Lockstep MCP

Lockstep MCP is a multi-agent coordination server that enables Claude, Codex, and other AI agents to work together on the same project without conflicts. It provides shared state (tasks, locks, notes) so agents can coordinate their work.

Quick Start

# 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

Then tell Claude "you're the planner" and Codex "you're the implementer".

Features

• Task Management - Create, assign, and track tasks with complexity levels and review workflow
• File Locking - Prevent conflicts when multiple agents edit the same files
• Git Worktree Isolation - Optional isolated branches for complex/parallel work
• Real-time Dashboard - Monitor all agents, tasks, and locks in a web UI
• Discussion System - Agents can discuss architectural decisions
• Multi-platform Launchers - tmux and macOS Terminal launchers

For AI Agents: Installation Instructions

If you are an AI agent (Claude, Codex, or similar) and have been asked to install lockstep-mcp, follow these steps exactly:

Step 1: Clone and Build

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

Step 2: Install Globally (Optional but Recommended)

npm link

This makes the lockstep-mcp command available system-wide.

Step 3: Add to Your MCP Configuration

Run the install command to automatically configure lockstep-mcp:

lockstep-mcp install --all

This adds lockstep-mcp to both Claude Code (~/.mcp.json or project .mcp.json) and Codex (~/.codex/config.toml).

Alternative: Install for specific tools only:

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

Step 4: Enable in the Project

Navigate to the project where you want to use coordination:

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

