Tirith

在同一个代码仓库中运行五个或十个编码 Agent，它们会编辑相同的文件、重命名其他 Agent 依赖的内容，还会把接口的两端构建成不同的形态。Tirith 是一个小型守护进程，所有 Agent 都与之通信：Agent 在编辑前认领文件，并在认领时获取这些文件的通知、契约、决策和笔记；同时，还会在接口任一端开始实现之前，发布接口的形态。

它适用于所有支持 MCP 的工具，可通过 stdio 或 HTTP 使用：Claude Code、 Cursor、Codex、LangGraph、CrewAI，或普通脚本。

它还会记住信息。Agent 会留下按代码仓库路径划分范围的笔记，因此，一个 Agent 对某个文件的了解会传递给下一个认领该文件的 Agent。 Tirith 不存储对话历史，也不存储嵌入向量。

状态：v1 已发布。 所有基础功能、CLI、持久化功能和 控制面板均已根据 ADR-0013 中的定义完成并通过测试；工具架构遵循语义化版本控制。

安装

macOS 和 Linux：

curl -LsSf https://eabz.github.io/tirith/install.sh | sh

Windows（PowerShell）：

irm https://eabz.github.io/tirith/install.ps1 | iex

使用 cargo（软件包名为 tirith-mcp，二进制文件名为 tirith）：

cargo install tirith-mcp

已经安装？运行 tirith update，即可将二进制文件原位替换为最新版本。macOS、Linux 和 Windows 的 x86_64 与 ARM64 预构建二进制文件可在发行版页面获取；所有选项均列于docs/1-about/05-installation.md。

已列入 MCP Registry： mcp-name: io.github.eabz/tirith。

快速开始

在仓库中运行：

tirith init

此命令会在 .mcp.json 中注册 tirith stdio，并在 AGENTS.md 中写入一段简短说明（如需使用其他文件，请传入 --file）。协议本身涵盖从首次声明到由谁领导蜂群的所有内容，每次会话连接时都会作为 MCP 服务的指令传入；希望使用自有协议的仓库，可将其保存在 .tirith/instructions.md 中（运行 tirith init --instructions 会将内置协议写入该文件，供你编辑）。其他客户端可手动注册相同命令：首次会话需要时，垫片会启动仓库的守护进程；如果守护进程版本不同，则会将其替换；之后再代理请求。无需手动启动任何东西。

客户端	设置
Claude Code	claude mcp add tirith -- tirith stdio
Cursor	.cursor/mcp.json：{ "mcpServers": { "tirith": { "command": "tirith", "args": ["stdio"] } } }
Codex	codex mcp add tirith -- tirith stdio
LangGraph、CrewAI、curl	通过 HTTP 连接，参见 docs/2-examples/02-client-setup.md

守护进程在 http://127.0.0.1:7477/mcp 提供 MCP 服务，并在 http://127.0.0.1:7477/ 提供实时仪表板。状态会写入仓库中的 .tirith/：契约、通知、决策和记忆笔记适合提交到版本库；.tirith/runtime/（声明、任务、消息）则由 Tirith 自行写入的 .gitignore 忽略。

每个 Agent 在每次调用时都会传入一个稳定的 agent 名称。这是它唯一需要遵循的约定。要同时运行多个 Agent，请将 docs/2-examples/03-swarm-playbook.md 中的协议段落粘贴到项目的 Agent 指令中：其中说明哪个会话负责领导、何时启动工作 Agent、告知每个工作 Agent 的内容，以及它们各自运行的模型。守护进程也会在其指令中提供相同的规则。

功能

基元	工具	用途
声明	claim、release、renew、claims_list	编辑文件或目录前先申请租约。若存在重叠，系统会拒绝申请并告知持有者、原因和到期时间；也可在服务端通过 wait_secs 等待。Agent 退出后租约会过期，并会在下次调用时收到通知。
任务看板	task_create、task_pull、task_update、task_list	包含优先级、负责人和依赖项的任务。Agent 会领取下一个未阻塞的任务，跳过其他 Agent 正在处理的任务，也可在服务端通过 wait_secs 等待任务；负责人失联的任务会返回看板。
契约	contract_publish、contract_get、contract_list	在实现前发布并版本化接口结构。新版本会自动通知使用者。
变更通知	notice_publish、notice_list	“已将 X 重命名为 Y，这些路径会受到影响。”依赖方每次申请声明时，都会在返回的简报中收到相关通知。
决策日志	decision_record、decision_list	记录已敲定的选择及其理由，避免重复决策。
记忆笔记	memory_write、memory_read、memory_search、memory_delete	记录与仓库路径关联的经验、陷阱和交接事项。以 Markdown 格式提交，可搜索，并会发送给申请了笔记所涉路径的人员。
消息	message_send、message_list	Agent 之间的简短消息会在收件人下次调用时送达，因此任何 MCP 客户端都能参与。仅存于运行时。
状态	status	显示计数、持久化和负载问题；verbose 会额外显示各项由谁持有。

共 22 个工具，每个工具都附有所有参数的说明、MCP 注解和输出架构；连接时还会通过服务端指令提供协议（ADR-0038）。每个结果都是包含 status 字段的 JSON；列表支持分页；任何结果都可能包含 lost（已结束的租约）或 inbox（待处理消息）。完整参考文档是工具架构的唯一事实来源，见 docs/1-about/04-primitives.md。

