briar

briar is a command-line tool (you run it in your terminal) that helps AI coding assistants do better work on your team's code.

The problem: an AI assistant like Claude can write code, but it does not know your team. It does not know which tests you run, who reviews what, how your PRs usually look, or what the ticket really asks. So it guesses, and you fix its guesses.

What briar does about it, in two parts:

1. It collects facts. It reads your team's tools (GitHub or Bitbucket, Jira or Linear, AWS, Fireflies meeting notes) and writes what it learns into plain text files on your computer. briar calls these facts "knowledge".
2. It gives those facts to AI agents. An agent is an AI that works on its own, step by step. One briar agent takes a ticket and opens a draft PR (a PR marked "not ready to merge yet"). Another one fixes the review comments on a PR. You always review and merge yourself.

There is no briar server and no account. briar only talks to the services you set up: your code host, your tracker, your cloud and your AI provider. Your tokens stay in a file on your computer.

What you get

• Facts from your tools. briar has 23 extractors. An extractor is a small reader for one kind of fact, for example "how long PRs take to merge" or "which files change the most". They read GitHub, Bitbucket, Jira, Linear, AWS, GCP, Azure and Fireflies, and write plain markdown text to a folder (or to a Postgres database), once or on a schedule.
• AI agents that read the facts first. briar agent implement takes a ticket, reads the facts it needs, writes the code in a fresh copy of your repo, runs your tests and opens a draft PR. briar agent prfix answers each review comment with its own small commit. Agents never force-push, amend or rebase, so they never rewrite history that is already there.
• A whole board, one card at a time. briar plan reads a Jira board or a GitHub Project (the list of tickets your team works on), puts the cards in order and works on them one by one. When a card needs another card's code, it starts from that card's branch, so the PRs build on each other.
• You stay in charge. Agents only open draft PRs. briar has no command that merges.
• Works with your other AI tools. --merge-claude-md adds the facts to CLAUDE.md, the file Claude Code reads when it starts. briar mcp serve shares the facts with any app that speaks MCP (a standard way for AI apps to call tools); it offers 10 tools.
• Runs on your computer. No account. Keys stay in a file on your machine, or in AWS Secrets Manager, SSM or Vault.

Where the knowledge comes from, and where the work goes

[briar reads code, tickets, cloud, meetings and Slack into a local knowledge store; agents read that knowledge plus live ticket context, work in a clean git worktree, and open draft PRs that you review and merge.]

Everything in the dashed box runs on your machine and reads from your tools. Agents push branches, open draft PRs and reply on reviews; their send_message tool only reaches the channels you list in the runbook.

1. Extractors read your tools, on demand or on a schedule, and write markdown knowledge to a local folder or to Postgres.
2. You point an agent at a ticket or a PR. It fetches the ticket, the PR's review threads, and matching meeting notes and Slack messages live.
3. In a clean git worktree it first reads the knowledge sections that fit its job (conventions, hotspots, reviewers, PR history), writes the code on a new branch and runs your tests. Coding agents run on Anthropic with your own key.
4. It pushes and opens a draft PR. If you allow those channels in the runbook, it can also comment on the ticket or post in Slack or Telegram.
5. You review. briar agent prfix answers the comments with one commit per thread. You merge; briar never does.
6. A plan run writes what each card taught into the plan's knowledge, which its selector reads before the next pick. All knowledge also feeds Claude Code (CLAUDE.md) and any MCP client.

More diagrams are in See it run.

Install

pip install briar-clibriar version

briar needs Python 3.10 or later. To run briar agent or briar plan run you also need git and the GitHub CLI gh, because the agent runs them.

The base install covers GitHub, Bitbucket, AWS, Jira, Linear, Fireflies, Anthropic (Claude) and AWS Bedrock, with a file or Postgres store, and runs the coding agents. Extras add more:

pip install 'briar-cli[mcp]'      # briar mcp serve, briar chat, MCP tools for agentspip install 'briar-cli[all]'      # openai, gemini, mcp, gcp, azure, vault

Or skip the install and use the Docker image, which also has git and gh:

docker run --rm iklob1/briar version

Mounts, keys and running agents in Docker: usebriar.com/docs/install#docker. What each extra adds: usebriar.com/docs/install#extras.

