mozak

每个项目一份经批准的计划，由你的编码 Agent 共享，并可在 Obsidian 中查看。

你关注的是构想和计划，而不是代码。多个 Agent 共享同一份计划，互不覆盖；你可以在笔记中跟进它们的进度。

项目介绍 · 观看演示 · 安装 · 工作原理 · 在 Obsidian 中查看一切 · 安全性 · 测试情况 · 文档

观看演示

预览以双倍速播放。76 秒内：你用日常语言向 Agent 提出需求，它读取项目并提出一个问题，起草计划并等待你确认，记录测试结果，Obsidian 中的路线图随之推进。Obsidian 画面是插件根据文件重新绘制的实时录制。终端画面则是 Agent 对话的渲染重现，其中运行的是同一组 mozak 命令。点击观看带声音的完整视频。

项目介绍

**mozak 为每个项目提供一份共享计划，以纯文件形式存储在项目文件夹中（公开仓库则存储在你的笔记中）。**它负责两件事：

• **Agent 读取同一份计划。**加载 mozak 技能或 MCP 服务的 Agent 都会基于同一份计划开始工作，因此你不必向每个 Agent 分别粘贴上下文。Agent 可以提出更改，但只有经你批准后，内容才会成为计划。
• **你可以在 Obsidian 中跟进。**每个项目的计划都会显示在你的知识库中，包含路线图和进度，让并行工作一目了然。由你批准下一步。Agent 记录了通过的证据（例如报告一次测试运行）后，对应结果会变为绿色。mozak 不会自行运行测试；你标记为自己负责的结果，也需要你签字确认。

值得信赖的原因：

• 它只是文件。mozak.json 保存计划，mozak.md 是易读的副本。它们与 README.md 放在一起；如果文件夹位于 git 中，git 就会保存历史记录。没有云服务、没有账户、没有守护进程。
• **由你掌控。**同意做什么与同意开始构建是两项独立的批准。
• **多个 Agent，井然有序。**通过 mozak 提交的更改如果基于过时副本，会被拒绝，而不会覆盖其他人的工作。
• **仓库与笔记兼顾。**项目可以是本地文件夹、Obsidian 知识库文件夹，也可以是你甚至还没有克隆的 GitHub 仓库。

mozak 面向已经使用编码 Agent、希望它们共享一份计划的开发者和研究人员。它适用于任何能够加载技能或 MCP 服务的 Agent。目前已验证：jcode（技能和 MCP）以及 Claude Code（MCP）。

安装

你需要 Node 24.11 或更高版本（Node 26 也可）和 Git。适用于 Linux 和 macOS。

npm install -g mozak
mozak doctor --fix      # links the mozak skill into ~/.claude/skills, ~/.jcode/skills or ~/.codex/skills if they exist

npm 包将 CLI 和 MCP 服务打包在同一个无依赖、无安装脚本的包中。使用 npm install -g mozak@latest 更新。

将 Agent 连接到 MCP 服务（使用你自己的清单路径）：

# Claude Code
claude mcp add mozak -- mozak-mcp --config "$HOME/notes/mozak-inventory.json"
# Codex
codex mcp add mozak -- mozak-mcp --config "$HOME/notes/mozak-inventory.json"

其他任何 MCP 客户端：命令为 mozak-mcp，参数为 --config /path/to/mozak-inventory.json。

mozak scopes 和 Obsidian 侧边栏会告知你有新版本发布（MOZAK_NO_UPDATE_CHECK=1 可关闭此功能）。更改记录见 CHANGELOG.md。

git clone https://github.com/pitfa19/mozak.git && cd mozak
npm ci --ignore-scripts && npm run build
mkdir -p "$HOME/.local/share"
node scripts/install.mjs --prefix "$(cd "$HOME/.local/share" && pwd -P)/mozak" --json
"$HOME/.local/share/mozak/bin/mozak" --help

mozak upgrade --vault ~/Documents/notes   # newest tagged release; the old install is kept, plugin updated in that vault
mozak doctor --fix                        # checks the whole setup; fixes links, wrappers and plugin copies, prints the rest

详情、退出代码、恢复方法和已知限制：见 docs/installation.md。

工作原理

