Skip to content

CLI reference

briar agent

An agent is an AI model that works on your code by itself. 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. implement uses the engineer persona. prfix uses the pr-fixer persona.
  • 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 implement that is the ticket text, its acceptance criteria and its comments. For prfix it 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:

SubcommandSections 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

ToolWhat it doesWhen it is there
bashRuns a shell command in the worktree. Only a fixed list of commands works (see Good to know).Always
read_fileReads a file in the worktree.Always
write_fileWrites a whole file in the worktree.Always
edit_fileSwaps one exact piece of text in a file. The text must appear once.Always
send_messagePosts 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-cli is enough (since 1.1.74). Without the [mcp] extra, briar skips the think and time helper servers and logs one warning. Install pip install 'briar-cli[mcp]' to get them, or when your runbook has an mcp: block.
  • git and gh on the machine. The Docker image iklob1/briar has both (since 1.1.75), so you can run briar agent there too. See Agents in Docker.
  • An Anthropic key: ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN. The agent always runs on Anthropic. There is no --llm flag here.
  • A token to clone the repo: GITHUB_TOKEN on GitHub. On Bitbucket, BITBUCKET_ACME_APP_PASSWORD (plus the username and workspace vars).
  • On GitHub, the gh CLI, installed and logged in. The agent opens PRs and reads review threads with it.
  • A company key: --company acme, BRIAR_COMPANY, or company = "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_URL and its auth vars, LINEAR_ACME_TOKEN, or GITHUB_TOKEN. Without them the agent only gets the ticket key.
  • Optional: FIREFLIES_ACME_API_KEY for meetings. SLACK_ACME_TOKEN and SLACK_ACME_COOKIE_D for 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 implement once per card.

What it does, step by step

  1. Checks that it knows the company and the repo. They come from flags, .briar.toml, or the git origin remote.
  2. Clones the default branch into a new worktree. After the clone it removes the token from the saved remote URL.
  3. Sets the git name and email in the worktree.
  4. 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.
  5. Looks for meetings and Slack threads that mention the ticket key. It skips this when those keys are not set.
  6. Starts the model with the engineer steps. It reads the ticket and makes a branch named from the ticket key: ACME-42 becomes chore/acme-42.
  7. The agent changes the code. It runs the test command from codebase-conventions. It pushes only when the tests pass, and never with --force.
  8. It opens a draft PR with gh pr create --draft and 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).
  9. If an acceptance criterion is unclear, the agent stops. It comments on the ticket instead of guessing.
  10. 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:

runbooks/acme.yaml
version: 1
companies:
acme:
git_identity:
name: Dana Lee
messages:
ticket_comment:
kind: jira-comment
pr_reply:
kind: github-pr-comment
ops_chat:
kind: slack-channel
mcp:
sentry:
transport: http
url: https://mcp.sentry.dev/mcp
headers:
Authorization: SENTRY_MCP_BEARER
purpose: 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 KEYrequired
The ticket to work on. Jira: ACME-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: jira
jiragithub-issuesbitbucket-issueslinear
Where the ticket lives. tracker in .briar.toml also sets it. Example: --tracker linear.
--ticket-project KEY
The tracker project. Jira: ACME. 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>
The branch the agent creates and pushes. Example: --branch-name fix/login-retry.
--base-branch BRANCHdefault: the repo's default branch
The branch to clone and open the PR against. Use it to stack this ticket on another open branch. If the branch does not exist, the run fails. Since 1.1.85. Example: --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 empty means briar could not read the ticket. Check the tracker keys, --tracker and --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

  1. Clones the PR's branch (--branch) into a new worktree.
  2. Reads the PR's review threads and comments. Looks for meetings and Slack threads that mention acme-co/acme-app#482.
  3. 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.
  4. Otherwise it lists every open review thread and PR comment.
  5. 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.
  6. It pushes to the PR branch with a plain push: git push origin HEAD:fix/login.
  7. It replies to each thread it fixed, in one sentence, with the commit SHA.
  8. 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.
  9. 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
The PR number. It must be a number. Example: --pr 482.
--branch BRANCHrequired
The PR's branch (its head branch). briar clones it, and the agent pushes back to it. Example: --branch fix/login.

Good to know

  • The prfix steps use gh to read the PR and to reply. gh only 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 COMPANY