Quickstart

The short version, for a GitHub repo with Jira tickets. New to briar? Learn it in 3 examples instead.

# 1. Save a GitHub token and Jira login. They go to ~/.config/briar/secrets.envbriar auth login github-pat --company acmebriar auth login jira-token --company acme
# 2. Give briar a Claude key. It reads it from your shell.export ANTHROPIC_API_KEY=sk-ant-your-key
# 3. Read the repo's recent PRs and its tools into the blob knowledge:acmebriar extract --company acme --repo acme-co/acme-app \    --include pr-archaeology --include codebase-conventions --max 50
# 4. Read what was savedbriar context get knowledge:acme
# 5. Print the agent's prompt for ticket ACME-42. No cost, nothing pushed.briar agent implement --company acme --repo acme-co/acme-app \    --ticket-key ACME-42 --tracker jira --dry-run
# 6. Run it for real: clone, branch, code, test, open a draft PRbriar agent implement --company acme --repo acme-co/acme-app \    --ticket-key ACME-42 --tracker jira

After step 3 you have ./knowledge/knowledge/acme.md. After step 6 you have a branch chore/acme-42 and a draft PR on acme-co/acme-app.

Learn briar in 3 examples

Written for someone who has never used briar. Each example says the problem it solves, what each command does, what happens behind the scenes, and what you get. Every GIF is a real run in a clone of this repo on briar 1.1.99: the commands really ran; only the typing is paced, and a long output is shown one screen at a time so you can read it.

Before you start (once, about 2 minutes):

pip install briar-cli                  # installs the briar command (needs Python 3.10 or later)cd path/to/your-repo                   # go into any GitHub repo you can readexport GITHUB_TOKEN=$(gh auth token)   # gives briar your GitHub login, so it can read the repo

If you do not use the GitHub CLI gh, run briar auth login github-pat --company myteam and paste a GitHub token instead. That token is all examples 1 and 2 need. Nothing is sent to an AI, so they cost nothing. Example 3 also uses --dry-run, so it costs nothing either; you only need an AI key (export ANTHROPIC_API_KEY=...) when you drop --dry-run and let the agent really work.

Words you will see:

Example 1: Set up briar and collect facts

The problem: an AI that writes code for you does not know your repo or how your team works: how fast PRs get merged, who writes them, how often you release, how often CI passes.

briar init --company myteam    # creates .briar.toml, a small settings file in your repobriar doctor                   # checks that briar has everything it needsbriar extract --include pr-archaeology --include release-cadence --include ci-health --merge-claude-md                               # collects three kinds of facts and tells Claude Code where they arebriar context get knowledge:myteam   # prints the facts briar saved

[briar init writes .briar.toml, briar doctor shows every check as ok, briar extract collects three kinds of facts and updates CLAUDE.md, briar context get prints them]

What happens:

• init runs git remote get-url origin to find the GitHub owner and repo name, and writes them into .briar.toml with the team name you chose (myteam is just a label). After this, no command needs --company or --repo. To see each setting and where it came from, run briar config show.
• doctor checks Python, the settings file, the git remote, your GitHub token and your AI key. ok means ready; warn tells you what is missing and what needs it.
• extract runs the extractors you name with --include. They ask the GitHub API for your merged PRs (pr-archaeology), your releases (release-cadence) and your last 100 CI runs (ci-health), and sum them up. The result is saved as one markdown file under ./knowledge/, called knowledge:myteam.
• --merge-claude-md also writes the facts to .briar/knowledge/myteam.md and adds a short block to CLAUDE.md that points to it. Claude Code (an AI coding assistant) reads CLAUDE.md when it starts, so every session begins with your facts. Your own text in CLAUDE.md stays as it is.
• context get prints the saved file. It only reads your disk; nothing goes online.

You get: your repo's facts in one text file, ready for any AI.

briar extract -h lists all 23 extractors. Good ones to add later: code-hotspots (the files that change the most), codebase-conventions (your test runner, linter and formatter) and stale-prs (open PRs nobody touched for a while). Running extract again only replaces the sections of the extractors that ran, so the facts you already have stay. briar extract with no --include runs all 23; on this repo that took about 4 minutes.