1. 列出你的项目。 一个 mozak-inventory.json 文件会列出 mozak 可以查看的所有项目。范围命令只会操作其中列出的项目。将它放在笔记文件夹的顶层，这样 Obsidian 插件就能自动找到它。

{
  "format": "mozak.local/v3",
  "scopes": [
    { "id": "my-app",     "root": "./my-app" },
    { "id": "lab-notes",  "root": "./vault/lab-notes" },
    { "id": "genome-mcp", "remote": "github:you/genome-mcp", "ref": "main" },
    { "id": "my-oss-tool", "remote": "github:you/my-oss-tool", "plans": "./vault/my-oss-tool" }
  ]
}

带有 root 的项目是本地文件夹。带有 remote 的项目是 GitHub 仓库。计划存放的位置取决于谁应该能看到它们：

• 私有仓库：计划存放在仓库内，因此所有有权限的人都能共享。mozak 只会检出 README.md、AGENTS.md 和两个 mozak 文件（稀疏浅克隆），并将计划更改推送回去。
• 公开仓库：添加 "plans" 并指定一个文件夹，通常位于你的笔记文件夹中。计划会保存在那里，仅对你私有，并且绝不会提交到仓库。mozak 一旦发现存放计划的仓库已变为公开，就会拒绝写入（每天最多检查一次；无法访问 API 不会阻止操作）。

mozak pull --into ~/Downloads/x 可将代码克隆到任意位置。对于公开仓库，克隆不会接收计划文件。在任何克隆中运行 mozak 读取命令时，无需使用 --scope，它会根据克隆的 Git 远程源找到项目。

2. 启动项目。 为文件夹添加 README.md 和 AGENTS.md，然后让你的 Agent 使用 mozak 技能进行设置，或者自行运行 mozak scope init（参见该技能的 references/bootstrap.md）。此操作会创建项目的 mozak.json 和 mozak.md。创建项目属于所有者命令：Agent 无法通过 MCP 执行此操作。

3. 就计划达成一致。

1. 提出方案。 Agent 起草计划，并等待批准。
2. 批准方向。 你对做什么表示同意。这会启动规划，而不是编码。
3. 批准构建。 附上规格说明，并单独批准实施。
4. 记录下来。 决策和证据会保存到项目文件中，以便下一次会话了解上一次进展到哪里。

4. 让 Agent 找到方向。 mozak scopes 会列出每个项目及其计划数量。Agent 也会从 MCP 服务获取相同的列表。

在 Obsidian 中查看所有内容

packages/obsidian 中的 Obsidian 插件会在侧边栏显示清单中的所有项目，包括笔记和 GitHub 仓库。可按 All、Open 或 Done 筛选。未完成的计划会显示一条小进度条，每个结果对应一个进度段。点击计划即可打开其在该范围 mozak.md 中的章节。该文件像笔记一样，包含用途、列出各项结果及当前进度的路线图、状态表和完整计划文本。侧边栏用于阅读和导航。你应在 Agent 聊天中批准计划，而不是在 Obsidian 中。插件绝不会批准或更改计划。它可能会重新生成已过时的 mozak.md，效果与 mozak render 相同。

在 Obsidian 中安装：依次点击 Settings, Community plugins, Browse，搜索 mozak，然后点击 Install 和 Enable（目录页面）。也可以在源代码检出目录中运行：

node scripts/install-obsidian-plugin.mjs /path/to/your/vault --build

插件会从知识库文件夹开始向上搜索 mozak-inventory.json，也可以在插件设置中指定其路径。每个 GitHub 项目都会显示一个地球或锁形徽章，表示仓库是公开还是私有。

插件披露信息（仅限桌面端，isDesktopOnly: true）： 如果 mozak-inventory.json 列出了当前知识库之外的范围，插件会从这些已配置路径读取其 mozak.json、mozak.md、README.md 和 AGENTS.md 文件，并在启用 Auto-refresh 时监视这些文件。它绝不会扫描清单中未列出的文件夹，也绝不会批准或更改计划（如果没有未合并的手动编辑，它可能会重新生成已过时的 mozak.md 投影文件）。对于远程 GitHub 范围（"remote": "github:owner/repo"，且没有由知识库托管的 "plans"），点击 Sync remote scopes 或启用 Repo sync interval (seconds) 后，插件会使用你现有的 git 登录信息，在隐藏的 .mozak-cache 副本上运行本地 git：执行 git fetch，然后将该副本重置到获取的提交。如果此前的 mozak 写入留下了尚未推送的计划提交（例如网络故障后），同步会先提交并推送待处理的 mozak.json / mozak.md 更改。将同步间隔设为 0 可关闭后台 git 操作。同步还会在无需登录的情况下请求公开 GitHub API，每个仓库每天最多一次，以确认各远程仓库是否公开。更新通知只会读取 CLI 写入的缓存文件。插件绝不会自行安装或更新，也不包含遥测功能。完整披露清单请参阅 packages/obsidian/README.md。

