Reference
Recipes.
briar init --company acme in your repo, so the company and repo come from .briar.toml.How do I ...
- set up one repo, start to finish?
- change how far back briar looks?
- leave out bots, or keep only some people?
- pass several repos, projects or filters?
- use Bitbucket instead of GitHub?
- use Linear instead of Jira?
- read GCP or Azure instead of AWS?
- refresh several companies on a schedule?
- keep knowledge in Postgres?
- get JSON for scripts?
- stop CI when a login is missing?
- try an agent without spending money?
- pick the AI model?
- set the name on the agent's commits?
- look at the agent's clone after a run?
- run prfix on every open PR, every hour?
- serve MCP over HTTP?
- turn telemetry off?
- do the other small things?
One rule for every extract recipe
briar extract updates only the sections of the extractors it ran and keeps the rest of knowledge:acme, so each recipe below can run on its own. Before 1.1.82 it replaced the whole blob; there, add --blob-name knowledge:acme.extra to keep the rest. The coding agent looks in every blob whose name starts with knowledge:acme, for the sections its role uses.Set up one repo, start to finish
Goal: a repo and a Jira board, from zero to three draft pull requests.
1. Log in
$ briar auth login github-pat --company acme$ briar auth login jira-token --company acme$ briar auth list --company acme
You get your GitHub and Jira logins saved. The last line lists the variables that are set, names only.
2. Extract
$ briar extract --tracker jira \--ticket-project KAN \--ticket-archaeology-project KAN
You get knowledge:acme with every extractor that can run: PR history, conventions, CI, open and closed tickets of project KAN, and more. Every later step reads it.
3. Build the plan
$ briar plan build jira:KAN --name q3 --llm anthropic --with-knowledge
You get plan:q3: one card per ticket on board KAN, each with scope, out of scope and risks, written with your knowledge in mind.
4. Run three cards
$ briar plan run q3 --llm anthropic \--tracker jira --tracker-project KAN \--limit 3
You get up to three draft PRs. For each card the selector picks it, the agent implements it, and a note goes into knowledge:acme.q3.
Always use --limit on your first runs
--limit lets you check cost and quality before you let it run the whole board.Change how far back briar looks
$ briar extract --include code-hotspots --include revert-signals --since-days 30
You get both sections built from the last 30 days of commits. --since-days feeds every extractor that looks at history. Their own defaults differ: code-hotspots 30, defect-hotspots 90, revert-signals 90, commit-message-quality 90 and meeting-digest 7.
Other size knobs work the same way, per repo:
# read up to 200 items or commits per repo, keep the top 5$ briar extract --include code-hotspots --max 200 --top-n 5# sample the 40 most recent PRs per repo$ briar extract --include review-nits --sample 40# call a PR stale after 7 days instead of 14$ briar extract --include stale-prs --stale-days 7
You get smaller or larger sections. A per-extractor flag, like --hotspots-since-days 90, wins over the shared one for that extractor only. It still works, but prints a note that points you to the shared flag. See them all with briar extract --advanced-help.
Leave out bots, or keep only some people
# drop PRs opened by bots$ briar extract --include pr-archaeology --include active-work \--authors-block "dependabot[bot]" --authors-block "renovate[bot]"# keep only PRs assigned to alice or bob$ briar extract --include active-work \--assignees-allow alice --assignees-allow bob
You get sections without the bot PRs, or with only alice's and bob's work. These four filters apply to pr-archaeology and active-work.
- Use logins (GitHub usernames), not display names. Quote names with brackets, like
"dependabot[bot]". - An allow list keeps only matches. A block list drops matches. With both, a PR must be allowed and not blocked.
- Bitbucket PRs have no assignees. An assignee allow list drops all of them.
Pass several repos, projects or filters
Repeat the flag, once per value. There is no comma form: --repo a,b is read as one repo named a,b.
Several repos, projects and AWS services
$ briar extract \--include pr-archaeology --include active-work \--include active-tickets --include aws-infra \--repo acme-co/acme-app --repo acme-co/acme-api \--authors-block "dependabot[bot]" --authors-block "renovate[bot]" \--ticket-project ACME --ticket-project KAN \--aws-extract-service ecs --aws-extract-service rds \--aws-extract-service logs
You get PR history and open work for two repos (no bot PRs), open tickets for two Jira projects, and three AWS services. The shared --repo feeds every repo-based extractor you include.
Scaffold with several sources
$ briar scaffold implementation \--prefix acme-onerror \--source sentry --source github --source aws \--sentry-org acme \--sentry-project backend --sentry-project worker \--sentry-environment prod --sentry-environment staging \--sentry-level error --sentry-level fatal \--sentry-secret-id 7c1e4f2a-3b9d-4e8a-9f10-2d6c5b8a1e43 \--auth-mode pat --github-secret-id 0b6d2e9f-1a4c-4f7e-8d3b-6c5a9e2f1d07 \--owner acme-co --repo acme-app \--aws-services ecs --aws-services rds
You get one JSON config on stdout that reads from Sentry (two projects, two environments, two levels), GitHub and AWS. The secret IDs are the IDs of secrets you stored for the orchestrator that will run this config.
The same lists in a runbook
extract:- name: pr-archaeologyargs:pr_repo: [acme-co/acme-app, acme-co/acme-api]pr_authors_block: ["dependabot[bot]", "renovate[bot]"]- name: active-ticketsargs:tracker: jiraticket_project: [ACME, KAN]
In a runbook, a repeated flag becomes a YAML list under the extractor's args:. The shared names (repo, since_days, max, ...) work there too.
Four repo extractors in one pass
$ briar extract \--include reviewer-profile --include code-hotspots \--include github-deployments --include codebase-conventions \--repo acme-co/acme-app --repo acme-co/acme-api \--sample 40 --top-n 6 --since-days 45 --max 200
You get reviewers, hot files, deploys and conventions for both repos. The shared flags go to each extractor that has that knob: --sample to the reviewer PR sample, --top-n to the reviewer and hotspot lists, --since-days and --max to the hotspot scan.
Open tickets and closed tickets, different projects
$ briar extract --tracker jira \--include active-tickets \--ticket-project ACME --ticket-project KAN \--ticket-project BILLING --ticket-project GROWTH \--include ticket-archaeology \--ticket-archaeology-project ACME \--ticket-archaeology-project KAN \--max 150
You get open tickets from four projects, and closed-ticket history from two of them. active-tickets and ticket-archaeology take separate project lists. --max 150 caps closed tickets per project (default 100).
Wide AWS inventory plus a meeting digest
$ briar extract \--include aws-infra --cloud aws \--aws-extract-region us-east-1 \--aws-extract-service ecs --aws-extract-service lambda \--aws-extract-service logs --aws-extract-service rds \--aws-extract-service sqs --aws-extract-service tagging-inventory \--include meeting-digest --meeting fireflies \--meeting-attendee-allow [email protected] \--meeting-attendee-allow [email protected]
You get every AWS service briar knows in us-east-1. The first five give detail on one service each. tagging-inventory counts every tagged resource of every service in the region (untagged ones are not seen). You also get the meetings where alice or bob took part.
Dashboard: pick the disk to watch
$ briar dashboard --host 0.0.0.0 --port 8080 \--examples runbooks/ \--disk-path /var/lib/briar
You get the status page on port 8080 of every address, with disk use for /var/lib/briar. --disk-path takes one path (default /). Before you use --host 0.0.0.0, check your firewall: the page has no login.
Scaffold: filters per source
$ briar scaffold implementation \--prefix acme-triage \--source github --source jira \--owner acme-co --repo acme-app \--auth-mode pat --github-secret-id 0b6d2e9f-1a4c-4f7e-8d3b-6c5a9e2f1d07 \--github-authors-block "dependabot[bot]" \--github-assignees-allow alice --github-assignees-allow bob \--jira-project ACME --jira-project KAN \--jira-secret-id 5e8a1c3d-9b2f-4a6e-8c7d-1f0e2b3a4c5d \--jira-authors-allow [email protected] \--jira-assignees-allow [email protected] \--out scaffolds/acme-triage.json
You get scaffolds/acme-triage.json, reading GitHub issues and two Jira projects, each with its own filters. The shared --authors-allow, --authors-block, --assignees-allow and --assignees-block apply to every source. The per-source ones (hidden from -h) win for their source, and print a note that points to the shared flags.
Scaffold: webhook events and labels
$ briar scaffold implementation \--prefix acme-onlabel \--source github \--owner acme-co --repo acme-app \--auth-mode pat --github-secret-id 0b6d2e9f-1a4c-4f7e-8d3b-6c5a9e2f1d07 \--trigger-kind github_webhook \--webhook-events issues.opened --webhook-events issues.labeled \--webhook-labels briar --webhook-labels needs-agent \--out scaffolds/acme-onlabel.json
You get a config whose agent starts only when an issue is opened or labeled, and only for issues with the label briar or needs-agent. For Bitbucket, use --trigger-kind bitbucket_webhook with --bitbucket-webhook-events and --bitbucket-webhook-labels.
Every flag you can repeat
--include, --repo, --authors-allow, --authors-block, --assignees-allow, --assignees-block, --ticket-project, --ticket-archaeology-project, --aws-extract-service, --meeting-attendee-allow, and the per-extractor repo and filter flags such as --pr-repo and --active-authors-block. scaffold: --source, the four shared filters, --jira-project, --sentry-project, --sentry-environment, --sentry-level, --aws-services, the per-source filters, and --webhook-events, --webhook-labels, --bitbucket-webhook-events, --bitbucket-webhook-labels.Use Bitbucket instead of GitHub
$ briar auth login bitbucket-app-password --company acme$ briar extract --provider bitbucket --include pr-archaeology --repo acme-co/acme-app$ briar agent prfix --provider bitbucket --pr 482 --branch fix/login --dry-run
You get your Bitbucket workspace, username and app password saved, then PR history from Bitbucket, then an agent preview for a Bitbucket PR. In --repo, the part before the slash is the Bitbucket workspace.
- Put
provider = "bitbucket"under[repo]in.briar.tomland you can drop--provider. - For Bitbucket issues, add
--tracker bitbucket-issues. - If an extractor cannot run with Bitbucket, extract prints
skippedfor it and goes on. agent implementon Bitbucket pushes the branch but does not open the pull request. The agent is told to open it withcurl, and its bash tool blockscurl. Open the PR yourself from the pushed branch. Draft PRs open fine on GitHub.- The prfix steps briar gives the agent use the GitHub CLI
gh. On Bitbucket, read the--dry-runprompt before a real run.
Use Linear instead of Jira
$ briar auth login linear-api-key --company acme$ briar extract --tracker linear --include active-tickets --ticket-project ACME$ briar agent implement --tracker linear --ticket-key ACME-42 --dry-run
You get LINEAR_ACME_TOKEN saved, the open issues of Linear team ACME, and an agent preview for issue ACME-42. The team is the part of the issue key before the dash. Put tracker = "linear" in .briar.toml to drop --tracker. Note that plan build reads only Jira and GitHub Projects boards.
Read GCP or Azure instead of AWS
The aws-infra extractor also reads GCP and Azure. Pick the cloud with --cloud. The flags keep their AWS names: --aws-extract-profile holds the GCP project ID or the Azure subscription ID, and --aws-extract-region holds the region.
# GCP: log in with Application Default Credentials first$ pip install "briar-cli[gcp]"$ gcloud auth application-default login$ briar extract --include aws-infra --cloud gcp \--aws-extract-profile acme-prod --aws-extract-region us-central1# Azure: log in with the Azure CLI first$ pip install "briar-cli[azure]"$ az login$ briar extract --include aws-infra --cloud azure \--aws-extract-profile 3f2b8c1e-7d4a-4e9b-a1c2-5d6e7f8a9b0c \--aws-extract-region eastus
You get a section for GCP project acme-prod or for the Azure subscription. Always pass the region: the default, us-east-1, is an AWS region.
Refresh several companies on a schedule
Goal: one host refreshes knowledge for two companies every day.
1. Write the runbook
# runbooks/all.yamlversion: 1companies:acme:knowledge: { store: file, name: knowledge:acme }schedules:- task: extractorsevery: "day at 07:00"extract:- name: pr-archaeologyargs: { pr_repo: [acme-co/acme-app, acme-co/acme-api] }- name: active-ticketsargs: { tracker: jira, ticket_project: [ACME] }- name: aws-infraargs: { aws_extract_region: us-east-1 }globex:knowledge: { store: file, name: knowledge:globex }schedules:- task: extractorsevery: "day at 07:30"extract:- name: pr-archaeologyargs: { pr_repo: [globex/core] }- name: code-hotspotsargs: { hotspots_repo: [globex/core], hotspots_since_days: 14 }- task: open-workevery: "1 hour"extract:- name: active-workargs: { active_repo: [globex/core] }
Each company has its own knowledge and times (UTC). The task extractors writes knowledge:acme and knowledge:globex. The hourly task writes knowledge:globex.open-work.
2. Run the scheduler, with failure alerts
$ export BRIAR_NOTIFY_SINKS=slack$ export SLACK_ACME_WEBHOOK_URL=https://hooks.slack.com/services/T000/B000/AAAA$ export SLACK_GLOBEX_WEBHOOK_URL=https://hooks.slack.com/services/T000/B000/BBBB$ briar runbook serve runbooks/
You get a process that runs every task at its time. When a task fails, a message goes to that company's Slack webhook. The messages: block of a runbook is a different thing: it lists channels an agent may post to.
3. Add the dashboard
$ briar dashboard --examples runbooks/ --log-file /var/log/briar/scheduler.log
You get a read-only page at http://127.0.0.1:8080. It shows the schedules from the YAML files, GitHub API quota, the deployed commit, and host health (disk, memory, load). Scheduler health and recent runs come from the log file you pass with --log-file (default /var/log/briar/scheduler.log).
Keep knowledge in Postgres
Goal: two hosts share knowledge through Postgres. One runs the scheduler, the other runs agents.
1. Create the tables once
Briar does not create its tables on first use. Run this once, with the same Python that has briar, and an admin connection string:
$ export ADMIN_DATABASE_URL="postgresql://admin:<admin password>@db.internal:5432/briar"$ export BRIAR_KB_PASSWORD="$(openssl rand -hex 24)"$ python3 -c 'import os; from briar.storage.postgres import StorePostgres; StorePostgres.bootstrap_admin(os.environ["ADMIN_DATABASE_URL"], os.environ["BRIAR_KB_PASSWORD"])'
You get two tables (briar_knowledge and briar_knowledge_history) and a role briar_kb that can only read and write them. It is safe to run again.
2. Scheduler host
# /etc/briar/runbooks/acme.yaml (the knowledge part)companies:acme:knowledge:store: postgresname: knowledge:acme
$ export BRIAR_DATABASE_URL="postgresql://briar_kb:${BRIAR_KB_PASSWORD}@db.internal:5432/briar"$ briar runbook serve /etc/briar/runbooks/
You get the scheduler writing to Postgres. A runbook uses Postgres only when it says store: postgres; the variable alone does not switch it. For a different database per company, set BRIAR_ACME_DATABASE_URL.
3. Agent host
$ export BRIAR_DATABASE_URL="postgresql://briar_kb:${BRIAR_KB_PASSWORD}@db.internal:5432/briar"$ briar plan run q3 --llm anthropic \--tracker jira --tracker-project KAN \--runbook /etc/briar/runbooks/acme.yaml$ briar context --store postgres get knowledge:acme.q3
You get the plan loop reading the knowledge the scheduler keeps fresh. extract, agent and plan use Postgres on their own once BRIAR_DATABASE_URL is set. context needs --store postgres (or BRIAR_STORE=postgres).
The journal stays on each host
./journal/. Read it on the host that ran plan run.Get JSON for scripts
Commands that print a table or a record take the global --format flag. It works anywhere on the line, even after a subcommand.
Read values with jq
# card counts by state$ briar plan status q3 --format json | jq '.counts'# keys of the blocked cards$ briar plan status q3 --format json | jq -r '.blocked[].key'# every knowledge blob, by name$ briar context list --prefix knowledge: --format json | jq -r '.[].name'# the checks that are not ok$ briar doctor --format json | jq -r '.[] | select(.status != "ok") | .check'
You get plain values to use in a script. The plan status JSON has counts, then one list per state: done, in_progress, blocked and pending.
Stop a script when knowledge is missing
$ n=$(briar context list --prefix knowledge:acme --format json | jq 'length')$ [ "$n" -gt 0 ] || { echo "no knowledge for acme yet"; exit 1; }
You get a script that stops early when nothing has been extracted.
Output formats
--format takes table (the default for lists), json, yaml, csv and quiet. quiet prints almost nothing: use it when you only need the exit code. journal list and extract print plain text whatever you pass.Stop CI when a login is missing
briar secrets doctor reads every runbook in a folder. It checks each extractor and each message channel for the variables it needs, and exits 1 if any are missing.
GitHub Actions check
# .github/workflows/briar-check.ymlname: briar checkon: [push]jobs:secrets:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4- run: pip install briar-cli- name: Every runbook has its loginsenv:GITHUB_TOKEN: ${{ secrets.BRIAR_GH }}JIRA_ACME_URL: ${{ secrets.JIRA_ACME_URL }}JIRA_ACME_EMAIL: ${{ secrets.JIRA_ACME_EMAIL }}JIRA_ACME_TOKEN: ${{ secrets.JIRA_ACME_TOKEN }}run: briar secrets doctor --examples runbooks/
You get a failed job when a runbook in runbooks/ needs a variable that is not set. The log names it. Values are never printed.
Exit codes
0 on success and 1 on a runtime error or a missing login. It exits 2 on a usage error (unknown command or bad flag) or an unexpected crash, and 130 when you press Ctrl-C. A CI step needs nothing more to fail on them.Try an agent without spending money
Go from free to wide in three steps.
1. Dry run: no model call
$ briar agent implement --ticket-key ACME-42 --tracker jira \--runbook runbooks/acme.yaml --dry-run
You get the full prompt, the tool list (with send_message, if the runbook has message channels), and the size of each ticket section. There is no clone and no model call.
2. One paid card, with a turn cap
$ briar plan run q3 \--tracker jira --tracker-project KAN \--llm anthropic --model claude-sonnet-4-6 \--limit 1 --max-iter 20
You get one card done or blocked, with at most 20 agent turns. This is your test of quality and real cost per card.
3. Go wide, and keep going past failures
$ briar plan run q3 \--tracker jira --tracker-project KAN \--llm anthropic --continue-on-failure
You get the whole plan worked. A failed card is marked blocked and the loop moves on.
plan run --dry-run saves nothing (1.1.81 and later)
plan run --dry-run passes --dry-run to each card's agent and keeps the plan as it was. The selector still calls the model, so it is not free. Before 1.1.81 the picked card was marked done; put it back with briar plan advance q3 --card KAN-7 --status pending.Pick the AI model
# agents: an Anthropic model (default claude-sonnet-4-5)$ briar agent implement --ticket-key ACME-42 --tracker jira --model claude-sonnet-4-6# plan with OpenAI (needs the [openai] extra and OPENAI_API_KEY)$ briar plan build jira:KAN --name q3 --llm openai --model gpt-4o# chat with Gemini (needs the [gemini] extra and GEMINI_API_KEY)$ briar chat --llm gemini --model gemini-2.5-pro# plan with AWS Bedrock (AWS default credentials and AWS_REGION)$ briar plan next q3 --llm bedrock
You get each step on the model you named. Agents always use Anthropic. --llm exists only on plan build, plan next, plan run and chat. Default models: OpenAI gpt-4o, Gemini gemini-2.5-pro, Bedrock anthropic.claude-sonnet-4-20250514-v1:0.
- In
plan run,--modelalso reaches the card's agent only with--llm anthropic. With another--llm, the agent uses its default model. modelunder[agent]in.briar.tomlsets the default--modelfor every command that has one, plan and chat too. Pass--modelwhen you use another--llm.
Set the name on the agent's commits
$ briar agent implement --ticket-key ACME-42 --tracker jira \--git-user-name "Acme Dev" --git-user-email [email protected]
You get commits made as Acme Dev. Briar looks for a name and email in this order:
--git-user-nameand--git-user-email, orgit_user_nameandgit_user_emailunder[agent]in.briar.toml.- The
git_identityblock of the company in the runbook, when you pass--runbook. - Your own
git config user.nameanduser.email. This step is skipped when theCIvariable is set.
If none gives a value, the run stops with an error. Each of the two fields is looked up on its own. The agent is told never to commit as a bot, so use a person's name.
Look at the agent's clone after a run
$ briar agent implement --ticket-key ACME-42 --tracker jira --keep-worktree -v$ ls -d "${TMPDIR:-/tmp}"/briar-agent-*
You get the clone left on disk, and its path in the log line worktree kept at ... (shown with -v). The second line lists all kept clones. A failed run keeps its clone even without the flag. Delete them by hand when you are done.
Run prfix on every open PR, every hour
1. The loop script
#!/usr/bin/env bash# /opt/briar/prfix-loop.shset -euo pipefailgh pr list --repo acme-co/acme-app --state open --json number,headRefName \| jq -c '.[]' | while read -r pr; donum=$(echo "$pr" | jq -r .number)branch=$(echo "$pr" | jq -r .headRefName)briar agent prfix --company acme --repo acme-co/acme-app \--pr "$num" --branch "$branch" \--runbook /etc/briar/runbooks/acme.yaml || truedone
You get one prfix run per open PR. || true keeps one failed PR from stopping the loop. Cron has no repo folder, so the script passes --company and --repo. The script's own gh call needs gh to be logged in, or GITHUB_TOKEN exported. Set the commit author in the runbook's git_identity.
2. The cron line
# crontab -e0 * * * * /opt/briar/prfix-loop.sh >> /var/log/briar/prfix.log 2>&1
You get the loop once an hour, with all output in a log file.
What happens on a PR it already fixed
--dry-run on one PR first.Serve MCP over HTTP
# on your own machine: loopback, no token needed$ briar mcp serve --transport http --port 8765# for other machines: a token is required$ export BRIAR_MCP_TOKEN="$(openssl rand -hex 32)"$ briar mcp serve --transport http --host 0.0.0.0 --port 8765 \--token-env BRIAR_MCP_TOKEN --runbook runbooks/acme.yaml
You get an MCP server at http://127.0.0.1:8765/mcp, or on every address for the second form. Clients must send Authorization: Bearer and the token; any other request gets 401. Briar refuses to listen on a non-loopback address without --token-env. --runbook turns on the runbook tools: read it, check it, and turn its MCP servers on or off. Needs the [mcp] extra.
Turn telemetry off
$ briar telemetry off$ briar telemetry status
You get telemetry off for good on this machine, saved in ~/.config/briar/telemetry.json. status shows the current level and where it came from.
- For one shell or one CI job, set
BRIAR_TELEMETRY=offorDO_NOT_TRACK=1.DO_NOT_TRACK=1wins over everything. - To keep crash reports but drop usage data, run
briar telemetry errors-only. - To see what would be sent, run
briar telemetry preview --for-command extract. Prompts, file contents, ticket keys, repo names, paths and secret values are never sent. - The daily new-version check is separate. Stop it with
BRIAR_NO_UPDATE_CHECK=1.DO_NOT_TRACK=1andBRIAR_TELEMETRY=offstop it too.
Other small things
Preview a telemetry event
$ briar telemetry preview --for-command extract$ briar telemetry preview --for-command "plan run"
You get the exact JSON event for that command. Nothing is sent.
Export a journal session
$ briar journal export 3f9a1c2b7d4e --as json --out audit.json$ briar journal export 3f9a1c2b7d4e --as markdown --out -
You get the session as a JSON file, or as markdown on your screen (--out - means stdout, the default). Find session IDs with briar journal list.
Write a blob three ways
$ briar context put memory:reviewer-alice --content "Cares about type hints"$ briar context put knowledge:acme --from-file notes/acme.md$ briar context put lessons:typing --content - --category lessons < notes/typing.md
You get a blob from text on the command line, from a file, and from stdin (--content -). The category comes from the part of the name before the colon unless you pass --category.
Set one card's state by hand
$ briar plan advance q3 --card KAN-7 --status in_progress
You get card KAN-7 marked in progress. --status takes pending, in_progress, done (the default) or blocked.
Preview a plan without saving it
$ briar plan build jira:KAN --name preview --max-cards 20 --dry-run
You get the plan for the first 20 cards printed, and nothing saved. --dry-run turns on --print for you. Without --llm, cards are built by simple rules, with no model call.
Flags briar fills in for you
--pr-target-repo and --pr-target-number are not flags you pass. briar agent prfix fills them from --owner, --repo and --pr, for the extractor that reads the PR review threads.Where to go next
- Usage flows: the same commands, put together into full jobs.
- briar extract: every extractor and flag.
- Runbook YAML: every field.
- briar plan: every flag of the plan loop.