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 |
| 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 |
| Resume, export or prune your past work | Managing sessions |
| Run BioRouter as a shared headless server | Headless Linux deployment |
| 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 | How BioRouter is extended — MCP extensions, platform extensions and skills — with a reference page for each built-in extension, plus an open investigation into Slack posting that has not been built. |
| 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. |
| security | Agent autonomy, admin-imposed managed policy, credential storage, and which providers are acceptable for patient and other sensitive data. |
| workflows | Reusable workflow files that package instructions, extensions and model settings into one shareable session, plus the built-in cron scheduler. |
| 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 | Running BioRouter as a shared server rather than a desktop app: building the Linux headless artifact, deploying it, and migrating secrets. |
| 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, 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. |
| 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: 25 topic folders covering May–July 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. |
| 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. |
| 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.