Skip to content

Reference

Usage flows.

Each flow is a real job you can finish in a day. It gives the goal, the commands in order, and what you get after each step. The examples use company acme, repo acme-co/acme-app, Jira project ACME and board jira:KAN. Change them to yours.

Before you start

Run the flows inside your repo, after briar init --company acme. Then --company, --owner and --repo come from .briar.toml and you can leave them out. Each flag is explained on its command page in the CLI reference.

1. Onboard a repo

Goal: go from nothing to a knowledge blob that describes your repo and your open tickets.

  1. Install briar and create the project config.
    $ pip install briar-cli
    $ briar init --company acme
    You get the briar command and a .briar.toml with company, owner and repo. Agent runs (flows 2 to 4) work on this plain install. The [mcp] extra only adds two small helper servers. Without it, each agent run logs one warning.
  2. Log in to GitHub and Jira. Each command asks you to paste a token.
    $ briar auth login github-pat --company acme
    $ briar auth login jira-token --company acme
    You get GITHUB_TOKEN, JIRA_ACME_URL, JIRA_ACME_EMAIL and JIRA_ACME_TOKEN in ~/.config/briar/secrets.env.
  3. Check your setup.
    $ briar doctor
    You get one line per check. Fix anything marked fail. A warn for the AI key is fine for now.
  4. Run every extractor, and name your Jira project for the two ticket extractors.
    $ briar extract --ticket-project ACME --ticket-archaeology-project ACME
    You get knowledge:acme, with one section per extractor that found data. An extractor that cannot run (for example Fireflies, with no login yet) prints skipped. That is expected.
  5. Read the top of the result.
    $ briar context get knowledge:acme | head -40
    You get the first 40 lines: the title and the first sections.

extract keeps the other sections (1.1.82 and later)

A briar extract run with two --include flags updates those two sections of knowledge:acme and keeps the rest. Before 1.1.82 the blob then held only those two sections; there, write new sections to their own blob with --blob-name, as below. The coding agent looks in every blob whose name starts with knowledge:acme, for the sections its role uses (see what an agent reads).

Connect more tools

Add a login for each tool you use, then extract its data. Each login is for one company.

$ briar auth login aws-static --company acme
$ briar auth login fireflies --company acme
$ briar extract --include aws-infra --include meeting-digest --since-days 14 --blob-name knowledge:acme.cloud

You get a second blob, knowledge:acme.cloud, with your AWS setup and a digest of the last 14 days of Fireflies meetings. knowledge:acme stays as it was. The coding agent uses the meeting digest. The AWS section is for you and for MCP hosts; the agent does not read it. Other logins: aws-sso, github-device, bitbucket-app-password, jira-session (a browser cookie instead of a token) and linear-api-key.

Slack has no auth login target. Agents read it live, from a browser session. Add these two lines to ~/.config/briar/secrets.env:

SLACK_ACME_TOKEN=xoxc-your-token
SLACK_ACME_COOKIE_D=xoxd-your-cookie

You get Slack threads in agent prompts when you pass --slack-query (or by default, matched on the ticket key or PR).

2. Ship one ticket

Goal: Jira ticket ACME-42 becomes a draft pull request, with tests run before the push.

  1. Make sure the knowledge is fresh. If you ran flow 1 today, skip this step.
    $ briar extract --ticket-project ACME --ticket-archaeology-project ACME
    You get a new knowledge:acme. The agent leans most on its codebase conventions section: your test command, linter and formatter.
  2. Preview the run. This is free.
    $ briar agent implement --ticket-key ACME-42 --tracker jira --dry-run
    You get the full prompt, the tool list, and the ticket section with its size. No clone and no model call happen.
  3. Run it for real. Set ANTHROPIC_API_KEY first.
    $ briar agent implement --ticket-key ACME-42 --tracker jira
    The agent clones your default branch into a temp folder. It makes a branch (chore/acme-42), changes the code, and runs your tests. It pushes only when they pass, then opens a draft PR. You get its final message, the PR link, and the list of commits in your terminal.
  4. Review the draft PR like any other. If the agent found an unclear acceptance criterion, it stops and asks on the ticket instead of guessing.

For a whole board, use flow 4.

3. Answer a review