示例

两个 Agent，一个目录。第二个会收到拒绝，并获得足够的信息来决定下一步怎么做：

tirith claim --agent alice --reason "refactor session handling" src/auth/
# ok       alice  src/auth  expires 04:14:34Z

tirith claim --agent bob --reason "fix login redirect" src/auth/login.rs
# conflict src/auth/login.rs overlaps src/auth (alice: "refactor session handling", expires 04:14:34Z)

留给下一个编辑某个路径的人的备注。Alice 写一次；Bob 认领时，这条备注会以摘录形式返回，无需任何人搜索，且不会返回正文：

tirith memory write --agent alice "Session ids are opaque" -k gotcha --path src/auth/ <<'NOTE'
Tokens are opaque strings. Compare them, never parse them.
NOTE

tirith release --agent alice
tirith claim --agent bob --reason "fix login redirect" src/auth/login.rs
# ok       bob  src/auth/login.rs  expires 04:14:34Z
# memory:
#   session-ids-are-opaque gotcha   04:04:34Z  paths src/auth  Session ids are opaque: Tokens are opaque strings. Compare them, never parse them.

完整演练包含契约、通知，以及通过原始 MCP 执行的相同调用，见 docs/2-examples/01-two-agents-demo.md；脚本见 examples/demo.sh。

CLI

每个工具都有一个子命令；CLI 使用与 Agent 相同的 MCP 路径。

tirith serve                               # run the repo's daemon by hand
tirith stdio                               # per-session shim clients spawn; starts the daemon if needed
tirith update                              # replace the binary with the latest release
tirith status                              # counts, and who holds what
tirith init [--file AGENTS.md] [--instructions]  # register the server, add the agents block
tirith claim | release | renew | claims
tirith task     create | pull | update | list
tirith contract publish | get | list
tirith notice   publish | list
tirith decision record | list
tirith memory   write | read | search | delete   # body from --body, --file, or stdin
tirith message  send | list                # talk to other agents; the inbox shows on any result
tirith lead log                            # the swarm lead and its policy's decisions
tirith lead human                          # items waiting for you, most agents blocked first
tirith lead human done <id> [--reply TEXT] # answer one; the reply reaches its sender
tirith tray                                # macOS only: menu bar icon listing every daemon
tirith tools                               # list tools with descriptions
tirith call <tool> '<json>'                # call any tool directly

--agent 用于设置你的名称，--json 用于打印原始结果，非 ok 的结果会以状态码 1 退出。

Swarm 负责人和升级处理

启动其他 Agent 的会话会认领保留路径 .tirith/lead，并成为 swarm 负责人；status 和仪表板会显示持有者。随后，守护进程会按照固定规则处理常规升级，无需消耗一次大模型调用：

• **负责人的权限：**持有 .tirith/lead 期间，只有负责人可以发布契约、创建任务、记录决策、删除记忆备注，以及强制接管其他 Agent 的任务；其他人会收到 conflict，其中注明负责人，并可通过 message_send 提议更改 (ADR-0036)。没有负责人时，不会限制任何操作。负责人也是唯一可以提交、推送、创建拉取请求或部署的会话 (ADR-0037)。
• **升级条件：**任务被设为 blocked（其备注即为原因），或 360 s 内同一认领请求第三次遭到拒绝。发给负责人的消息不会触发升级。
• **升级去向：**有负责人时，升级会作为来自 tirith 的消息发送到负责人的收件箱；若涉及凭据、权限、开支或破坏性步骤，则会标记为“可能需要人工介入”。不会有任何消息主动送达你：负责人会通过 message_send 向 human 转发需要你处理的事项，并使用面向你的措辞。没有负责人时，升级会发送到你的队列。
• **你的队列：**包括仪表板的“需要你处理”列表、tirith lead human、仪表板端口上的 /api/human，以及 macOS 菜单栏应用。菜单栏应用会列出每条消息的发送者和首行，并在有新消息时通知你。点击仪表板上的 Done 按钮，或运行 tirith lead human done <id> --reply "..." 回复；回复会作为来自 human 的消息发送给发件人。

认领获准、拒绝、等待、释放和租约结束、通知推送以及升级处理都会追加到负责人决策日志中：运行 tirith lead log，或访问仪表板端口上的 /api/lead。设计说明： ADR-0027；各工具说明见： 04-primitives.md。

文档

Section	Contents
1-about	项目目的、架构、项目结构、工具参考、安装
2-examples	演示、所有受支持框架的客户端配置，以及 swarm 指南：负责人、工作 Agent、简报、模型
3-tests	测试策略
4-style	Rust 规则及其依据、Git 约定
5-decisions	架构决策记录
6-agent-workflow	Agent 如何在此仓库中工作：Serena、记忆、Tirith 自身
7-release	发布流程和版本号更新
index.html	位于 eabz.github.io/tirith 的落地页

贡献

编码 Agent 必须先阅读 AGENTS.md。本仓库由 Tirith 自身协调：守护进程会为该仓库运行，Agent 编辑文件前必须先通过它认领文件。 .agents/skills/ 中的技能说明了具体方法。

许可证

MIT