Get started
Core concepts.
The idea in one picture
- Extractors read your tools and write knowledge.
- Agents read that knowledge, then write code and open pull requests.
- A plan feeds agents one ticket at a time, and saves what each one learned.
Company
A company is a short name, like acme, for one org. Briar uses it in two places. It names your knowledge: the main blob for acme is knowledge:acme. It also names your logins: the Jira token for acme lives in JIRA_ACME_TOKEN.
$ briar extract --company acme --include pr-archaeology
You get a blob named knowledge:acme. With two companies, each one keeps its own knowledge and its own logins.
- In variable names, the company is upper case and dashes become underscores:
acme-cobecomesACME_CO. - The GitHub token is shared by all companies:
GITHUB_TOKENhas no company in its name. - Put
company = "acme"in.briar.tomland you can drop--companyfrom every command.
Knowledge blob and knowledge store
A knowledge blob is a piece of markdown text with a name. The name has two parts: a category, a colon, and the rest. In knowledge:acme the category is knowledge.
The knowledge store is where blobs are kept. There are two:
file(the default): one markdown file per blob, under./knowledge/. The blobknowledge:acmeis the file./knowledge/knowledge/acme.md.postgres: the same blobs in a database, with a history table. Use it when several hosts share knowledge. It needsBRIAR_DATABASE_URL.
These are the blob names you will see most:
| Blob | Written by | What is in it |
|---|---|---|
knowledge:acme | briar extract, or a runbook's default task | One section per extractor that found data. |
knowledge:acme.nightly | A runbook schedule with task: nightly | The same, for that one task. |
plan:q3 | briar plan build | The cards of plan q3 and their status. |
knowledge:acme.q3 | briar plan run | Notes the plan learned, added after each done card. The selector reads them. |
inventory:acme | A runbook with the inventory option on | Full structured data (JSON), for example every AWS resource. |
$ briar context list$ briar context get knowledge:acme$ briar context categories
You get the list of blobs, the text of one blob, and the categories in use (for example knowledge and plan).
context reads the file store unless you say otherwise
extract, agent and plan switch to Postgres on their own when BRIAR_DATABASE_URL is set. context does not. Pass --store postgres, set BRIAR_STORE=postgres, or put store = "postgres" in .briar.toml.Extractor
An extractor reads one kind of data from one tool and writes one section of markdown. For example, stale-prs lists pull requests that have been open too long. There are two kinds.
Scheduled extractors (23)
These run when you call briar extract or a runbook. They write to the company's knowledge blob. They cover PR history, open work, open and closed tickets, CI health, hot files, code rules, reviewers, deploys, cloud setup, meeting notes, and more.
$ briar extract --include stale-prs --stale-days 7
You get a section that lists every open PR older than 7 days. Leave out --include to run all 23. An extractor that cannot run (for example, no login for its tool) prints skipped and the rest go on.
Since 1.1.82 the example above updates only the stale PR section of knowledge:acme and keeps your other sections. Before 1.1.82 each run wrote the blob from scratch; there, add --blob-name knowledge:acme.stale to keep them.
Task-scoped extractors (4)
These run only inside an agent run, for the one ticket or PR the agent works on. You never call them by hand.
ticket-context: the full ticket, its acceptance criteria and comments (foragent implement).pr-review-context: the PR's review threads and comments (foragent prfix).meeting-context: matching Fireflies meeting notes, when a Fireflies login is set.slack-context: matching Slack threads, when Slack login variables are set. Slack is read only here: there is no scheduled Slack extractor.
Runbook
A runbook is a YAML file. It lists your companies, which extractors to run for each, and how often. It can also hold message channels, MCP servers and a git identity for agents. Think of it as a long briar extract command, saved in a file you can review.
# runbooks/acme.yamlversion: 1companies:acme:knowledge:store: filename: knowledge:acmeextract:- name: pr-archaeologyargs:pr_repo: [acme-co/acme-app]schedules:- task: nightlyevery: "day at 02:00"extract:- name: stale-prsargs:stale_repo: [acme-co/acme-app]
The top-level extract: list runs as a task named extractors, every day at 03:17. It writes knowledge:acme. The nightly schedule runs at 02:00 and writes knowledge:acme.nightly. Times are UTC.
$ briar runbook extract runbooks/acme.yaml$ briar runbook sweep runbooks/$ briar runbook serve runbooks/
extract runs one file once. sweep runs every *.yaml in a folder once. serve keeps running and fires each task at its time. Every field is on the runbook YAML page.
Agent and archetype
An agent is an AI loop. It reads a prompt, picks a tool, runs it, reads the result, and repeats. It stops when the job is done or after 30 turns (change this with --max-iter). Agents always run on Anthropic models. A plain install is enough. The [mcp] extra adds two small helper servers (see Install).
The tools an agent can use:
bash, for a short list of commands (git, gh, test and lint tools, make, and simple file commands). It refuses force-push, amend, rebase, squash,reset --hardandrm -rf.read_file,write_fileandedit_file, only inside its worktree.send_message, only when you pass--runbookand that runbook lists message channels (a PR comment, a Jira comment, a Slack channel, ...).- Tools from MCP servers, if you set any up.
An archetype is the role an agent plays: its instructions and its tools. There are five:
| Archetype | Job | How you run it |
|---|---|---|
engineer | Takes a ticket to a draft pull request. | briar agent implement, and each card of plan run |
pr-fixer | Answers open review threads on a PR. | briar agent prfix |
triager, pr-ci-fixer, pr-conflict-resolver | Sort issues, fix CI, solve merge conflicts. | Only inside a config made by briar scaffold implementation --archetype, not as a local command |
$ briar agent implement --ticket-key ACME-42 --tracker jira --dry-run$ briar agent prfix --pr 482 --branch fix/login --dry-run
You get the engineer's and the pr-fixer's prompts and tool lists, without a clone or a model call.
What an agent reads first
Before the loop starts, briar builds the prompt from three things:
- The archetype's instructions.
- Some sections of your knowledge. Briar looks in every blob whose name starts with
knowledge:acme, but keeps only the sections the archetype uses (table below). - The task-scoped extractors for this one job: the ticket, or the PR review threads, plus meeting notes and Slack threads when those logins are set.
| Archetype | Knowledge sections it reads |
|---|---|
engineer | codebase-conventions, code-hotspots, reviewer-profile, active-work, pr-archaeology, meeting-digest |
pr-fixer | codebase-conventions, code-hotspots, reviewer-profile, active-work, meeting-digest |
Other sections, like CI health, tickets or AWS, do not reach the coding agent. They are for you, for the plan steps, and for MCP hosts. The plan notes in knowledge:acme.q3 do not reach it either: the selector reads them.
Worktree
A worktree here is a fresh clone of your repo in a temp folder. The agent works only there and never touches your own checkout. agent implement clones the default branch (or --base-branch); agent prfix clones the PR's branch.
The folder is named like $TMPDIR/briar-agent-implement-.... Briar deletes it after the run. It keeps it if the run failed, or if you passed --keep-worktree.
$ briar agent implement --ticket-key ACME-42 --tracker jira --keep-worktree -v
You get a real run, and the clone stays on disk. With -v the log prints where it is.
Plan, card and selector
A plan is a list of cards made from a board. A card is one ticket, with a summary, what is in and out of scope, risks, what it depends on, and a status: pending, in_progress, done or blocked. The plan is saved as a blob, for example plan:q3.
The selector is the AI step that picks what to do next. It reads the cards, the knowledge, and past decisions from the journal. Then it picks a card, asks for a replan, says the plan is complete, or says it is blocked. It is not a fixed order.
$ briar plan build jira:KAN --name q3 --llm anthropic$ briar plan status q3$ briar plan next q3 --llm anthropic$ briar plan run q3 --llm anthropic --tracker jira --tracker-project KAN --limit 1
buildreads board KAN and savesplan:q3.statusshows the cards by state.nextprints what the selector would pick. It changes nothing.rundoes one card: the selector picks it, the engineer agent implements it, and the card becomesdoneorblocked. After a done card, a short note goes intoknowledge:acme.q3.
Journal
The journal is a saved log of decisions. Only briar plan run and briar scaffold write to it. A plain agent implement or agent prfix does not: it prints its result to your terminal instead.
Each run is one session, saved under ./journal/ with a 12-character ID. A plan run session holds each selector pick and its reason, each replan, and each card's start, done or failed result.
$ briar journal list --command plan.run --limit 5$ briar journal show 3f9a1c2b7d4e$ briar journal export 3f9a1c2b7d4e --as json --out last-run.json
You get the five newest plan runs, one session as markdown, and the same session as a JSON file. Set BRIAR_JOURNAL=off to turn the journal off.
Credential store
The credential store is where briar auth login saves what you paste. The default, envfile, is the file ~/.config/briar/secrets.env, readable only by you. Other stores are aws-secretsmanager, ssm and vault. Pick one with --cred-store or BRIAR_DEFAULT_STORE.
Every time briar starts, it loads secrets.env into its environment. A variable you already exported in your shell wins over the file.
$ briar auth login jira-token --company acme$ briar auth list --company acme$ briar auth status jira-token --company acme
You get JIRA_ACME_URL, JIRA_ACME_EMAIL and JIRA_ACME_TOKEN saved. The next two commands show which variables are set. They print names only, never values.
Two different stores
BRIAR_DEFAULT_STORE picks the first, BRIAR_STORE picks the second.Where a setting comes from
Most settings can come from four places. When more than one sets a value, the first one in this list wins:
- A flag on the command line.
- An environment variable:
BRIAR_COMPANYorBRIAR_STORE. - The project config:
.briar.toml, or a[tool.briar]table inpyproject.toml. Briar looks in this folder and then each parent folder. - The built-in default.
Owner and repo have one more source: if nothing else sets them, briar reads them from your git origin remote.
$ BRIAR_COMPANY=globex briar config show$ briar config show
You get a table of settings, each with its value and source, such as env (BRIAR_COMPANY), config (.briar.toml) or inferred (git origin). The first line shows the env variable winning over the file. See Configuration for every key.
How the pieces fit
- A runbook (or a plain
extract) runs extractors. - Extractors write knowledge blobs to the store.
- A plan turns a board into cards, using that knowledge.
- The selector picks a card. The agent does it in a worktree. Each reads the parts of the knowledge it needs.
- Each
plan runwrites to the journal, and the next selector turn reads it.
The short version
Glossary
| Word | Meaning |
|---|---|
| archetype | The role an agent plays: its instructions and its tools. Example: engineer. |
| blob | One named piece of markdown in the knowledge store. Example: knowledge:acme. |
| board | A Jira board or a GitHub Projects board. plan build reads one. |
| card | One ticket inside a plan, with a status: pending, in_progress, done or blocked. |
| category | The part of a blob name before the colon. knowledge:acme is in category knowledge. |
| company | A short name for one org. It names blobs and login variables. |
| credential store | Where briar auth login saves your logins. Default: a local file. |
| dry run | An agent run that prints the prompt and tools, with no clone and no model call. |
| extractor | A reader for one kind of data, like merged PRs or open tickets. |
| journal | A saved log of what plan run or scaffold decided. |
| knowledge store | Where blobs live: local files or Postgres. |
| MCP | Model Context Protocol. A standard way for AI tools to call other tools. |
| plan | A saved, ordered list of cards made from a board. |
| runbook | A YAML file that says which extractors to run, for which company, and when. |
| selector | The AI step in plan run that picks the next card. |
| task-scoped extractor | An extractor that runs only inside an agent run, for one ticket or PR. |
| worktree | A fresh clone of your repo in a temp folder. The agent works only there. |