BioRouter is an AI-powered integrated research environment for biomedical discovery, built by UCSF's Baranzini Lab. It unifies multiple LLM providers, AI agents, MCP-based extensions and customizable workflows behind one desktop app and one command-line tool, layered as interface → agent → extensions.
This tree holds everything written about BioRouter: end-user guides, subsystem design and reference documentation for developers, and the archived record of work that has already finished.
Two kinds of document live here, and the difference matters more than any other fact on this page.
- Living documentation is filed by subsystem at the top level. One folder per area —
providers/,security/,agent-loop/, and so on. These describe how BioRouter behaves now, and they are maintained. history/holds records of completed or abandoned work. Executed plans, closed review campaigns, finished stress tests, and a few designs that were removed or never built. It is kept so decisions stay auditable and so you can find out why a subsystem is shaped the way it is. It is explicitly not current guidance, and reading it as such will mislead you.
Every document carries a status in its header saying which it is. Trust that line over the filename, the folder, or your memory of the feature. A living document whose one section has rotted stays Current and carries a warning naming that section, rather than being restatused.
| If you want to… | Read |
|---|---|
| Install BioRouter and run a first task | biorouter in 5 minutes — or Installation and setup for the thorough path with institutional providers |
| Pick an LLM provider and model | Choosing a model provider |
| Use a Claude or ChatGPT subscription you already pay for, instead of an API key | Coding-agent providers — read its compliance page before any research data goes near one |
| Look up a command or flag | biorouter CLI command reference |
| Change a setting | Configuration file reference for config.yaml, Environment variables for per-invocation overrides |
| Decide how much autonomy the agent gets | Permission modes |
| Understand a cross-institution warning you just saw | Institutional affiliation |
| Resume, export or prune your past work | Managing sessions |
| Run several conversations at once, or delegate to a subagent you can watch | Workspace control |
| Work with your lab in Crew: chat, files and agents on a shared server | Crew user manual |
| Use Biorouter in a web browser, on your own machine or a shared host | Reaching Biorouter from a browser — then Headless Linux deployment if it should run as a server |
| Read or follow a private chat from a script, a dashboard or CI | Reaching a private chat from a script — the X-Caller-Provider header, and which routes honour it |
| Fix an error you are hitting right now | Common problems and fixes |
| Understand the codebase before changing it | System overview |
| Area | What it covers |
|---|---|
| getting-started | The end-user on-ramp: installing the app and CLI, connecting a provider, running a first biomedical task, managing sessions, and day-to-day usage habits. |
| architecture | The orientation-level map of the three layers and the crate and process boundaries, plus the agentic system explorer's account of how one request becomes context, tool work and a verified answer. |
| agent-loop | The reasoning loop itself — durable context, subagents, lifecycle hooks, tool routing — plus the designs behind its guardrails: command policy, sandboxing, checkpoints, session branching. |
| agent-drafter | The app-authoring MCP extension that builds BioRouter apps, and the frozen 100-spec corpus and runbook used to stress-test it. |
| apps-sdk | The contract behind BioRouter apps in three layers: the shipped reference, the v2 design of record, and the phase roadmap. |
| extensions | Built-in capabilities, user-installed MCP extensions, and skills, with a reference page for each capability plus an open investigation into Slack posting. |
| integrations | The opposite direction from extensions/: adapters that let another application host a Biorouter agent, starting with the @Biorouter persona for JupyterLab's Jupyter AI chat. |
| knowledge-base | The live working documents for the personal, LLM-maintained wiki: surveys of the ingestion pipeline and plans for extending it. |
| providers | Maintainer-facing integration references for individual LLM providers: registry wiring, credential contracts, selection surfaces and verification commands. Includes coding-agent providers — the two that run on the user's own Claude or ChatGPT subscription by driving a vendor CLI, with their tool bridge, child-isolation flags and the vendor-terms and PHI compliance position. |
| security | Agent autonomy, admin-imposed managed policy, credential storage, which providers are acceptable for patient and other sensitive data, and the institutional affiliation check behind cross-institution warnings. |
| workflows | Reusable workflow files that package instructions, extensions and model settings into one shareable session, plus the built-in cron scheduler. |
| crew | The Crew user manual: joining or hosting a lab workspace, teams and channels, messages and files, agent access, privacy, connections, the biorouter crew commands and server administration. Its design folder holds the broker protocol, the naming design, the interface specification and the CLI guide, for developers. |
| cli | The biorouter command-line surface: subcommands and flags, the interactive terminal UI, and the manual QA script that verifies both. |
| configuration | The complete reference for both configuration forms — persistent YAML files and the environment variables that override them. |
| desktop-ui | Exercising the Electron desktop app as a running program: launching and driving the dev GUI, and the behavior to check once it is in front of you. |
| deployment | Reaching Biorouter through a browser instead of the desktop app — biorouter serve on your own machine or on a shared Linux host: the access token, what exposing the port means, and the decisions behind the serving path. |
| releases | Shipping to users: the auto-update QA checklist, a local cross-compilation recipe, and the published per-version release notes. |
| troubleshooting | Known problems and their fixes, the diagnostics bundle, and how to file a useful bug report. |
| design | Visual design specifications and their rendered companions: brand marks, theme families, chat-group design spikes, the desktop UI overhaul, the proposed Astryx interface revision, and the browser-only design-system and boot-splash studios. |
| research | External research — studies of other agentic coding tools, written to inform BioRouter's own design. |
| testing | The properties this repository's tests must hold: the audit of process-global state the crates read and write, the ledger of unlocked readers behind a family of CI flakes, and the standing guards that keep fixed hazards fixed. |
| contributing | How this documentation tree itself is written and maintained: the house style every file follows, and the live register of unresolved problems found in it. |
history/ is the archive: 31 topic folders covering May to September 2026, almost all of which shipped. Read it to trace a decision, reconstruct what landed in a release, or decode an identifier like BR-43 in a commit message, never to learn what the code does today.
The largest campaigns in there:
| Campaign | What it records |
|---|---|
| agent-loop-review | The agentic-loop review: a loop walkthrough, a comparison against nine open-source coding agents, 28 sub-reports, and the 67-item BR-NN proposal register the rest of the tree cites. |
| agent-loop-campaign | The BR-1…BR-70 fix campaign that implemented those findings — wave conventions, regression gates and a dated merge log, across 86 commits. |
| knowledge-base-buildout | The founding design for the Knowledge feature and the six implementation plans that built it out in order. |
| agent-drafter-stress-test | A campaign driving a real model to build 100 agentic apps with Agent Drafter; the eight resulting drafter fixes shipped. |
| agent-drafter-testdrive-100 | A separate test drive against a 100-app spec corpus — per-app rubrics, three cross-cutting audits, and a six-wave remediation plan. |
| performance-2026-06 | A whole-app latency review against v1.86.0 plus an independent comparison against the jcode harness; nine fixes merged. |
| streaming-tool-call-ui-2026-07 | The July 2026 streaming tool-call campaign: why a tool card appeared late and already finished, the streaming implemented across fourteen providers that never streamed, and three QA rounds over the result. |
| biorouter-crew | The campaign that built Crew, 2026-09-21 to its merge on 2026-09-27: the research and plan, independent reviews, the redesign and naming work, four live QA rounds, the bounded evidence runs behind each acceptance claim, and the QA of the merged build that followed. |
| dashboard-mode | Four generations of design for a free-floating multi-chat canvas, and the record of its removal on 2026-07-18. The feature no longer exists. |
| mcp-apps-removal | The sandboxed iframe in which a third-party MCP server ran its own UI inside BioRouter, present since the first commit, never requested, and removed on 2026-09-08. The feature no longer exists; Agent Drafter's Built apps is a different one and stays. |
| legacy-architecture | Two superseded internals designs: a hand-written Extension trait framework that was never shipped, and the agent error model, whose two-tier policy still holds but whose every type name is gone. |
- Every file opens with a context header — a blockquote giving What this is, Status, and Audience — before any other content.
README.mdindex files are the exception: they open with a paragraph describing the folder's scope instead. - Status is one of three values:
Current,Historical record — <what completed, and when>, orSuperseded — <what changed, and where the current truth lives>. Anything dated, planned, or reporting completed work must carry one. - Folders are topic-specific and each carries a
README.mdlisting its documents with a one-line description each. - Filenames are kebab-case and name the document's purpose, not the process that produced it —
defects-found-and-fixed.md, notfindings.md.README.mdis the onlyALL_CAPSname. Dated reports carry an ISO date suffix when the date is load-bearing. - Where a document goes is governed by how this documentation is organized — the sorting rules, when a new folder is justified, and what to do when the rules do not fit. Read it before adding a document or creating a folder.
- What a document looks like inside is governed by documentation style; gaps and known problems in this tree are tracked in open documentation issues.
Start at how this documentation is organized. It answers where a document goes, when a new folder is warranted, and how to extend the system for a feature area that does not exist yet.
Decide first whether you are writing living documentation or a record of finished work — that choice picks the folder and it is the one thing readers rely on. Put living documentation in the subsystem folder it belongs to; put anything describing completed or abandoned work under history/. Then write the context header before the body, so the status is never left implicit. Finally, add a row for it in the owning folder's README.md, and check that every link you wrote resolves. If your document is the obvious answer to one of the arrivals in Start here above, add it there too.