This adds coordination instructions to CLAUDE.md (creates the file if it doesn't exist). The instructions tell agents how to use lockstep-mcp.

Step 5: Verify Installation

lockstep-mcp status

You should see output like:

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

Global Installation:
  Claude: ✓ Installed
  Codex:  ✓ Installed

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

Step 6: Restart Your AI Tools

After installation, restart Claude Code and/or Codex so they pick up the new MCP server configuration.

---

For AI Agents: How to Use Lockstep

Once installed, here's how coordination works:

Starting a Coordination Session

When you start working in a project with lockstep enabled, call the coordination_init tool with your role:

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

If You're the Planner

The planner goes through these phases automatically:

Phase 1 - Gather Information:

1. Call coordination_init({ role: "planner" })
2. If no project context exists, ask the user:
   • What is this project?
   • What is the desired end state/goal?
   • What technologies are being used?
   • Any constraints or requirements?
   • What are the acceptance criteria?
   • What tests should pass when complete?
3. Call project_context_set with all the details

Phase 2 - Create Implementation Plan:

1. Based on the project context, create a detailed implementation plan
2. Call project_context_set again with the implementationPlan array
3. Set status to "ready"

Phase 3 - Create Tasks:

1. Create specific, actionable tasks using task_create
2. Ask the user what type of implementer they prefer (Claude or Codex)
3. Use launch_implementer to spawn workers (1-2 for simple projects, more for complex ones)

Phase 4 - Monitor:

1. Periodically check task_list and note_list
2. Respond to implementer questions via note_append
3. Add more implementers with launch_implementer if needed
4. When all tasks are done, call project_status_set with status "complete"
5. To stop all work, call project_status_set with status "stopped"

If You're the Implementer

Implementers run in a continuous loop until the project is stopped or complete:

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

IMPORTANT: Keep working until all tasks are done or project is stopped. Do NOT wait for user input between tasks.

Project Status States

Status	Meaning
planning	Planner is gathering information and creating plan
ready	Plan is ready, tasks can be created
in_progress	Implementers are actively working
complete	All work is done
stopped	Planner has halted all work

Disabling Lockstep

If the user says "don't use lockstep" or "work independently", stop using lockstep tools and work normally.

---

For Humans: Quick Start

1. Install

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

2. Configure

lockstep-mcp install --all

3. Enable in Your Project

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

4. Start Coordinating

Open Claude and Codex in your project. Tell one "you're the planner" and the other "you're the implementer". They'll coordinate automatically.

---

CLI Commands Reference

Command	Description
lockstep-mcp install --all	Add to both Claude and Codex configs
lockstep-mcp install --claude	Add to Claude config only
lockstep-mcp install --codex	Add to Codex config only
lockstep-mcp uninstall	Remove from all configs
lockstep-mcp init	Enable coordination in current project
lockstep-mcp disable	Disable coordination in current project
lockstep-mcp enable	Re-enable coordination in current project
lockstep-mcp status	Show installation and project status
lockstep-mcp dashboard	Start the web dashboard
lockstep-mcp tmux --repo /path	Launch Claude + Codex in tmux
lockstep-mcp macos --repo /path	Launch in macOS Terminal windows
lockstep-mcp server	Start the MCP server (called by AI tools)
lockstep-mcp help	Show help

---

MCP Tools Reference

Coordination Tools

Tool	Description	Required Parameters
coordination_init	Initialize coordination session. Returns phase-specific guidance.	role: "planner" or "implementer"
project_context_set	Store project context including plan and acceptance criteria	description, endState
project_context_get	Retrieve stored project context	(none)
project_status_set	Set project status (stopped, complete, etc.)	status
launch_implementer	Launch a new implementer agent in a terminal window	type ("claude" or "codex"), name
implementer_list	List all registered implementers	(none)

Task Tools

Tool	Description	Required Parameters
task_create	Create a new task	title
task_claim	Claim a task (sets status to in_progress)	id, owner
task_update	Update a task	id
task_list	List tasks with optional filters. Also returns projectStatus.	(none)
task_submit_for_review	Submit completed task for planner review	id, owner, reviewNotes
task_approve	Planner approves a task	id
task_request_changes	Planner requests changes on a task	id, feedback

Task Complexity Levels:

• simple - 1-2 files, obvious fix, no architectural decisions
• medium - 3-5 files, some ambiguity, needs verification
• complex - 6+ files, architectural decisions, cross-system impact
• critical - Database schema, security, affects other products (requires planner approval)

Task Isolation Modes:

• shared (default) - Implementer works in main directory with file locks
• worktree - Implementer gets isolated git worktree with own branch (good for complex/parallel work)

Lock Tools

Tool	Description	Required Parameters
lock_acquire	Lock a file before editing	path
lock_release	Release a lock	path
lock_list	List active locks	(none)

Note Tools

Tool	Description	Required Parameters
note_append	Add a note (for inter-agent communication)	text
note_list	List recent notes	(none)

File Tools

Tool	Description	Required Parameters
file_read	Read a file	path
file_write	Write to a file	path, content
artifact_read	Read an artifact	path
artifact_write	Write an artifact	path, content

Discussion Tools

Tool	Description	Required Parameters
discussion_start	Start a discussion with another agent	topic, message, author, waitingOn
discussion_reply	Reply to a discussion	id, message, author
discussion_resolve	Mark a discussion as resolved	id
discussion_inbox	Get discussions waiting on an agent	agent

Worktree Tools

Tool	Description	Required Parameters
worktree_status	Get status of an implementer's worktree	implementer
worktree_merge	Merge worktree changes back to main	implementer
worktree_list	List all active worktrees	(none)
worktree_cleanup	Clean up orphaned worktrees	(none)

Other Tools

Tool	Description	Required Parameters
status_get	Get coordinator status and config	(none)
command_run	Execute a shell command	command
tool_install	Install a tool via package manager	manager
log_append	Append to event log	event

---

How Coordination Works

Shared Database

All agents connect to the same SQLite database at ~/.lockstep-mcp/data/coordinator.db. This is how they share state:

┌─────────────────────────────────────────────────────┐
│                   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)│
   └─────────┘                          └─────────┘

Role Assignment

Roles are NOT configured in advance. When an agent starts, the user tells it which role to play:

• "You're the planner" → Agent calls coordination_init({ role: "planner" })
• "You're the implementer" → Agent calls coordination_init({ role: "implementer" })

This means you can use any combination:

• Claude as planner + Codex as implementer
• Codex as planner + Claude as implementer
• Two Codex instances (one planner, one implementer)
• Multiple implementers

Preventing Conflicts

Agents use locks to prevent editing the same file simultaneously:

1. Before editing src/app.ts:

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

2. Edit the file

3. After editing:

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

If another agent tries to acquire a lock on a file that's already locked, they'll get an error and should wait.

Git Worktree Isolation

For complex or parallel work, agents can use isolated git worktrees instead of file locks:

# 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"
})

When using worktrees:

• Each implementer gets their own branch (e.g., lockstep/impl-1)
• No file locks needed - full isolation
• Implementers commit changes frequently
• Planner uses worktree_status to check progress
• Planner uses worktree_merge to merge approved changes

Best practices:

• Shared isolation (default): Simple/medium tasks, quick edits
• Worktree isolation: Complex refactoring, parallel features, tasks that touch many files

---

Disabling Lockstep

Multiple ways to turn off lockstep:

