Lockstep MCP

锁定MCP


Lockstep MCP是一个多代理协调服务器，使Claude、Codex和其他AI代理能够在同一项目上协同工作，而不会发生冲突。它提供共享状态（任务、锁、注释），以便代理可以协调他们的工作。

快速开始

# Install (one-time)
git clone https://github.com/Tmmoore286/lockstep-mcp.git ~/lockstep-mcp
cd ~/lockstep-mcp && npm install && npm run build && npm link
lockstep-mcp install --all

# Enable in your project
cd /path/to/your/project
lockstep-mcp init

# Start the dashboard (optional)
lockstep-mcp dashboard

然后告诉克劳德“你是规划者”，告诉Codex“你是实施者”。

特性

• 任务管理 -创建、分配和跟踪具有复杂性级别的任务，并审查工作流程
• 文件锁定 -防止多个代理编辑相同文件时发生冲突
• Git工作树隔离 -用于复杂/并行工作的可选隔离分支
• 实时仪表盘 -监视web UI中的所有代理、任务和锁
• 讨论系统 -代理可以讨论架构决策
• 多平台发射器 -tmux和macOS终端启动器

对于AI代理：安装说明

如果您是人工智能代理（Claude、Codex或类似代理），并被要求安装lockstep mcp，请严格遵循以下步骤：

步骤1：克隆和构建

cd ~
git clone https://github.com/Tmmoore286/lockstep-mcp.git
cd lockstep-mcp
npm install
npm run build

步骤2：全局安装（可选但推荐）

npm link

这使得 lockstep-mcp 命令在系统范围内可用。

步骤3：添加到MCP配置

运行install命令自动配置lockstep mcp：

lockstep-mcp install --all

这为Claude Code添加了lockstep mcp(~/.mcp.json 或项目 .mcp.json)食品法典委员会(~/.codex/config.toml).

替代方案：仅针对特定工具进行安装：

lockstep-mcp install --claude    # Claude Code only
lockstep-mcp install --codex     # Codex only

步骤4：在项目中启用

导航到要使用协调的项目：

cd /path/to/your/project
lockstep-mcp init

这为以下内容添加了协调说明 CLAUDE.md （如果文件不存在，则创建该文件）。说明书告诉代理商如何使用lockstep mcp。

步骤5：验证安装

lockstep-mcp status

您应该看到如下输出：

Lockstep MCP Status
──────────────────────────────────────────────────

Global Installation:
  Claude: ✓ Installed
  Codex:  ✓ Installed

Current Project (/path/to/your/project):
  Coordination: ✓ Enabled

步骤6：重新启动AI工具

安装后，重新启动Claude Code和/或Codex，以便他们获取新的MCP服务器配置。

______________________________________________________________________

对于AI代理：如何使用Lockstep

安装后，协调工作如下：

启动协调会话

当您开始在启用了lockstep的项目中工作时，请调用 coordination_init 工具与您的角色：

coordination_init({ role: "planner" })   // If you're planning/creating tasks
coordination_init({ role: "implementer" }) // If you're implementing tasks

如果你是规划师

规划者会自动经历这些阶段：

第1阶段-收集信息：

1. 呼叫 coordination_init({ role: "planner" })
2. 如果不存在项目上下文，请询问用户：

- 这个项目是什么？ - 理想的最终状态/目标是什么？ - 正在使用哪些技术？ - 是否有任何约束或要求？ - 验收标准是什么？ - 完成后应该通过哪些测试？

1. 呼叫 project_context_set 所有的细节

第2阶段-创建实施计划：

1. 根据项目背景，制定详细的实施计划
2. 呼叫 project_context_set 再次与 implementationPlan 数组
3. 将状态设置为“就绪”

第3阶段-创建任务：

1. 使用创建具体、可操作的任务 task_create
2. 询问用户他们更喜欢哪种类型的实现器（Claude或Codex）
3. 使用 launch_implementer 生成workers（简单项目1-2个，复杂项目更多）

第4阶段-监控：

1. 定期检查 task_list 和 note_list
2. 通过以下方式回答实施者的问题 note_append
3. 添加更多实施者 launch_implementer 如有需要
4. 所有任务完成后，致电 project_status_set 状态为“完成”
5. 要停止所有工作，请致电 project_status_set 状态为“已停止”

如果你是执行者

实施者在 连续循环 直到项目停止或完成：

CONTINUOUS WORK LOOP:
1. Call task_list to see available tasks (also returns projectStatus)
2. If projectStatus is "stopped" or "complete" -> STOP working
3. If tasks available, call task_claim to take a "todo" task
4. Call lock_acquire before editing any file
5. Do the work
6. Call lock_release when done with file
7. Call task_update to mark task "done"
8. REPEAT from step 1

