briar

briar

briar 是一款在你自己的机器上运行的命令行工具。它能做两件事：

1. 读取团队工具中的动态（GitHub 或 Bitbucket、Jira 或 Linear、AWS、Fireflies），并将其保存为 Markdown 格式的“知识”。
2. 运行使用这些知识的 AI 编码 Agent。一个 Agent 接手工单并创建草稿 PR；另一个 Agent 修复 PR 上的审查意见。

briar 没有服务端，也不需要账号。briar 只会连接你配置的服务：代码托管平台、跟踪工具、云服务和大模型提供商。你的凭据会保留在本机的文件中。

安装

pip install briar-cli
briar version

你将获得 briar-cli 1.1.75（或更高版本）。briar 需要 Python 3.10 或更高版本。

基础安装支持 GitHub、Bitbucket、AWS、Jira、Linear、Fireflies、Anthropic (Claude) 和 AWS Bedrock，并支持文件或 Postgres 存储。它也能运行编码 Agent。通过扩展包可添加更多功能：

pip install 'briar-cli[mcp]'      # briar mcp serve, briar chat, MCP tools for agents
pip install 'briar-cli[all]'      # everything below

扩展包有 [openai]、[gemini]、[mcp]、[gcp]、[azure] 和 [vault]。

要运行 briar agent 或 briar plan run，还需要 git 和 GitHub CLI gh，因为 Agent 会调用它们。

[mcp] 扩展包会添加三项功能：

• briar mcp serve 和 briar chat。没有它们，这些命令无法启动。
• 运行手册中 mcp: 下列出的工具服务器。使用此类运行手册的 Agent 运行会在缺少扩展包时停止。
• 两个供 Agent 使用的小型辅助工具：“think”和“time”。缺少扩展包时，briar 会跳过它们，记录一条警告，然后继续运行。

从 1.1.74 版开始，普通安装也可以运行 Agent。旧版本会停止运行并提示 MCP support requires the `mcp` package，除非你传入 --no-default-mcp。

快速入门

# 1. Save a GitHub token and Jira login. They go to ~/.config/briar/secrets.env
briar auth login github-pat --company acme
briar 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:acme
briar extract --company acme --repo acme-co/acme-app \
    --include pr-archaeology --include codebase-conventions --max 50

# 4. Read what was saved
briar 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 PR
briar agent implement --company acme --repo acme-co/acme-app \
    --ticket-key ACME-42 --tracker jira

完成第 3 步后，你会得到 ./knowledge/knowledge/acme.md。完成第 6 步后，你会得到分支 chore/acme-42，以及在 acme-co/acme-app 上创建的草稿 PR。

使用 .briar.toml 减少输入

每项设置都会按以下顺序查找：你输入的标志、环境变量、.briar.toml，然后是内置默认值。仓库所有者和名称也可以从 git origin 远程仓库获取。

在仓库中创建一个初始配置文件：

briar init --company acme

你会得到一个 .briar.toml，其中的公司、存储位置和仓库信息取自 git。[agent] 部分默认注释掉了。取消注释即可设置 Agent 默认值：

company = "acme"
store   = "file"

[repo]
owner    = "acme-co"
repo     = "acme-app"
provider = "github"

[agent]
model          = "claude-sonnet-4-6"
git_user_name  = "Acme Bot"
git_user_email = "[email protected]"

在该仓库中，命令会变得更简短：

briar extract --include pr-archaeology
briar agent implement --ticket-key ACME-42

briar config show 会打印每项设置及其来源。 briar doctor 会检查配置、git、凭据和存储。 eval "$(briar completion bash)" 会启用 Tab 补全（zsh 也适用）。 请参阅 setup.md。

使用 Docker 运行

镜像 iklob1/briar 包含 briar、[mcp] 扩展包、git 和 gh。 无需安装其他内容：

docker run --rm iklob1/briar version

要在仓库上工作，请挂载仓库和 briar 配置文件夹：

docker run --rm \
    -v "$PWD":/work -w /work \
    -v "$HOME/.config/briar":/home/briar/.config/briar \
    -e ANTHROPIC_API_KEY \
    iklob1/briar extract --company acme --include pr-archaeology

• -v "$PWD":/work -w /work 会挂载你的仓库，因此 .briar.toml 和 ./knowledge 可以像在你的机器上一样使用。
• -v "$HOME/.config/briar":/home/briar/.config/briar 会挂载 briar auth login 保存的凭据。
• -e ANTHROPIC_API_KEY 会传入 shell 中的变量。其他变量可重复使用 -e。已保存的凭据无需使用 -e。

某些命令需要额外设置：

命令	添加项
auth login	-it，因为命令会要求你粘贴令牌。
dashboard	-p 8080:8080，并在末尾添加 --host 0.0.0.0。
mcp serve over stdio	-i，这样 MCP 客户端才能与其通信。

docker run --rm -it -v "$HOME/.config/briar":/home/briar/.config/briar \
    iklob1/briar auth login github-pat --company acme