Method	Scope	How
Natural language	This conversation	Tell agent "don't use lockstep"
MCP command	This session	/mcp disable lockstep
CLI command	This project	lockstep-mcp disable
CLI command	Global	lockstep-mcp uninstall

---

Security Model

Lockstep MCP is designed as a local development tool running on your machine. The threat model is "prevent agents from escaping their sandbox," not "defend against external attackers."

File Access Control

Mode	Behavior
open (default)	Agents can read/write any file the process can access
strict	File operations restricted to specified --roots directories

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

In strict mode, any file operation outside the allowed roots will fail.

Command Execution Control

The command_run tool executes shell commands. Control it with:

Mode	Behavior
open (default)	Any command can be executed
allowlist	Only commands in --command-allow list are permitted

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

The allowlist checks the first word of the command (e.g., npm install checks npm).

Recommended Security Settings

For production-like security:

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

For typical development (default):

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

What Lockstep Does NOT Protect Against

• Malicious prompts: If you tell an agent to delete files, it will try
• Network exfiltration: Agents can make network requests if the underlying tools allow
• Privilege escalation: Lockstep runs with your user permissions

---

Configuration Options

When installing, you can customize the server:

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

Option	Description	Default
--mode open|strict	In strict mode, file access is limited to roots	open
--roots /path1,/path2	Allowed directories (for strict mode)	Current directory
--storage sqlite|json	Storage backend	sqlite
--db-path /path/to/db	Database file location	~/.lockstep-mcp/data/coordinator.db
--command-mode open|allowlist	Command execution policy	open
--command-allow cmd1,cmd2	Allowed commands (for allowlist mode)	(none)

---

Dashboard

View coordination state in real-time:

lockstep-mcp dashboard

Then open http://127.0.0.1:8787 in a browser.

The dashboard shows:

• Project status - Dynamic status (in progress, paused, complete)
• All tasks - With status, complexity, isolation mode, and owner
• Implementers - With current task, review queue, and completion stats
• Active file locks - Who has what locked
• Recent notes - Inter-agent communication

Interactive features:

• Click on active implementer cards to focus their Terminal window (macOS)
• Real-time updates via WebSocket
• Auto-detects dead implementer processes

---

tmux Launcher

Launch Claude and Codex in tmux windows with one command:

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

This creates:

• Window 1: Claude
• Window 2: Codex
• Window 3: Dashboard

Switch windows with Ctrl-b n (next) or Ctrl-b p (previous).

Options:

• --session <name> - tmux session name (default: lockstep)
• --layout windows|panes - separate windows or split panes
• --no-dashboard - skip launching dashboard
• --no-prompts - don't auto-inject coordination prompts

---

macOS Terminal Launcher

Launch in separate macOS Terminal windows:

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

Opens three Terminal windows for Claude, Codex, and Dashboard.

---

Troubleshooting

"lockstep-mcp: command not found"

Run npm link in the lockstep-mcp directory, or use the full path:

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

SQLite installation fails (node-gyp errors)

Lockstep uses SQLite for coordination state. Prebuilt binaries are available for most platforms (macOS, Windows, Linux on x64/arm64), but if you see compilation errors:

Option 1: Install build tools

# macOS
xcode-select --install

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

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

Option 2: Use JSON storage instead

lockstep-mcp install --all --storage json

JSON storage works without native dependencies but is slightly slower for large projects.

Agent doesn't see lockstep tools

1. Check installation: lockstep-mcp status
2. Restart the AI tool (Claude/Codex)
3. In the AI tool, run /mcp to see connected servers

Agents not coordinating

1. Make sure both are in the same project directory
2. Check that lockstep-mcp init was run in that project
3. Verify both agents can call coordination_init

Lock conflicts

If an agent crashes while holding a lock:

# 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'"

---

Example Workflow

1. Setup (one time)

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

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

2. Start a Project

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

# Start dashboard (optional)
lockstep-mcp dashboard &

3. Open AI Tools

Terminal 1 (Claude):

cd ~/my-project
claude

Then tell Claude: "You're the planner. We're building [describe project]."

Terminal 2 (Codex):

cd ~/my-project
codex

Then tell Codex: "You're the implementer. Check lockstep for tasks."

4. Watch Them Collaborate

• Claude creates tasks based on the project description
• Codex claims tasks, implements them, marks them done
• Both use locks to avoid file conflicts
• Both use notes to communicate

---

License

MIT. See LICENSE.