重要： 继续工作，直到所有任务都完成或项目停止。不要在任务之间等待用户输入。

项目状态

禁用锁定步骤

如果用户说“不要使用锁步”或“独立工作”，请停止使用锁步工具并正常工作。

______________________________________________________________________

人类：快速入门

1.安装

git clone https://github.com/Tmmoore286/lockstep-mcp.git
cd lockstep-mcp
npm install
npm run build
npm link

2.配置

lockstep-mcp install --all

3.在项目中启用

cd /path/to/your/project
lockstep-mcp init

4.开始协调

在您的项目中打开Claude和Codex。告诉其中一个“你是规划者”，另一个则是“你是实施者”。他们会自动协调。

______________________________________________________________________

CLI命令参考

______________________________________________________________________

MCP工具参考

协调工具

任务工具

任务复杂性级别：

• simple -1-2个文件，明显修复，无架构决策
• medium -3-5个文件，有些模糊，需要验证
• complex -6+个文件、架构决策、跨系统影响
• critical -数据库模式、安全性会影响其他产品（需要计划员批准）

任务隔离模式：

• shared （默认）-实现程序在主目录中使用文件锁工作
• worktree -实现者获得具有自己分支的隔离git工作树（适合复杂/并行工作）

锁定工具

笔记工具

文件工具

讨论工具

工作树工具

其他工具

______________________________________________________________________

协调工作原理

共享数据库

所有代理都连接到相同的SQLite数据库 ~/.lockstep-mcp/data/coordinator.db。它们是这样共享状态的：

┌─────────────────────────────────────────────────────┐
│                   lockstep-mcp                      │
│              (shared SQLite database)               │
│                                                     │
│  • Tasks (todo, in_progress, done)                  │
│  • Locks (which files are being edited)             │
│  • Notes (inter-agent messages)                     │
│  • Project Context (description, goals)             │
└─────────────────────────────────────────────────────┘
        ▲                                    ▲
        │                                    │
   ┌────┴────┐                          ┌────┴────┐
   │ Claude  │                          │  Codex  │
   │(planner)│                          │(implmtr)│
   └─────────┘                          └─────────┘

角色分配

角色没有提前配置。当代理启动时，用户告诉它要扮演的角色：

• “你是策划者”→ 客服电话 coordination_init({ role: "planner" })
• “你是执行者”→ 客服电话 coordination_init({ role: "implementer" })

这意味着您可以使用任何组合：

• Claude担任策划人+Codex担任执行人
• Codex作为规划者+Claude作为实施者
• 两个Codex实例（一个规划者，一个实施者）
• 多个实施者

预防冲突

代理使用锁来防止同时编辑同一文件：

1. 编辑前 src/app.ts:

   lock_acquire({ path: "src/app.ts", owner: "codex" })

1. 编辑文件

1. 编辑后：

   lock_release({ path: "src/app.ts" })

如果另一个代理试图获取已锁定文件的锁，他们将收到错误并应等待。

Git工作树隔离

对于复杂或并行工作，代理可以使用隔离的git工作树而不是文件锁：

# Planner creates a task with worktree isolation
task_create({
  title: "Major refactor",
  complexity: "complex",
  isolation: "worktree"
})

# Launch implementer with worktree isolation
launch_implementer({
  name: "impl-1",
  type: "claude",
  isolation: "worktree"
})

使用工作台时：

• 每个实现者都有自己的分支（例如。， lockstep/impl-1)
• 无需文件锁-完全隔离
• 实施者经常提交更改
• 规划师使用 worktree_status 检查进度
• 规划师使用 worktree_merge 合并已批准的更改

最佳实践：

• 共享隔离 （默认）：简单/中等任务，快速编辑
• 工作树隔离：复杂的重构、并行功能、涉及许多文件的任务

______________________________________________________________________

禁用锁定步骤

关闭锁步的多种方法：

______________________________________________________________________

安全模型

锁步MCP被设计为 本地开发工具 在你的机器上运行。威胁模型是“防止代理逃离沙盒”，而不是“防御外部攻击者”

文件访问控制

# Restrict to specific directories
lockstep-mcp install --all --mode strict --roots /path/to/project,/tmp

在严格模式下，任何超出允许根的文件操作都将失败。

命令执行控制

这 command_run 该工具执行shell命令。通过以下方式进行控制：

