Reference
Usage flows.
acme, repo acme-co/acme-app, Jira project ACME and board jira:KAN. Change them to yours.Before you start
briar init --company acme. Then --company, --owner and --repo come from .briar.toml and you can leave them out. Each flag is explained on its command page in the CLI reference.1. Onboard a repo
Goal: go from nothing to a knowledge blob that describes your repo and your open tickets.
- Install briar and create the project config.You get the$ pip install briar-cli$ briar init --company acme
briarcommand and a.briar.tomlwith company, owner and repo. Agent runs (flows 2 to 4) work on this plain install. The[mcp]extra only adds two small helper servers. Without it, each agent run logs one warning. - Log in to GitHub and Jira. Each command asks you to paste a token.You get$ briar auth login github-pat --company acme$ briar auth login jira-token --company acme
GITHUB_TOKEN,JIRA_ACME_URL,JIRA_ACME_EMAILandJIRA_ACME_TOKENin~/.config/briar/secrets.env. - Check your setup.You get one line per check. Fix anything marked$ briar doctor
fail. Awarnfor the AI key is fine for now. - Run every extractor, and name your Jira project for the two ticket extractors.You get$ briar extract --ticket-project ACME --ticket-archaeology-project ACME
knowledge:acme, with one section per extractor that found data. An extractor that cannot run (for example Fireflies, with no login yet) printsskipped. That is expected. - Read the top of the result.You get the first 40 lines: the title and the first sections.$ briar context get knowledge:acme | head -40
extract keeps the other sections (1.1.82 and later)
briar extract run with two --include flags updates those two sections of knowledge:acme and keeps the rest. Before 1.1.82 the blob then held only those two sections; there, write new sections to their own blob with --blob-name, as below. The coding agent looks in every blob whose name starts with knowledge:acme, for the sections its role uses (see what an agent reads).Connect more tools
Add a login for each tool you use, then extract its data. Each login is for one company.
$ briar auth login aws-static --company acme$ briar auth login fireflies --company acme$ briar extract --include aws-infra --include meeting-digest --since-days 14 --blob-name knowledge:acme.cloud
You get a second blob, knowledge:acme.cloud, with your AWS setup and a digest of the last 14 days of Fireflies meetings. knowledge:acme stays as it was. The coding agent uses the meeting digest. The AWS section is for you and for MCP hosts; the agent does not read it. Other logins: aws-sso, github-device, bitbucket-app-password, jira-session (a browser cookie instead of a token) and linear-api-key.
Slack has no auth login target. Agents read it live, from a browser session. Add these two lines to ~/.config/briar/secrets.env:
SLACK_ACME_TOKEN=xoxc-your-tokenSLACK_ACME_COOKIE_D=xoxd-your-cookie
You get Slack threads in agent prompts when you pass --slack-query (or by default, matched on the ticket key or PR).
2. Ship one ticket
Goal: Jira ticket ACME-42 becomes a draft pull request, with tests run before the push.
- Make sure the knowledge is fresh. If you ran flow 1 today, skip this step.You get a new$ briar extract --ticket-project ACME --ticket-archaeology-project ACME
knowledge:acme. The agent leans most on its codebase conventions section: your test command, linter and formatter. - Preview the run. This is free.You get the full prompt, the tool list, and the ticket section with its size. No clone and no model call happen.$ briar agent implement --ticket-key ACME-42 --tracker jira --dry-run
- Run it for real. Set
ANTHROPIC_API_KEYfirst.The agent clones your default branch into a temp folder. It makes a branch ($ briar agent implement --ticket-key ACME-42 --tracker jirachore/acme-42), changes the code, and runs your tests. It pushes only when they pass, then opens a draft PR. You get its final message, the PR link, and the list of commits in your terminal. - Review the draft PR like any other. If the agent found an unclear acceptance criterion, it stops and asks on the ticket instead of guessing.
For a whole board, use flow 4.
3. Answer a review
Goal: a reviewer left comments on PR 482 (branch fix/login). The agent fixes each one and replies.
- Preview what the agent will see.You get the prompt, with a section that holds the PR's review threads and comments.$ briar agent prfix --pr 482 --branch fix/login --dry-run
- Run it.The agent clones the PR branch. It makes one commit per review thread and pushes. Then it replies on each thread with the commit SHA. It never force-pushes, amends, rebases or squashes. A thread that only asks a question gets a reply and no commit.$ briar agent prfix --pr 482 --branch fix/login
- Add meeting notes when the review was talked about in a call. This needs a Fireflies login.You get the matching meeting notes in the prompt. Without$ briar agent prfix --pr 482 --branch fix/login --meeting-query "login retry"
--meeting-query, briar searches foracme-co/acme-app#482. - Let the agent post a note to Jira or Slack when it is done.You get a$ briar agent prfix --pr 482 --branch fix/login --runbook runbooks/acme.yaml
send_messagetool bound to the channels in that runbook'smessages:block.
What prfix does not do
pr-ci-fixer agent. It is told to skip a PR that is approved, has green checks, and has only positive comments.4. Work a board
Goal: turn Jira board KAN into a plan, then ship it card by card.
- Refresh knowledge, so the plan and the agent start from facts.You get an up-to-date$ briar extract --ticket-project KAN --ticket-archaeology-project KAN
knowledge:acme, with the open and closed tickets of project KAN. - Build the plan.You get$ briar plan build jira:KAN --name q3 --with-knowledge --llm anthropic
plan:q3: one card per ticket (up to 50), each with scope, risks and what it depends on. - Look at it before you spend anything.You get the plan text, the cards by state, and the card the selector would pick next, with its reason. Nothing changes yet.$ briar plan show q3$ briar plan status q3$ briar plan next q3 --llm anthropic
Start small, then go wide
- Preview one card for free. Use the card key from
plan next.You get the prompt the agent would get for that card.$ briar agent implement --ticket-key KAN-7 --tracker jira --dry-run - Ship exactly one card.You get one draft PR, from the card's branch (built without$ briar plan run q3 --llm anthropic --tracker jira --tracker-project KAN --limit 1
--llm, for KAN-7:chore/kan-7), against the card's parent branch. The card becomesdoneorblocked, and a summary prints at the end. Check the PR and the cost before you go on. - Run the rest, and keep going when a card fails.You get one draft PR per finished card. A failed card is marked$ briar plan run q3 --llm anthropic --tracker jira --tracker-project KAN --continue-on-failure
blockedand the loop moves on. It stops when the selector says the plan is complete or blocked. - Watch progress and what the plan learned.You get the cards by state, and the notes added after each done card.$ briar plan status q3$ briar context get knowledge:acme.q3
Two flags people forget
plan run uses GitHub Issues as the tracker unless you say otherwise. For a Jira board, pass --tracker jira --tracker-project KAN, or put tracker = "jira" in .briar.toml. To preview the whole loop, use plan run --dry-run on 1.1.81 or later: it saves nothing. Before 1.1.81 it marked the picked cards done, so use plan next and agent implement --dry-run there.5. Keep knowledge fresh on a schedule
Goal: refresh knowledge:acme every morning, with no cron job, and hear about it when a run fails.
- Write a runbook.You get a file that runs three extractors every day at 07:00 UTC. The task name# runbooks/acme.yamlversion: 1companies:acme:knowledge:store: filename: knowledge:acmeschedules:- task: extractorsevery: "day at 07:00"extract:- name: pr-archaeologyargs:pr_repo: [acme-co/acme-app]- name: codebase-conventionsargs:conventions_repo: [acme-co/acme-app]- name: active-ticketsargs:tracker: jiraticket_project: [ACME]
extractorsmakes it writeknowledge:acme. Any other task name writesknowledge:acme.<task>, which agents read butplan build --with-knowledgedoes not. - Check that every login it needs is set.You get one line per extractor. A line with$ briar secrets doctor --examples runbooks/
MISSINGnames the variable to set. The command exits 1 if anything is missing. - Run it once now.You get a fresh$ briar runbook extract runbooks/acme.yaml
knowledge:acmeand a table row per task: written, skipped (no change), or failed. - Turn on failure alerts. Briar sends one when a runbook task fails.You get a Slack message for each failed task. Other sinks are$ export BRIAR_NOTIFY_SINKS=slack$ export SLACK_ACME_WEBHOOK_URL=https://hooks.slack.com/services/T000/B000/XXXX
email,pagerdutyandtelegram; list several with commas. - Start the scheduler and leave it running.You get a process that loads every$ briar runbook serve runbooks/
*.yamlin the folder and runs each task at its time. It waits for the first time; it does not run at start. Keep it alive with your usual tool (systemd, tmux, a container). - Optional: look at it in a browser.You get a read-only page at$ briar dashboard --examples runbooks/
http://127.0.0.1:8080with the schedules, host health and GitHub API quota.
Also keep a full AWS inventory
The knowledge blob keeps AI prompts small, so it holds counts, not every resource. To keep the full list too, turn on the inventory option in the runbook:
knowledge:store: filename: knowledge:acmeconfig:inventory: "true"
$ briar runbook extract runbooks/acme.yaml$ briar context list --prefix inventory:$ briar context get inventory:acme | jq -r '.sections[].title'
You get an extra blob, inventory:acme, with the full data in JSON. It is only rewritten when something changed. For a one-off dump, use briar extract --include aws-infra --aws-extract-service tagging-inventory --out-json acme-aws.json.
6. Feed Claude Code or an MCP host
Goal: let the AI tools you already use know what briar knows.
- Give Claude Code a pointer to your knowledge.You get the full text in$ briar extract --include codebase-conventions --include review-nits \--merge-claude-md --blob-name knowledge:acme.claude
.briar/knowledge/acme.md, and a short index in./CLAUDE.mdthat tells Claude Code when to read it. The index sits between two markers. A re-run replaces only that block, so your own text in the file stays.--blob-namekeeps your mainknowledge:acmeas it was. - Or share briar as MCP tools. Install the extra first.You get an MCP server on stdio. Your MCP host starts it for you; add it to the host's config. For Claude Code, that is a$ pip install "briar-cli[mcp]"$ briar mcp serve
.mcp.jsonfile in your repo:The host can then list and read blobs, and run extracts. Tools that change things only act when called with{"mcpServers": {"briar": { "command": "briar", "args": ["mcp", "serve"] }}}confirm=true; without it they show a preview. - Or chat with briar in your terminal.You get an assistant that uses the same MCP tools. It asks you before anything that changes data.$ briar chat --llm anthropic
To reach the server from another machine, see MCP over HTTP.
7. Audit what a plan did
Goal: after a plan run, see what it picked, why, and what happened to each card.
- Find the session.You get the five newest plan runs, newest first. Each line has the session ID, the plan and repo, the number of decisions, and the start time.$ briar journal list --command plan.run --limit 5
- Read it.You get a markdown timeline: each selector pick and its reason, each card start and its done or failed result, any replan, and why the run stopped.$ briar journal show 3f9a1c2b7d4e
- See where the cards ended up.You get done, in progress, blocked and pending cards. Blocked cards show the reason from their last try.$ briar plan status q3
- Keep a copy, or share it.You get the whole session in a JSON file.$ briar journal export 3f9a1c2b7d4e --as json --out q3-run.json
- Fix a card by hand if needed.You get card$ briar plan advance q3 --card KAN-7 --status pending
KAN-7back in the queue, so the nextplan runcan pick it again.
Plain agent runs are not in the journal
plan run and scaffold write journal sessions. A plain agent implement or agent prfix prints its final message and commit list to your terminal. Save that output if you need a record.8. A full day with briar
Put together, the flows above make one day of work:
- Morning: the scheduler from flow 5 has refreshed
knowledge:acme. - Build or update the plan for the sprint board (flow 4) and ship one card.
- Answer review comments on yesterday's PRs (flow 3).
- Ship the rest of the board with
--continue-on-failure. - End of day: read the journal (flow 7) and unblock any card that needs a person.
Where to go next
- Recipes: short answers to single questions.
- briar extract: every extractor and flag.
- Runbook YAML: every field, including the inventory option.