Example 2: Keep the facts fresh with a runbook

The problem: facts from last month are wrong today, and you do not want to type the extract command every day.

Save this as runbooks/myteam.yaml. It lists the same three extractors as example 1:

version: 1companies:  myteam:    schedules:      - task: extractors        every: "minute"          # only for the demo; use "day at 03:17" for real        extract:          - name: pr-archaeology            args: {pr_repo: [iklobato/briar]}          - name: release-cadence            args: {release_repo: [iklobato/briar]}          - name: ci-health            args: {cihealth_repo: [iklobato/briar]}

briar runbook serve runbooks   # start a scheduler for every runbook in the folder

[briar runbook serve runs the myteam job by itself, saves knowledge:myteam again, then stops on Ctrl+C]

What happens:

• serve is a scheduler: a program that keeps running and starts each job on time. Every second it checks which job is due.
• When the job is due, it does the same work as briar extract and saves knowledge:myteam again. The log lines show each step.
• It runs until you press Ctrl+C. On a server you leave it running.
• To run the file once, right now, use briar runbook extract runbooks/myteam.yaml.
• More teams go under companies:. Each team gets its own file, and their first runs start a few seconds apart, so they do not all call GitHub at the same moment.
• A runbook writes its whole file each time, so list in it every extractor you want to keep.

You get: facts that refresh themselves, without anyone typing a command.

Example 3: Let AI agents do the work

An agent reads your facts first, then works on its own. briar has two: one turns a ticket into a draft PR, the other answers review comments. Both are shown with --dry-run, so you see exactly what the AI would be told, without running it.

A ticket becomes a draft PR

The problem: before an AI can write good code for a ticket, it needs the ticket, your repo's rules and your team's facts, all in one set of instructions, and it must not be able to do anything risky.

briar agent implement --ticket-key 38 --tracker github-issues --dry-run   # build the agent's prompt for issue #38

[briar agent implement --dry-run prints the steps, the strict rules, the tools and the ticket context for issue #38]

What happens:

• briar reads issue #38 from GitHub and your saved facts, and builds the prompt: the agent's steps (make a new branch, write the code, run the tests, open a draft PR), its rules (never force-push, amend or rebase), and the tools it may use (a limited shell, and reading and editing files).
• --dry-run prints all of that and stops. No AI is called, nothing is cloned, nothing is pushed.

You get: run it again without --dry-run, with ANTHROPIC_API_KEY set, and the agent writes the code on a new branch, runs your tests and opens a draft PR. You review it and merge it; briar never merges. Jira and Linear tickets work the same way (--tracker jira, --tracker linear).

Review comments get answered

The problem: reviewers leave comments on your PR, and fixing each one, committing and replying on GitHub takes time.

briar agent prfix --pr 75 --branch docs/readme-hero --dry-run   # build the agent's prompt for PR #75

[briar agent prfix --dry-run prints the review comment, the fix steps, the strict rules and the tools]

What happens:

• briar reads PR #75, its description and its open review comments from GitHub (here there is one, shown under "Inline review comments (1)").
• It builds the prompt: one small commit per comment, then a reply on the comment with the commit's SHA (its id), and the same safety rules as above.
• --dry-run prints it and stops. Nothing changes on the PR.

You get: run it without --dry-run and the agent fixes each comment, pushes to the PR's branch and replies on GitHub.

Commands

Each command has a manual in agents/. The same reference, with more examples, is at usebriar.com/docs.

Recipes that chain these commands are in flows.md. A runbook that uses every feature is examples/all_features.yaml.

Three flags work with every command, anywhere on the line:

See it run

The same four diagrams as on usebriar.com. Click one to open it.

Contributing

Bug reports and PRs are welcome: open an issue or read CONTRIBUTING.md first. Every merge to main is a release on PyPI and Docker Hub, and CHANGELOG.md lists what each version changed. If briar helps you, a star on GitHub helps other people find it.

Telemetry

briar sends error reports and usage counts by default. No prompts, file contents, ticket keys, repo names, paths or secret values leave your machine. Turn it off with briar telemetry off, BRIAR_TELEMETRY=off or DO_NOT_TRACK=1.

License

MIT. See LICENSE.