CLI reference
briar agent
briar agent runs one agent on one task. implement turns a ticket into a draft pull request (PR). prfix fixes the review comments on a PR you already have.What an agent run is
An agent run is one task done by one AI model. briar gives the model a long prompt and a set of tools. The model works in turns. In each turn it reads what happened and calls the next tool. The run ends when the model says it is done, or after 30 turns.
What goes into the prompt
- The persona: the role the model plays.
implementuses theengineerpersona.prfixuses thepr-fixerpersona. - Your company knowledge. A blob is one saved markdown text in your knowledge store. briar reads every blob whose name starts with
knowledge:acme. It keeps only the sections this persona uses (see the list below). You make them with briar extract. - The task. For
implementthat is the ticket text, its acceptance criteria and its comments. Forprfixit is the PR's review threads. briar fetches it right before the run. - Meeting notes and Slack threads that match the task. briar adds them only when your Fireflies or Slack keys are set.
- The procedure: the exact steps the model must follow, and the rules it must never break.
These are the only sections each persona reads:
| Subcommand | Sections in the prompt |
|---|---|
implement (engineer) | ticket-context, meeting-context, meeting-digest, codebase-conventions, code-hotspots, reviewer-profile, active-work, pr-archaeology |
prfix (pr-fixer) | pr-review-context, meeting-context, meeting-digest, reviewer-profile, codebase-conventions, code-hotspots, active-work |
Sections from other extractors do not reach the agent. Neither does a plan's blob, like knowledge:acme.q3. Only the plan selector reads that one.
The tools the model can call
| Tool | What it does | When it is there |
|---|---|---|
bash | Runs a shell command in the worktree. Only a fixed list of commands works (see Good to know). | Always |
read_file | Reads a file in the worktree. | Always |
write_file | Writes a whole file in the worktree. | Always |
edit_file | Swaps one exact piece of text in a file. The text must appear once. | Always |
send_message | Posts to a named channel, like a Jira comment, a PR comment or a Slack channel. | With --runbook, when your company has a messages: block |
mcp__think__*, mcp__time__* | Step by step thinking, and the date and time. think needs npx and time needs uvx. Without them, that server is skipped with a warning. | When the [mcp] extra is installed, unless you pass --no-default-mcp |
mcp__sentry__* (any server) | Tools from an MCP server. MCP (Model Context Protocol) is a standard way to plug tools into a model. | With --runbook, when your company has an mcp: block |
Where the work happens
briar makes a worktree: a new temp folder with a fresh clone of your repo. Its name starts with briar-agent-implement- or briar-agent-prfix-. The file tools only work inside it. When the run ends, briar deletes it. briar keeps it when the run fails, or when you pass --keep-worktree. Then you can look inside.
Before you start
- A plain
pip install briar-cliis enough (since 1.1.74). Without the[mcp]extra, briar skips the think and time helper servers and logs one warning. Installpip install 'briar-cli[mcp]'to get them, or when your runbook has anmcp:block. gitandghon the machine. The Docker imageiklob1/briarhas both (since 1.1.75), so you can runbriar agentthere too. See Agents in Docker.- An Anthropic key:
ANTHROPIC_API_KEYorCLAUDE_CODE_OAUTH_TOKEN. The agent always runs on Anthropic. There is no--llmflag here. - A token to clone the repo:
GITHUB_TOKENon GitHub. On Bitbucket,BITBUCKET_ACME_APP_PASSWORD(plus the username and workspace vars). - On GitHub, the
ghCLI, installed and logged in. The agent opens PRs and reads review threads with it. - A company key:
--company acme,BRIAR_COMPANY, orcompany = "acme"in.briar.toml. - A real person's git name and email for the commits (see Good to know).
- Tracker keys so briar can read the ticket:
JIRA_ACME_URLand its auth vars,LINEAR_ACME_TOKEN, orGITHUB_TOKEN. Without them the agent only gets the ticket key. - Optional:
FIREFLIES_ACME_API_KEYfor meetings.SLACK_ACME_TOKENandSLACK_ACME_COOKIE_Dfor Slack (read only).
The full list of key names is on the configuration page.
$ briar agent implement
briar agent implement --ticket-key KEY
[--tracker {jira,github-issues,bitbucket-issues,linear}]
[--ticket-project KEY] [--company C] [--repo OWNER/REPO]
[--branch-name NAME] [--base-branch BRANCH]
[--dry-run] [--runbook YAML] [shared flags]Takes one ticket and tries to finish it as a draft PR. It works on a fresh clone of your default branch, or of --base-branch.
Use it when
- You have a small, clear ticket and want a first draft PR.
- You want to see what the agent would get before it spends tokens (
--dry-run). - You want to test one card by hand before you let briar plan run do a whole board. It calls
implementonce per card.
What it does, step by step
- Checks that it knows the company and the repo. They come from flags,
.briar.toml, or the gitoriginremote. - Clones the default branch into a new worktree. After the clone it removes the token from the saved remote URL.
- Sets the git name and email in the worktree.
- Reads the ticket: its text, its acceptance criteria (the checks the ticket says must pass) and its comments. If that fails, the agent still runs, but with the ticket key only.
- Looks for meetings and Slack threads that mention the ticket key. It skips this when those keys are not set.
- Starts the model with the engineer steps. It reads the ticket and makes a branch named from the ticket key:
ACME-42becomeschore/acme-42. - The agent changes the code. It runs the test command from
codebase-conventions. It pushes only when the tests pass, and never with--force. - It opens a draft PR with
gh pr create --draftand ends with the PR URL. This works on GitHub. On Bitbucket the branch gets pushed, but the PR is not opened (see Good to know). - If an acceptance criterion is unclear, the agent stops. It comments on the ticket instead of guessing.
- briar prints the agent's last message and the commit SHAs. Then it deletes the worktree.
Examples
These run inside a checkout of acme-co/acme-app with company = "acme" in .briar.toml, so most of them skip --company and --repo.
# 1. See the prompt and the tools first. No clone, no model call.$ briar agent implement --ticket-key ACME-42 --dry-run
You get the system prompt, the first message, the tool list, and the size of each context section. briar still reads the ticket, meetings and Slack, so those keys must work.
# 2. The real run, with company and repo spelled out.$ briar agent implement --company acme --repo acme-co/acme-app --ticket-key ACME-42
You get a draft PR on acme-co/acme-app from the branch chore/acme-42. The PR URL is at the end of the output.
# 3. Search meetings and Slack for a topic, not the ticket key.$ briar agent implement --ticket-key ACME-42 --meeting-query "login retry" --slack-query "login retry"
You get up to 3 meetings and 3 Slack threads about "login retry" in the prompt.
# 4. Give the agent message channels, MCP servers and a git identity.$ briar agent implement --ticket-key ACME-42 --runbook runbooks/acme.yaml
With this in runbooks/acme.yaml:
version: 1companies:acme:git_identity:name: Dana Leemessages:ticket_comment:kind: jira-commentpr_reply:kind: github-pr-commentops_chat:kind: slack-channelmcp:sentry:transport: httpurl: https://mcp.sentry.dev/mcpheaders:Authorization: SENTRY_MCP_BEARERpurpose: Production errors and stack traces
You get a send_message tool with three channels, the Sentry tools, and commits by Dana Lee. The full schema is on the runbook YAML page.
# 5. More turns, another model, a set author, and keep the folder.$ briar agent implement --ticket-key ACME-42 --model claude-sonnet-4-6 --max-iter 40 --git-user-name "Dana Lee" --git-user-email [email protected] --keep-worktree
You get up to 40 turns on that model and commits by Dana Lee. The log line worktree kept at ... tells you where the folder is.
# 6. Other trackers, and a repo on Bitbucket.$ briar agent implement --tracker linear --ticket-key ENG-7$ briar agent implement --tracker github-issues --ticket-key '#42'$ briar agent implement --provider bitbucket --repo acme-co/acme-app --tracker jira --ticket-key ACME-42
Jira and Linear take the project from the key (ACME, ENG). GitHub Issues uses the repo as the project. Quote '#42', or the shell reads it as a comment. On Bitbucket you get the pushed branch chore/acme-42, but no PR. Open it by hand.
Parameters
These flags are only on implement. The shared flags below work here too.
--ticket-key KEYrequiredACME-42. Linear: ENG-7. GitHub or Bitbucket Issues: #42. It also names the branch and is the default search for meetings and Slack. Example: --ticket-key ACME-42.--tracker TRACKERdefault: jirajiragithub-issuesbitbucket-issueslineartracker in .briar.toml also sets it. Example: --tracker linear.--ticket-project KEYACME. Linear team: ENG. GitHub or Bitbucket Issues: acme-co/acme-app. Leave it out and briar takes it from the ticket key (Jira, Linear) or from the repo (Issues). Example: --ticket-project ACME.--branch-name NAMEdefault: chore/<key>--branch-name fix/login-retry.--base-branch BRANCHdefault: the repo's default branch--base-branch feat/acme-41-schema.Good to know
- briar says the run worked when the agent ended without an error and made at least one commit (since 1.1.96; a run with no commit exits 1). It does not check that a PR exists. Read the agent's last message.
- A warning
ticket-context was emptymeans briar could not read the ticket. Check the tracker keys,--trackerand--ticket-project. - The agent pushes with
git push -u origin HEAD. It never force-pushes, amends, rebases or squashes.
$ briar agent prfix
briar agent prfix --pr NUMBER --branch BRANCH
[--company C] [--repo OWNER/REPO]
[--dry-run] [--runbook YAML] [shared flags]Works through the open review comments on one PR. It pushes one small commit per thread and replies with the commit SHA. Its steps cover review threads and PR comments only. The prompt also shows failing CI steps, but fixing CI is not one of its steps.
Use it when
- A reviewer left comments and the fixes are small and clear.
- You want a first pass on review comments before you look.
- You run it on a schedule. It skips a PR that needs nothing (see step 3).
What it does, step by step
- Clones the PR's branch (
--branch) into a new worktree. - Reads the PR's review threads and comments. Looks for meetings and Slack threads that mention
acme-co/acme-app#482. - The agent checks the PR with
gh pr view. It stops and reports "skipped" when the PR is approved, every required check is green, and every open thread has only positive comments. - Otherwise it lists every open review thread and PR comment.
- For each thread that asks for a code change, it makes the smallest fix. One commit per thread. The subject has 72 characters or fewer. The body names the comment ID.
- It pushes to the PR branch with a plain push:
git push origin HEAD:fix/login. - It replies to each thread it fixed, in one sentence, with the commit SHA.
- A question like "did you consider X?" gets a reply and no commit. A thread it cannot fix safely gets a comment that says why.
- It never force-pushes, amends, rebases, squashes or rewrites history.
Examples
# 1. See the prompt and the review threads first. No clone, no model call.$ briar agent prfix --pr 482 --branch fix/login --dry-run
You get the prompt, the tool list and the size of the pr-review-context section. If that section is missing, briar could not read the PR.
# 2. The real run, with company and repo spelled out.$ briar agent prfix --company acme --repo acme-co/acme-app --pr 482 --branch fix/login
You get one commit per fixed thread on fix/login, a reply on each of those threads, and the commit SHAs at the end of the output.
# 3. Reply through a runbook channel.$ briar agent prfix --pr 482 --branch fix/login --runbook runbooks/acme.yaml
With the pr_reply channel from the runbook above, the agent gets a send_message tool. It posts replies with it instead of raw gh calls.
# 4. Find the call where the reviewer explained the change.$ briar agent prfix --pr 482 --branch fix/login --meeting-query "Dana Lee" --slack-query "login retry"
You get up to 3 meetings that match "Dana Lee" and up to 3 Slack threads about "login retry".
# 5. Fewer turns, and keep the folder to check the result.$ briar agent prfix --pr 482 --branch fix/login --max-iter 15 --keep-worktree
You get a shorter run, at most 15 turns. The worktree stays on disk.
Parameters
These flags are only on prfix. The shared flags below work here too.
--pr NUMBERrequired--pr 482.--branch BRANCHrequired--branch fix/login.Good to know
- The prfix steps use
ghto read the PR and to reply.ghonly talks to GitHub. - briar does not track which comments it answered before. The agent sees every thread, its own earlier replies too, and decides what is left.
Flags both subcommands share
Every flag here works the same on implement and prfix. A flag on the command line wins over an env var. An env var wins over .briar.toml. That file wins over the built-in default.
--company COMPANYJIRA_ACME_URL) and your runbook block. Required, but it can come from BRIAR_COMPANY or company in .briar.toml. Example: --company acme.--repo REPOowner/repo, or a bare name with --owner. If you leave it out, briar uses [repo] in .briar.toml, then the git origin remote. Example: --repo acme-co/acme-app.--owner OWNER--repo is a bare name. Found the same way as --repo when you leave it out. Example: --owner acme-co --repo acme-app.--provider PROVIDERdefault: githubgithubbitbucket--provider bitbucket.--store STOREdefault: postgres if BRIAR_DATABASE_URL set, else filefilepostgresfile reads markdown files under --root. postgres reads the database in BRIAR_DATABASE_URL. BRIAR_STORE or store in .briar.toml also set it. Example: --store file.--root ROOTdefault: ./knowledge--knowledge still works as an old name for this flag (it prints a note). Example: --root ./knowledge.--model MODELdefault: claude-sonnet-4-5model under [agent] in .briar.toml also sets it. Example: --model claude-sonnet-4-6.--max-iter Ndefault: 30hit iteration ceiling. 0 means the default. Example: --max-iter 40.--git-user-name NAMEgit_identity.name from the runbook, then your own git config user.name. It skips that last step when the CI env var is set. Example: --git-user-name "Dana Lee".--git-user-email EMAIL--git-user-name. Each of the two is found on its own. Example: --git-user-email [email protected].--keep-worktree--keep-worktree.--no-default-mcpthink (needs npx) and time (needs uvx). BRIAR_NO_DEFAULT_MCP=1 does the same. Use it to stop the warnings. Without the [mcp] extra, briar skips these servers and logs one warning. On a machine without Node or uv, it warns about the missing one. If your runbook has an mcp: block, you still need the extra. Example: --no-default-mcp.--dry-run--dry-run.--runbook YAMLmessages: gives the agent a send_message tool. mcp: adds MCP servers. git_identity: sets the commit author. If the file does not load, the run goes on without them. Example: --runbook runbooks/acme.yaml.--meeting-key ID--meeting-query. Example: --meeting-key 01HZX3K9QW.--meeting-query TEXTimplement, and acme-co/acme-app#482 on prfix. Example: --meeting-query "login retry".--slack-query TEXT--meeting-query. briar only reads Slack. It needs SLACK_ACME_TOKEN and SLACK_ACME_COOKIE_D. Example: --slack-query "login retry".Hidden flags
These work, but -h does not show them. The defaults are fine for most runs.
--meeting PROVIDERdefault: firefliesfireflies--meeting fireflies.--meeting-top-k Ndefault: 3--meeting-top-k 5.--meeting-max-bytes Ndefault: 50000--meeting-max-bytes 20000.--chat PROVIDERdefault: slack--chat slack.--slack-top-k Ndefault: 3--slack-top-k 5.--slack-max-bytes Ndefault: 30000--slack-max-bytes 10000.--knowledge ROOT--root. Example: --knowledge ./knowledge.Good to know
- The agent always runs on Anthropic. Set
ANTHROPIC_API_KEYorCLAUDE_CODE_OAUTH_TOKEN. When both are set, briar uses the OAuth token. Without either, the run fails withLLM (anthropic) credentials missing. - A rate limit error (HTTP 429) stops the run at once. Wait for your quota to reset, then run it again.
- The agent must commit as a real person, never as a bot. Its rules tell it to check
git config user.namefirst. If briar finds no name or email, it stops withgit identity not configured. briar also turns off commit signing in the worktree. bashonly runs these commands:git,gh,ls,cat,head,tail,grep,rg,find,wc,pwd,echo,cd,python,python3,pytest,ruff,black,mypy,npm,node,make,tee,sortanduniq. If your tests need another tool, put them behind amaketarget.bashalso blocks any command that containscurl,wget,sudo,rm -rf,--force,--amend,rebase,squashorreset --hard.- On Bitbucket, the agent opens the draft PR with a short Python script it saves under
.git/(never committed) and runs withpython3, sincebashblockscurl(since 1.1.88; before, only the branch got pushed). On GitHub it usesgh. - A
bashcommand times out after 60 seconds by default, and after 300 at most. - When your runbook gives two or more MCP servers, briar first asks the model which ones this task needs. That is one short extra call.
thinkandtimeare always on. - The last log line shows tokens in, tokens out, and a cost guess. The guess uses Sonnet 4.5 prices: $3 per million input tokens, $15 per million output tokens.
- A run of
implementorprfixon its own is not saved in the journal. Onlyplan runandscaffoldwrite there.
Exit codes
| Code | Meaning |
|---|---|
0 | The agent ended without an error. A dry run also ends with 0. |
1 | Something failed: a missing company or repo, the clone, the git identity, the model key, a model error, or the turn limit. |
2 | Bad flags, a repo provider briar could not set up, or a crash. |
130 | You pressed Ctrl-C. |
Start with a dry run
--dry-run first. It shows the exact prompt and tools, and costs no tokens. Then run for real on one small ticket.See also
- briar plan: runs
agent implementon each card of a board. - Runbook YAML: the
messages:,mcp:andgit_identity:blocks. - Configuration: every key and env var name.
- briar scaffold: a config bundle that wires
implementandprfixinto another tool. - Core concepts: Agents: personas and the knowledge they read.