Skip to content

Get started

Install & first run.

Briar is one Python package on PyPI, named 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 CLI gh when your code is on GitHub. The agent clones with git and opens the pull request with gh.
  • For agent and plan runs: an AI key. Agents always use Anthropic, so set ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN. plan and chat can also use OpenAI, Gemini or AWS Bedrock.
  • Optional: npx (from Node) and uvx (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]"
ExtraWhat it addsYou 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

Since 1.1.74, 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 /work shares your repo folder, so briar sees your .briar.toml. briar can also read owner and repo from your origin remote. 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 user briar, whose home is /home/briar.
  • -e ANTHROPIC_API_KEY passes 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 through gh, and gh reads this token. That is how the agent pushes and opens the PR.
  • An Anthropic key: -e ANTHROPIC_API_KEY or -e CLAUDE_CODE_OAUTH_TOKEN.
  • A git name and email for the commits: --git-user-name and --git-user-email, or mount your ~/.gitconfig read-only (-v "$HOME/.gitconfig":/home/briar/.gitconfig:ro). A Mac .gitconfig where gh auth setup-git wrote /usr/local/bin/gh or /opt/homebrew/bin/gh works 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/briar folder has them.
  • The repo: a .briar.toml in 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 detail
python ok 3.11.7
briar ok 1.1.75
project config ok /home/you/acme-app/.briar.toml
git remote ok acme-co/acme-app (inferred)
llm key ok found
github token warn GITHUB_TOKEN not set - GitHub extractors/agents need it
store ok file
CheckWhat it looks atIf it is not ok
pythonYour Python version.Fail below 3.10. Install a newer Python.
briarThe installed briar version.Always ok.
project configA .briar.toml here or in a parent folder.Warn. Run briar init --company acme.
git remoteThe origin remote, to find owner and repo.Warn. Pass --repo, or set [repo] in the config.
llm keyANTHROPIC_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 tokenGITHUB_TOKEN.Warn. Run briar auth login github-pat --company acme.
storeWhich 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.

  1. Log in to GitHub. Create a classic token with the repo and read:org scopes, then paste it when asked.
    $ briar auth login github-pat --company acme
    You get GITHUB_TOKEN saved in ~/.config/briar/secrets.env. Briar loads that file every time it starts.
  2. Read the merged PRs of one repo.
    $ briar extract --company acme \
    --include pr-archaeology \
    --repo acme-co/acme-app \
    --max 25
    You get a blob named knowledge:acme, with a summary of the last 25 merged PRs. The command prints the blob name, its size and the number of sections.
  3. Read the result.
    $ briar context get knowledge:acme
    # the same text is in ./knowledge/knowledge/acme.md
    You get the markdown, printed to your terminal.

No AI key yet?

That is fine for 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

PathWhat is in it
~/.config/briar/secrets.envLogins 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.jsonYour telemetry choice, saved by briar telemetry off and friends.
~/.config/briar/install_idA random ID for this install, used by telemetry.
~/.cache/briar/update_check.jsonWhen briar last checked PyPI for a new version.
./.briar.tomlProject 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.mdWritten 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

Skip it if you want to keep your tokens for a later install. Your knowledge/ and journal/ folders stay in each project. Delete them by hand if you do not need them.