内部原理

Agent 会在项目文件夹中写入纯文本 mozak.json 和 mozak.md 文件。Obsidian 侧边栏以及每篇笔记中的路线图图示都根据这些文件绘制。Agent 不会编写任何 UI 代码。

与 Agent 搭配使用

每条范围命令都需要显式指定 --config。只有维护命令（upgrade、doctor）可以不指定配置。

安全性

• 限制批准范围。 批准仅对你看到的确切计划版本有效，一条消息不能重复用于第二次批准。通过 MCP 连接的 Agent 完全无法批准。技能会告知 Agent 只接受你自己的消息，不接受引文或工具输出，但 mozak 无法验证消息是谁输入的（见下文的限制）。
• 禁止覆盖。 如果通过 mozak 写入时使用的是过期副本，写入会被拒绝。手动编辑文件不受此保护。
• 限制推送内容。 对于私有 GitHub 项目，mozak 只会提交并推送 mozak.json 和 mozak.md。对于计划存放在笔记中的公开仓库，它从不提交或推送。
• 不处理凭据。 mozak 从不索要或存储凭据。GitHub 访问使用你现有的 git 登录信息。
• 如实说明限制。 批准遵循受信任主机约定，并非身份验证：拥有 shell 访问权限的 Agent 可以运行所有者命令。并发保证适用于本地磁盘上的协作进程，不适用于网络驱动器、断电或同步工具同时编辑同一文件的情况。远程范围仅跟踪一个分支。

已测试与尚未测试的内容

已测试。 450 项单元测试和集成测试，以及 74 项安装程序测试；每次向 main 推送以及每个拉取请求时，都会在 Ubuntu 和 macOS 上使用 Node 24.11 和 26 在 CI 中运行。测试涵盖：

• 拒绝过期写入，包括两个真实 CLI 进程同时写入的情况
• 写入中途被终止后能够恢复，且不会丢失数据
• 两次批准彼此独立，并绑定到你看到的版本
• 通过 MCP 连接的 Agent 无法批准或创建项目
• 公开仓库不会收到计划提交
• 安装程序会拒绝不安全的目标，且不会写入任何内容

Obsidian 插件通过了 Obsidian 的自动化社区审核。每次发布都会检查其构建和证明。

尚未证实。

• 对 Agent 的益处。 一项小规模试点（5 项代理任务、10 次 Agent 会话）对比了使用和未使用 mozak 的 Agent，发现令牌用量没有显著差异：一组表现差了 16%，另一组好转了 6%。计划进行更大规模的评估。在此之前，请将 mozak 视为一种保留一份已批准计划并在 Obsidian 中查看的方式，而非已证实能提升速度的工具。
• Agent 宿主。 已检查：加载技能和 MCP 服务的 jcode，以及通过 npm 包调用 MCP 服务的 Claude Code 2.1。Codex 和其他 MCP 客户端尚未验证。
• Obsidian 内的插件。 其视图模型经过单元测试，也进行过手动试用，但没有在 Obsidian 应用内运行的自动化测试。
• 真实 GitHub。 测试使用本地裸仓库。真实 GitHub 已手动检查。
• 不受支持的配置。 Windows、网络文件系统和已分叉的远程分支。

平台

Linux 和 macOS，Node 24.11 或更高版本。

贡献

npm ci --ignore-scripts && npm run build
npm test && npm run test:install

提交拉取请求前请运行测试。如果你的全局 git 配置添加了钩子或签名，请使用 GIT_CONFIG_GLOBAL=/dev/null 运行。格式、远程范围、退出代码和已知限制见 docs/installation.md。

许可证

MIT。参见 LICENSE。