The company key. briar uses it to find your knowledge blobs, your per-company keys (like JIRA_ACME_URL) and your runbook block. Required, but it can come from BRIAR_COMPANY or company in .briar.toml. Example: --company acme.
--repo REPO
The repo, as owner/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
The GitHub owner, or the Bitbucket workspace. You need it only when --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: github
githubbitbucket
Where the repo lives. It picks the clone URL, the token, and how the PR is opened. Example: --provider bitbucket.
--store STOREdefault: postgres if BRIAR_DATABASE_URL set, else file
filepostgres
Where your knowledge blobs live. file 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
The folder of the file store. briar ignores it with postgres. --knowledge still works as an old name for this flag (it prints a note). Example: --root ./knowledge.
--model MODELdefault: claude-sonnet-4-5
The Anthropic model the agent uses. model under [agent] in .briar.toml also sets it. Example: --model claude-sonnet-4-6.
--max-iter Ndefault: 30
The most turns the model gets. One turn is one model reply plus the tools it calls. When the turns run out, the run fails with hit iteration ceiling. 0 means the default. Example: --max-iter 40.
--git-user-name NAME
The commit author name in the worktree. If you leave it out, briar uses git_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
The commit author email. Same rules as --git-user-name. Each of the two is found on its own. Example: --git-user-email [email protected].
--keep-worktree
Keep the worktree folder after the run. briar always keeps it when the run fails. Example: --keep-worktree.
--no-default-mcp
Do not start the two built-in MCP servers: think (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
Print the prompt, the first message and the tool list, then stop. No clone, no model call, no tokens spent. briar still reads the ticket or PR, meetings and Slack, and still starts the MCP servers. It works on a plain install, too. Example: --dry-run.
--runbook YAML
A runbook file: the YAML that holds per-company settings. briar reads three blocks from your company's entry. messages: 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
One Fireflies meeting ID to add to the prompt. It wins over --meeting-query. Example: --meeting-key 01HZX3K9QW.
--meeting-query TEXT
Search words for recent meetings (title and transcript). The default is the ticket key on implement, and acme-co/acme-app#482 on prfix. Example: --meeting-query "login retry".
--slack-query TEXT
Search words for Slack threads. Same default as --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: fireflies
fireflies
The meeting tool to search. Only Fireflies exists today. Example: --meeting fireflies.
--meeting-top-k Ndefault: 3
The most meetings to add when briar searches. The lowest value is 1. Example: --meeting-top-k 5.
--meeting-max-bytes Ndefault: 50000
The most transcript text to add per meeting, in bytes. The lowest value is 1024. Example: --meeting-max-bytes 20000.
--chat PROVIDERdefault: slack
The chat tool to search. Only Slack exists today. Example: --chat slack.
--slack-top-k Ndefault: 3
The most Slack threads to add. Example: --slack-top-k 5.
--slack-max-bytes Ndefault: 30000
The most Slack text to add in total, in bytes. The lowest value is 1024. Example: --slack-max-bytes 10000.
--knowledge ROOT
The old name for --root. Example: --knowledge ./knowledge.

Good to know

  • The agent always runs on Anthropic. Set ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN. When both are set, briar uses the OAuth token. Without either, the run fails with LLM (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.name first. If briar finds no name or email, it stops with git identity not configured. briar also turns off commit signing in the worktree.
  • bash only 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, sort and uniq. If your tests need another tool, put them behind a make target.
  • bash also blocks any command that contains curl, wget, sudo, rm -rf, --force, --amend, rebase, squash or reset --hard.
  • On Bitbucket, the agent opens the draft PR with a short Python script it saves under .git/ (never committed) and runs with python3, since bash blocks curl (since 1.1.88; before, only the branch got pushed). On GitHub it uses gh.
  • A bash command 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. think and time are 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 implement or prfix on its own is not saved in the journal. Only plan run and scaffold write there.

Exit codes

CodeMeaning
0The agent ended without an error. A dry run also ends with 0.
1Something failed: a missing company or repo, the clone, the git identity, the model key, a model error, or the turn limit.
2Bad flags, a repo provider briar could not set up, or a crash.
130You pressed Ctrl-C.

Start with a dry run

Run with --dry-run first. It shows the exact prompt and tools, and costs no tokens. Then run for real on one small ticket.

See also