Skip to content

Documentation

Briar documentation

Briar is a free command-line tool that runs on your own machine. It reads your repos, tickets, cloud and meeting notes, and saves what it learns as plain markdown, called knowledge. Its AI agents then use that knowledge to open draft pull requests for tickets and to fix review comments.

Who it is for

  • Developers who want an AI agent to take a ticket to a draft pull request (PR), with tests run first.
  • Developers who want an agent to answer the review comments on a PR.
  • Teams that want a written, up-to-date summary of how they work: PR history, hot files, CI health, open tickets, cloud setup.
  • People who use AI coding tools (Claude Code or any MCP host) and want those tools to know the project.

The 5-minute path

Six commands take you from nothing to a preview of an agent run. You need Python 3.10 or newer, a git checkout of your repo, and a GitHub token. Each command has its own page with every option.

1. Install

$ pip install briar-cli
$ briar version

You get the briar command. The second line prints briar-cli 1.1.75 (or newer).

2. Set up your repo and log in

Run these inside your repo folder.

$ briar init --company acme
$ briar auth login github-pat --company acme

init writes a .briar.toml file. It holds your company name (acme) and the repo owner and name, read from your git remote. Later commands read this file, so you can skip --company and the repo flags.

auth login github-pat opens the GitHub token page and asks you to paste a token. Give it the repo and read:org scopes. Briar saves it as GITHUB_TOKEN in ~/.config/briar/secrets.env.

3. Pull knowledge and read it

$ briar extract --include pr-archaeology --max 50
$ briar context get knowledge:acme

extract reads your last 50 merged PRs and writes a summary to a blob named knowledge:acme. On disk that is ./knowledge/knowledge/acme.md. context get prints it. No AI key is needed for this step.

4. Preview an agent run

$ briar agent implement --ticket-key ACME-42 --tracker jira --dry-run

You get the exact prompt and the tool list the agent would use for ticket ACME-42. A dry run does not clone the repo and does not call the model, so it costs nothing. Without a Jira login the ticket part of the prompt is empty, but the preview still works.

One warning about MCP is normal

Each agent run tries to start two small helper servers. They need the [mcp] extra. On a plain install, briar skips them, logs one warning, and the run goes on. See Install: extras.

For a real run, set ANTHROPIC_API_KEY, log in to Jira with briar auth login jira-token --company acme, and drop --dry-run. The agent then opens a draft PR on GitHub. The ship one ticket flow walks through it.

Every command, one line each

CommandWhat it does
briar extractReads your tools (GitHub, Jira, AWS, ...) and writes what it finds to a knowledge blob.
briar runbook extract | sweep | serveRuns extractors from a YAML file: once, for a whole folder, or on a schedule.
briar plan build | show | status | next | advance | list | clear | runTurns a board into a list of cards, then works the cards one by one.
briar agent implement | prfixAn AI agent takes a ticket to a draft PR, or fixes the review comments on a PR.
briar scaffold implementation | pr-fixesPrints a starter JSON config for an agent workflow, from a template.
briar context put | get | list | delete | categoriesReads and writes knowledge blobs by name.
briar journal list | show | exportShows what a plan run or a scaffold decided, step by step.
briar dashboardServes a read-only status web page for a host that runs briar.
briar mcp serveShares briar's knowledge and tools with an MCP host, like Claude Code.
briar chatA chat in your terminal with an assistant that can use briar for you.
briar init | config show | doctorCreates your project config, shows where each setting comes from, checks your setup.
briar completion | versionTab completion for bash or zsh, and the installed version.
briar auth login | logout | refresh | list | statusSaves your logins (tokens, keys) and shows which ones are set.
briar secrets doctor | bootstrapChecks that every login your runbooks need is set.
briar telemetry status | preview | off | errors-only | full | resetControls the crash and usage reports briar sends.

Every command takes -h for its help. The global --format json flag gives JSON from the commands that print tables, and -v turns on debug logs.

How these docs are organised

  • Get started: this page, Install, Core concepts and Configuration. Read them in order the first time.
  • CLI reference: one page per command group, with every flag, its default and an example.
  • Reference: the guides below.
PageWhat you find there
ConfigurationThe .briar.toml file, environment variables, and where logins are kept.
Runbook YAMLEvery field you can put in a runbook file.
Plugin registriesThe lists of supported LLMs, repo hosts, trackers, clouds and stores.
Usage flowsStep-by-step flows from start to finish.
RecipesShort “how do I ...?” answers.

Next steps

Which version

These pages describe briar-cli 1.1.75. Run briar <command> -h to see the help of the version you have. Found something wrong? Open an issue.