Get started
Install & first run.
briar-cli. There is no account to create and no server to run. You install it, log in to the tools you use, and run commands.Requirements
- Python 3.10 or newer. It is tested on 3.10, 3.11 and 3.12. Check yours with
python3 --version. - A bash or zsh shell. The examples on these pages use one.
- For agent runs:
git, and the GitHub CLIghwhen your code is on GitHub. The agent clones with git and opens the pull request withgh. - For agent and plan runs: an AI key. Agents always use Anthropic, so set
ANTHROPIC_API_KEYorCLAUDE_CODE_OAUTH_TOKEN.planandchatcan also use OpenAI, Gemini or AWS Bedrock. - Optional:
npx(from Node) anduvx(from uv). With the[mcp]extra, each agent run starts two small helper servers with them. If they are missing, those servers do not start, a warning is logged, and the run goes on.
You do not need an AI key to install briar or to run extract.
Install with pip
$ pip install briar-cli
You get the briar command. To keep it apart from other Python tools, install it in its own virtual environment:
$ python3 -m venv ~/.local/briar-venv$ ~/.local/briar-venv/bin/pip install -U pip$ ~/.local/briar-venv/bin/pip install briar-cli$ ln -s ~/.local/briar-venv/bin/briar ~/.local/bin/briar
The last line puts briar on your PATH, if ~/.local/bin is on it.
Optional extras
The base install covers GitHub, Bitbucket, AWS, Jira, Linear, Fireflies, Anthropic, AWS Bedrock, and the file and Postgres knowledge stores. Extras add the SDKs that only some setups need. Put the extra names in square brackets, with quotes so your shell leaves the brackets alone:
$ pip install "briar-cli[mcp]"$ pip install "briar-cli[mcp,openai]"$ pip install "briar-cli[all]"
| Extra | What it adds | You need it for |
|---|---|---|
[openai] | The OpenAI SDK. | --llm openai in plan and chat. |
[gemini] | The Google Gemini SDK (google-generativeai). | --llm gemini in plan and chat. |
[mcp] | The MCP SDK. | briar mcp serve, briar chat, and MCP servers in a runbook. Agent runs also use it for two small helper servers, but run without it. |
[gcp] | Google Cloud Run, Pub/Sub, Logging, the API client and google-auth. | --cloud gcp in extract. |
[azure] | azure-identity and the azure-mgmt libraries. | --cloud azure in extract. |
[vault] | hvac, the HashiCorp Vault client. | --cred-store vault in auth and secrets. |
[all] | Every extra above. | When you want it all. |
Agents run on a plain install
agent implement, agent prfix and plan run work with a plain pip install briar-cli. Each run tries to start two helper servers (think and time) through MCP. Without the [mcp] extra, briar skips them, logs one warning, and the run goes on. To hide the warning, pass --no-default-mcp (agent) or set BRIAR_NO_DEFAULT_MCP=1 (agent and plan run). A runbook with an mcp: block still needs the extra.Run with Docker
The image iklob1/briar has briar installed, so you do not need Python. It is built from the same release as PyPI. It holds the base install plus the [mcp] extra, on Python 3.11. Other extras are not in it. It also has git and gh, so agents run in it too (see Agents in Docker). The image is built for linux/amd64 only.
$ docker pull iklob1/briar$ docker run --rm iklob1/briar version
You get briar-cli and the version. Tags are latest and each release number, for example iklob1/briar:1.1.75.
For real work, the container needs your repo folder and your saved logins. This is the usual command:
$ docker run --rm \-v "$PWD":/work -w /work \-v "$HOME/.config/briar":/home/briar/.config/briar \-e ANTHROPIC_API_KEY \iklob1/briar extract --include pr-archaeology
-v "$PWD":/work -w /workshares your repo folder, so briar sees your.briar.toml. briar can also read owner and repo from youroriginremote. On Linux that needs 1.1.79 or later: older images refused a folder owned by another user than the container's (uid 1000).-v "$HOME/.config/briar":...shares your saved logins. The container runs as userbriar, whose home is/home/briar.-e ANTHROPIC_API_KEYpasses a key from your shell into the container. Pass other keys the same way, for example-e FIREFLIES_ACME_API_KEY.
Some commands need one more flag:
# auth login asks questions, so it needs a terminal (-it)$ docker run --rm -it -v "$HOME/.config/briar":/home/briar/.config/briar \iklob1/briar auth login github-pat --company acme# runbook serve: keep it running in the background$ docker run -d --name briar-scheduler -v "$PWD":/work -w /work \-v "$HOME/.config/briar":/home/briar/.config/briar \iklob1/briar runbook serve runbooks/# dashboard: publish the port and listen on all addresses$ docker run --rm -p 8080:8080 -v "$PWD":/work -w /work \iklob1/briar dashboard --host 0.0.0.0# mcp serve over stdio needs -i$ docker run --rm -i -v "$PWD":/work -w /work iklob1/briar mcp serve
Agents in Docker
Since 1.1.75 the image runs agent implement, agent prfix and plan run. Pass in what a local run needs:
-e GITHUB_TOKEN. The image's git logs in to GitHub throughgh, andghreads this token. That is how the agent pushes and opens the PR.- An Anthropic key:
-e ANTHROPIC_API_KEYor-e CLAUDE_CODE_OAUTH_TOKEN. - A git name and email for the commits:
--git-user-nameand--git-user-email, or mount your~/.gitconfigread-only (-v "$HOME/.gitconfig":/home/briar/.gitconfig:ro). A Mac.gitconfigwheregh auth setup-gitwrote/usr/local/bin/ghor/opt/homebrew/bin/ghworks since 1.1.79; with older images the push fails with "gh: not found". - Your tracker keys, for example the Jira ones. If you saved them with
briar auth login, the shared~/.config/briarfolder has them. - The repo: a
.briar.tomlin your folder, or--repo.
$ docker run --rm \-v "$PWD":/work -w /work \-v "$HOME/.config/briar":/home/briar/.config/briar \-e GITHUB_TOKEN -e ANTHROPIC_API_KEY \iklob1/briar agent implement --ticket-key ACME-42 --tracker jira \--git-user-name "Dana Lee" --git-user-email [email protected]
You get the same draft PR as a local run. The image sets BRIAR_NO_DEFAULT_MCP=1, because it has no npx or uvx for the helper servers. If you build an image on top that adds them, pass -e BRIAR_NO_DEFAULT_MCP=0.
The image sets up git logins for GitHub only. On Bitbucket, git has no login helper, and the agent cannot open the PR anyway (see Registries).
From source (contributors)
$ git clone https://github.com/iklobato/briar.git$ cd briar$ python3 -m venv .venv$ .venv/bin/pip install -e ".[dev]"$ .venv/bin/briar version
You get an editable install: changes to the source take effect at once. The [dev] extra adds black, mypy and ruff. Add [test] for the test tools.
Check the install
$ briar version$ briar --version
Both print the same line, for example briar-cli 1.1.75. If your shell says command not found, the folder pip installed into is not on your PATH.
First-run checks with briar doctor
Run this inside your repo:
$ briar doctor
You get one line per check. Example output:
check status detailpython ok 3.11.7briar ok 1.1.75project config ok /home/you/acme-app/.briar.tomlgit remote ok acme-co/acme-app (inferred)llm key ok foundgithub token warn GITHUB_TOKEN not set - GitHub extractors/agents need itstore ok file
| Check | What it looks at | If it is not ok |
|---|---|---|
| python | Your Python version. | Fail below 3.10. Install a newer Python. |
| briar | The installed briar version. | Always ok. |
| project config | A .briar.toml here or in a parent folder. | Warn. Run briar init --company acme. |
| git remote | The origin remote, to find owner and repo. | Warn. Pass --repo, or set [repo] in the config. |
| llm key | ANTHROPIC_API_KEY, OPENAI_API_KEY or GEMINI_API_KEY. | Warn. Agents and plans need one. It does not look at CLAUDE_CODE_OAUTH_TOKEN, so ignore the warn if you use that. |
| github token | GITHUB_TOKEN. | Warn. Run briar auth login github-pat --company acme. |
| store | Which knowledge store you picked. | Fail if the store is postgres and BRIAR_DATABASE_URL is not set. |
doctor makes no network calls. It exits with code 1 only when a check fails, so you can use it in CI. Two more checks help: briar config show lists each setting with where its value came from, and briar auth list lists which login variables are set (names only, never values).
Your first run
The shortest useful run reads one GitHub repo. It needs a GitHub token but no AI key.
- Log in to GitHub. Create a classic token with the
repoandread:orgscopes, then paste it when asked.You get$ briar auth login github-pat --company acmeGITHUB_TOKENsaved in~/.config/briar/secrets.env. Briar loads that file every time it starts. - Read the merged PRs of one repo.You get a blob named$ briar extract --company acme \--include pr-archaeology \--repo acme-co/acme-app \--max 25
knowledge:acme, with a summary of the last 25 merged PRs. The command prints the blob name, its size and the number of sections. - Read the result.You get the markdown, printed to your terminal.$ briar context get knowledge:acme# the same text is in ./knowledge/knowledge/acme.md
No AI key yet?
extract, context, runbook and the agent --dry-run. You need a key for plan build with --llm, plan next, plan run, chat, and real agent runs.Shell completion
Briar can print a tab-completion script for bash or zsh. Add one line to your shell start file:
# bash: add to ~/.bashrc$ eval "$(briar completion bash)"# zsh: add to ~/.zshrc, after compinit$ eval "$(briar completion zsh)"
Open a new terminal. Then briar pl and Tab completes to briar plan, and it also completes subcommands and flags. The script is built from the installed version, so new commands show up after an upgrade.
Where briar puts things on disk
| Path | What is in it |
|---|---|
~/.config/briar/secrets.env | Logins saved by briar auth login. Set BRIAR_SECRETS_FILE to use another file. If /etc/briar/secrets.env exists, it is used instead. |
~/.config/briar/telemetry.json | Your telemetry choice, saved by briar telemetry off and friends. |
~/.config/briar/install_id | A random ID for this install, used by telemetry. |
~/.cache/briar/update_check.json | When briar last checked PyPI for a new version. |
./.briar.toml | Project config, written by briar init. |
./knowledge/ | Knowledge blobs for the file store. Change it with --root. |
./journal/ | Journal sessions from plan run and scaffold. |
./.briar/knowledge/ and ./CLAUDE.md | Written only by briar extract --merge-claude-md. |
$TMPDIR/briar-agent-* | The temporary clone an agent works in. It is deleted after the run, unless the run failed or you passed --keep-worktree. |
The ~/.config paths move if you set XDG_CONFIG_HOME, and ~/.cache moves with XDG_CACHE_HOME.
Upgrade
$ pip install -U briar-cli$ briar version
You get the newest release. With Docker, run docker pull iklob1/briar. Briar checks PyPI at most once a day and prints a short note when a newer version exists. To stop that check, set BRIAR_NO_UPDATE_CHECK=1.
Every release is listed in the changelog. Read it before you upgrade a shared host.
Uninstall
$ pip uninstall briar-cli$ rm -rf ~/.config/briar
The second line deletes your saved logins
knowledge/ and journal/ folders stay in each project. Delete them by hand if you do not need them.