Goal: a reviewer left comments on PR 482 (branch fix/login). The agent fixes each one and replies.

  1. Preview what the agent will see.
    $ briar agent prfix --pr 482 --branch fix/login --dry-run
    You get the prompt, with a section that holds the PR's review threads and comments.
  2. Run it.
    $ briar agent prfix --pr 482 --branch fix/login
    The agent clones the PR branch. It makes one commit per review thread and pushes. Then it replies on each thread with the commit SHA. It never force-pushes, amends, rebases or squashes. A thread that only asks a question gets a reply and no commit.
  3. Add meeting notes when the review was talked about in a call. This needs a Fireflies login.
    $ briar agent prfix --pr 482 --branch fix/login --meeting-query "login retry"
    You get the matching meeting notes in the prompt. Without --meeting-query, briar searches for acme-co/acme-app#482.
  4. Let the agent post a note to Jira or Slack when it is done.
    $ briar agent prfix --pr 482 --branch fix/login --runbook runbooks/acme.yaml
    You get a send_message tool bound to the channels in that runbook's messages: block.

What prfix does not do

Its steps cover open review threads and PR comments only. It sees the PR's failing CI logs as background, but it is not told to fix them; for that, scaffold a pr-ci-fixer agent. It is told to skip a PR that is approved, has green checks, and has only positive comments.

4. Work a board

Goal: turn Jira board KAN into a plan, then ship it card by card.

  1. Refresh knowledge, so the plan and the agent start from facts.
    $ briar extract --ticket-project KAN --ticket-archaeology-project KAN
    You get an up-to-date knowledge:acme, with the open and closed tickets of project KAN.
  2. Build the plan.
    $ briar plan build jira:KAN --name q3 --with-knowledge --llm anthropic
    You get plan:q3: one card per ticket (up to 50), each with scope, risks and what it depends on.
  3. Look at it before you spend anything.
    $ briar plan show q3
    $ briar plan status q3
    $ briar plan next q3 --llm anthropic
    You get the plan text, the cards by state, and the card the selector would pick next, with its reason. Nothing changes yet.

Start small, then go wide

  1. Preview one card for free. Use the card key from plan next.
    $ briar agent implement --ticket-key KAN-7 --tracker jira --dry-run
    You get the prompt the agent would get for that card.
  2. Ship exactly one card.
    $ briar plan run q3 --llm anthropic --tracker jira --tracker-project KAN --limit 1
    You get one draft PR, from the card's branch (built without --llm, for KAN-7: chore/kan-7), against the card's parent branch. The card becomes done or blocked, and a summary prints at the end. Check the PR and the cost before you go on.
  3. Run the rest, and keep going when a card fails.
    $ briar plan run q3 --llm anthropic --tracker jira --tracker-project KAN --continue-on-failure
    You get one draft PR per finished card. A failed card is marked blocked and the loop moves on. It stops when the selector says the plan is complete or blocked.
  4. Watch progress and what the plan learned.
    $ briar plan status q3
    $ briar context get knowledge:acme.q3
    You get the cards by state, and the notes added after each done card.

Two flags people forget

plan run uses GitHub Issues as the tracker unless you say otherwise. For a Jira board, pass --tracker jira --tracker-project KAN, or put tracker = "jira" in .briar.toml. To preview the whole loop, use plan run --dry-run on 1.1.81 or later: it saves nothing. Before 1.1.81 it marked the picked cards done, so use plan next and agent implement --dry-run there.

5. Keep knowledge fresh on a schedule

Goal: refresh knowledge:acme every morning, with no cron job, and hear about it when a run fails.

  1. Write a runbook.
    # runbooks/acme.yaml
    version: 1
    companies:
    acme:
    knowledge:
    store: file
    name: knowledge:acme
    schedules:
    - task: extractors
    every: "day at 07:00"
    extract:
    - name: pr-archaeology
    args:
    pr_repo: [acme-co/acme-app]
    - name: codebase-conventions
    args:
    conventions_repo: [acme-co/acme-app]
    - name: active-tickets
    args:
    tracker: jira
    ticket_project: [ACME]
    You get a file that runs three extractors every day at 07:00 UTC. The task name extractors makes it write knowledge:acme. Any other task name writes knowledge:acme.<task>, which agents read but plan build --with-knowledge does not.
  2. Check that every login it needs is set.
    $ briar secrets doctor --examples runbooks/
    You get one line per extractor. A line with MISSING names the variable to set. The command exits 1 if anything is missing.
  3. Run it once now.
    $ briar runbook extract runbooks/acme.yaml
    You get a fresh knowledge:acme and a table row per task: written, skipped (no change), or failed.
  4. Turn on failure alerts. Briar sends one when a runbook task fails.
    $ export BRIAR_NOTIFY_SINKS=slack
    $ export SLACK_ACME_WEBHOOK_URL=https://hooks.slack.com/services/T000/B000/XXXX
    You get a Slack message for each failed task. Other sinks are email, pagerduty and telegram; list several with commas.
  5. Start the scheduler and leave it running.
    $ briar runbook serve runbooks/
    You get a process that loads every *.yaml in the folder and runs each task at its time. It waits for the first time; it does not run at start. Keep it alive with your usual tool (systemd, tmux, a container).
  6. Optional: look at it in a browser.
    $ briar dashboard --examples runbooks/
    You get a read-only page at http://127.0.0.1:8080 with the schedules, host health and GitHub API quota.