docker run --rm -p 8080:8080 -v "$PWD":/work -w /work \
    iklob1/briar dashboard --host 0.0.0.0

在 Docker 中运行 Agent

从 1.1.75 版本起，镜像可以运行 briar agent 和 briar plan run。添加 两个密钥，以及你的 git 用户名和邮箱：

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 --company acme --repo acme-co/acme-app \
    --ticket-key ACME-42 --tracker jira \
    --git-user-name "Dana Lee" --git-user-email [email protected]

它会执行与你在本机相同的步骤：创建分支 chore/acme-42，并在 acme-co/acme-app 中创建草稿 PR。添加 --dry-run 可先查看提示词。

• --git-user-name 和 --git-user-email 会将你的姓名和 邮箱写入提交。你也可以只读方式挂载 ~/.gitconfig： -v "$HOME/.gitconfig":/home/briar/.gitconfig:ro。
• -e GITHUB_TOKEN 可让 git push 和 gh 登录 GitHub。在 镜像中，git 会向 gh 获取登录信息，而 gh 会读取 GITHUB_TOKEN。
• -e ANTHROPIC_API_KEY 是 Claude 密钥。也可以使用 -e CLAUDE_CODE_OAUTH_TOKEN。
• Jira 密钥来自挂载的配置文件夹。
• --repo 也可以来自挂载的 .briar.toml 中的 [repo]。

须知：

• 来自 Mac 的 ~/.gitconfig 也能使用。gh auth setup-git 会将你 机器上 gh 的路径写入其中（/usr/local/bin/gh 或 /opt/homebrew/bin/gh）。从 1.1.79 版本起，镜像在这两个路径下都有 gh。 此前，推送会报错“gh: not found”。
• briar 也可以从挂载的仓库的 git origin 远程读取所有者和仓库名。 从 1.1.79 版本起，无论文件夹由谁所有，都可以正常使用。 此前，在 Linux 上，git 会拒绝不属于 uid 1000 的文件夹 （“detected dubious ownership”），因此你必须传入 --repo。
• 镜像只会设置 GitHub 的 git 登录。对于 Bitbucket，请从本地安装运行 Agent。
• 镜像设置了 BRIAR_NO_DEFAULT_MCP=1，因为其中没有 Agent 辅助工具所需的 npx 或 uvx。如果你自己的镜像添加了这些工具，可以传入 -e BRIAR_NO_DEFAULT_MCP=0。
• 镜像仅为 linux/amd64 构建。在 Apple Silicon 上，Docker 会通过模拟运行它。
• 容器以用户 briar（uid 1000）运行。在 Linux 上，你挂载的文件夹 必须可由该 uid 写入。
• 标签为 latest 和各个版本，例如 iklob1/briar:1.1.75。

命令

每个命令都有对应的手册，见 agents/。 usebriar.com/docs 上提供了相同的参考资料，并附有更多示例。

命令	功能	手册
briar extract	将你的工具读取为知识块（23 个提取器）。	extract.md
briar agent implement	接收一项工单并创建一个草稿 PR。	agent.md
briar agent prfix	修复一个 PR 中的问题并回复审查意见。	agent.md
briar plan	将 Jira 或 GitHub Projects 看板转换为计划，然后逐卡执行。	plan.md
briar runbook	从 YAML 文件运行提取器，可运行一次或按计划运行。	runbook.md
briar context	读取、写入、列出和删除知识块。	context.md
briar scaffold	为 Agent 工作流编写 JSON 配置包。	scaffold.md
briar auth	保存凭据（login、logout、list、status、refresh）。	auth.md
briar secrets	显示缺少哪些凭据（doctor、bootstrap）。	creds.md
briar journal	显示 plan run 和 scaffold 记录的决策。	journal.md
briar dashboard	提供只读状态页面。	dashboard.md
briar mcp serve、briar chat	将 briar 作为 MCP 工具提供服务，或在终端中通过聊天来驱动这些工具。	mcp.md
briar init、config show、doctor、completion	配置辅助工具。	setup.md
briar telemetry	查看或更改发送哪些使用数据。	telemetry.md
briar version	输出版本号。	version.md

将这些命令串联起来的配方见 flows.md。使用所有功能的 runbook 见 examples/all_features.yaml。

以下三个标志可用于任意命令，并可出现在命令行的任意位置：

标志	功能
--format table|json|yaml|csv|quiet	输出格式。列表默认使用 table，单条记录默认使用 json。
--verbose、-v	在 stderr 上输出调试日志。设置 BRIAR_VERBOSE=1 也有相同效果。
--version、-V	输出版本号并退出。

遥测

briar 默认会发送错误报告和使用次数统计。提示词、文件 内容、工单编号、仓库名称、路径或密钥值都不会离开你的 计算机。使用 briar telemetry off、BRIAR_TELEMETRY=off 或 DO_NOT_TRACK=1 将其关闭。

许可证

MIT。请参阅 LICENSE。