# Only allow specific commands
lockstep-mcp install --all --command-mode allowlist --command-allow "npm,node,git,make"

allowlist检查 第一个词 命令（例如。， npm install 检查 npm).

推荐的安全设置

对于类似生产的安全性：

lockstep-mcp install --all \
  --mode strict \
  --roots /path/to/project \
  --command-mode allowlist \
  --command-allow "npm,node,git,make,pytest"

对于典型开发（默认）：

lockstep-mcp install --all  # Uses open mode, all commands allowed

Lockstep不能防止什么

• 恶意提示：如果你告诉代理删除文件，它会尝试
• 网络渗透：如果底层工具允许，代理可以发出网络请求
• 权限提升：Lockstep使用您的用户权限运行

______________________________________________________________________

配置选项

安装时，您可以自定义服务器：

lockstep-mcp install --all --mode strict --roots /path/to/project,/tmp

______________________________________________________________________

仪表盘

实时查看协调状态：

lockstep-mcp dashboard

然后打开http://127.0.0.1:8787在浏览器中。

仪表板显示：

• 项目状态 -动态状态（进行中、暂停、完成）
• 所有任务 -具有状态、复杂性、隔离模式和所有者
• 实施者 -包含当前任务、审核队列和完成统计信息
• 活动文件锁 -谁锁了什么
• 最近的笔记 -代理间通信

交互功能：

• 点击活动实施者卡以聚焦其终端窗口（macOS）
• 通过WebSocket实时更新
• 自动检测死执行器进程

______________________________________________________________________

tmux启动器

使用一个命令在tmux窗口中启动Claude和Codex：

lockstep-mcp tmux --repo /path/to/your/project

这将创建：

• 窗口1:克劳德
• 窗口2：食品法典
• 窗口3：仪表板

切换窗口 Ctrl-b n （下一页）或 Ctrl-b p （以前）。

选项：

• --session -tmux会话名称（默认值： lockstep)
• --layout windows|panes -单独的窗口或拆分窗格
• --no-dashboard -跳过启动仪表板
• --no-prompts -不自动注入协调提示

______________________________________________________________________

macOS终端启动器

在单独的macOS终端窗口中启动：

lockstep-mcp macos --repo /path/to/your/project

为Claude、Codex和Dashboard打开三个终端窗口。

______________________________________________________________________

故障排除

“lockstep mcp：找不到命令”

跑 npm link 在lockstep mcp目录中，或使用完整路径：

node /path/to/lockstep-mcp/dist/cli.js status

SQLite安装失败（节点gyp错误）

Lockstep使用SQLite进行协调状态。预构建的二进制文件可用于大多数平台（macOS、Windows、x64上的Linux/arm64），但如果您看到编译错误：

选项1：安装构建工具

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt-get install build-essential python3

# Windows (run as admin)
npm install -g windows-build-tools

选项2：改用JSON存储

lockstep-mcp install --all --storage json

JSON存储在没有本机依赖的情况下工作，但对于大型项目来说速度稍慢。

特工看不到锁步工具

1. 检查安装： lockstep-mcp status
2. 重启人工智能工具（Claude/Codex）
3. 在AI工具中，运行 /mcp 查看已连接的服务器

代理人不协调

1. 确保两者都在同一个项目目录中
2. 检查一下 lockstep-mcp init 在那个项目中运行
3. 验证两个代理都可以呼叫 coordination_init

锁定冲突

如果代理在持有锁时崩溃：

# View locks
lockstep-mcp dashboard

# Or manually clear via the database
sqlite3 ~/.lockstep-mcp/data/coordinator.db "UPDATE locks SET status='resolved' WHERE status='active'"

______________________________________________________________________

示例工作流程

1.设置（一次）

# Install lockstep-mcp
cd ~/lockstep-mcp
npm install && npm run build && npm link

# Add to AI tools
lockstep-mcp install --all

2.启动项目

# Enable in your project
cd ~/my-project
lockstep-mcp init

# Start dashboard (optional)
lockstep-mcp dashboard &

3.打开人工智能工具

1号航站楼（克劳德）：

cd ~/my-project
claude

然后告诉克劳德：“你是规划师。我们正在建设\[描述项目\]。”

2号航站楼（食品法典委员会）：

cd ~/my-project
codex

然后告诉Codex：“你是执行者。检查任务的锁步。”

4.看着他们合作

• Claude根据项目描述创建任务
• 食品法典委员会声称任务，执行任务，标记任务完成
• 两者都使用锁来避免文件冲突
• 两者都使用笔记进行交流

______________________________________________________________________

许可证

MIT。看 LICENSE.