Also keep a full AWS inventory

The knowledge blob keeps AI prompts small, so it holds counts, not every resource. To keep the full list too, turn on the inventory option in the runbook:

knowledge:
store: file
name: knowledge:acme
config:
inventory: "true"
$ briar runbook extract runbooks/acme.yaml
$ briar context list --prefix inventory:
$ briar context get inventory:acme | jq -r '.sections[].title'

You get an extra blob, inventory:acme, with the full data in JSON. It is only rewritten when something changed. For a one-off dump, use briar extract --include aws-infra --aws-extract-service tagging-inventory --out-json acme-aws.json.

6. Feed Claude Code or an MCP host

Goal: let the AI tools you already use know what briar knows.

  1. Give Claude Code a pointer to your knowledge.
    $ briar extract --include codebase-conventions --include review-nits \
    --merge-claude-md --blob-name knowledge:acme.claude
    You get the full text in .briar/knowledge/acme.md, and a short index in ./CLAUDE.md that tells Claude Code when to read it. The index sits between two markers. A re-run replaces only that block, so your own text in the file stays. --blob-name keeps your main knowledge:acme as it was.
  2. Or share briar as MCP tools. Install the extra first.
    $ pip install "briar-cli[mcp]"
    $ briar mcp serve
    You get an MCP server on stdio. Your MCP host starts it for you; add it to the host's config. For Claude Code, that is a .mcp.json file in your repo:
    {
    "mcpServers": {
    "briar": { "command": "briar", "args": ["mcp", "serve"] }
    }
    }
    The host can then list and read blobs, and run extracts. Tools that change things only act when called with confirm=true; without it they show a preview.
  3. Or chat with briar in your terminal.
    $ briar chat --llm anthropic
    You get an assistant that uses the same MCP tools. It asks you before anything that changes data.

To reach the server from another machine, see MCP over HTTP.

7. Audit what a plan did

Goal: after a plan run, see what it picked, why, and what happened to each card.

  1. Find the session.
    $ briar journal list --command plan.run --limit 5
    You get the five newest plan runs, newest first. Each line has the session ID, the plan and repo, the number of decisions, and the start time.
  2. Read it.
    $ briar journal show 3f9a1c2b7d4e
    You get a markdown timeline: each selector pick and its reason, each card start and its done or failed result, any replan, and why the run stopped.
  3. See where the cards ended up.
    $ briar plan status q3
    You get done, in progress, blocked and pending cards. Blocked cards show the reason from their last try.
  4. Keep a copy, or share it.
    $ briar journal export 3f9a1c2b7d4e --as json --out q3-run.json
    You get the whole session in a JSON file.
  5. Fix a card by hand if needed.
    $ briar plan advance q3 --card KAN-7 --status pending
    You get card KAN-7 back in the queue, so the next plan run can pick it again.

Plain agent runs are not in the journal

Only plan run and scaffold write journal sessions. A plain agent implement or agent prfix prints its final message and commit list to your terminal. Save that output if you need a record.

8. A full day with briar

Put together, the flows above make one day of work:

  1. Morning: the scheduler from flow 5 has refreshed knowledge:acme.
  2. Build or update the plan for the sprint board (flow 4) and ship one card.
  3. Answer review comments on yesterday's PRs (flow 3).
  4. Ship the rest of the board with --continue-on-failure.
  5. End of day: read the journal (flow 7) and unblock any card that needs a person.

Where to go next