lockstep

Lockstep

Stop your team's AI coding agents from making conflicting changes — without sharing source code.

Quick start · How it works · Deploy

When two developers point AI coding agents (Claude Code, Codex, Gemini CLI) at the same system, the agents have no idea what each other just did:

• Agent A renames an API endpoint → Agent B keeps calling the old one.
• Agent A picks an auth pattern → Agent B invents a conflicting one.
• Nobody knows who owns what, what changed, or what still needs review.

Lockstep is a neutral system-of-record for your agents. Every decision, contract change, and dependency is captured and routed to the agents that need it — in real time, and without any source code ever leaving the developer's machine (only decisions and metadata sync to the cloud).

npm i -g lockstep-cli

How it compares

How It Works

  Developer A (machine)              Lockstep Cloud              Developer B (machine)
  ────────────────────              ───────────────              ────────────────────
  ┌─────────────────┐                                           ┌─────────────────┐
  │  Claude Code    │                                           │  Codex / Gemini │
  │  + MCP Server   │──── capture ────┐                         │  + MCP Server   │
  └─────────────────┘                 │                         └─────────────────┘
         │                            ▼                                   ▲
         │                     ┌─────────────┐                            │
    hook fires on        ──→   │  Decisions   │   ──→   dependency graph  │
    every file edit            │  Contracts   │         looks up who      │
    (PostToolUse)              │  Ownership   │         consumes the      │
         │                     │  Deps Graph  │         changed surface   │
         ▼                     │   Inboxes    │              │            │
    classifies the             └─────────────┘              ▼            │
    diff as contract              Append-only          fan-out to ───────┘
    surface or owned              No source code       each consumer's inbox

The notification lifecycle

1. Capture — A Claude Code hook fires on every file edit (PostToolUse) and on session end. The CLI diffs the working tree against HEAD, classifies each changed file — is it an API route, a .proto, an OpenAPI spec, an exported function? Files that expose a public interface are flagged as contract surfaces. The change is published to the ledger with a risk tier (owned if only you touch it, shared if it's a contract surface).

2. Route — When a change hits the ledger, the dependency graph kicks in. Every repo that has registered a dependency on the changed surface gets a notification fanned out to its inbox. The sender is excluded. If repo B declared POST /auth/session as a dependency, and repo A just changed that surface, repo B's inbox gets the change — automatically, with zero configuration beyond register_dependency.

3. Replay — When an agent starts a new session (SessionStart hook), Lockstep reads the inbox and replays everything that arrived since the last session: unread changes, binding decisions, and open questions. This is injected as additionalContext so the agent is immediately aware of what teammates have done.

4. Decide — Agents can propose decisions scoped to a surface (e.g. "rename POST /auth/login to POST /auth/session"). Owner-scoped decisions are binding immediately. Shared/contract decisions stay open until another team member acknowledges them — then they become binding for the whole project.

5. Gate — At PR time, the Tier-2 reconciliation gate (a GitHub Action) checks every changed contract surface against the ledger. If a surface was changed but has no binding decision, the PR check fails. This catches anything Tier-1 missed.

Who gets notified?

What flows through the cloud (and what doesn't)

Features

Quick Start

Get a working local setup in under 5 minutes — no GitHub App keys needed.

1. Start the stack

git clone https://github.com/lockstep-team-agent/lockstep.git
cd lockstep
cp .env.example .env       # dev-login is enabled by default
docker compose up --build   # starts Postgres + API + dashboard

Wait for lockstep-core listening on :8080 in the logs. Verify:

curl http://localhost:8080/readyz
# => { "ok": true, "db": "up", "deployment": "self-host" }

This gives you:

• API at http://localhost:8080
• Dashboard at http://localhost:3000
• Postgres at localhost:5432

2. Install the CLI & log in

npm i -g lockstep-cli

# Point the CLI at your local server (saved permanently — only needed once)
lockstep login --api http://localhost:8080 --dev --dev-id 1 --dev-login alice

Important: The --api flag tells the CLI where the backend is. Without it, the CLI defaults to http://localhost:8080. For a deployed server, use lockstep login --api https://your-server.example.com.

3. Connect your repo

cd your-project              # any git repo with an origin remote
lockstep init                # installs MCP server + hooks into the repo
lockstep connect --project "my-team"   # creates a project and links this repo

4. Open the dashboard

Open http://localhost:3000 in your browser. To sign in, you need the session token. Get it with:

# macOS (token stored in keychain)
security find-generic-password -s lockstep -a session-token -w

# Linux / fallback (token stored in file)
cat ~/.lockstep/credentials.json

Paste the lsk_... token into the dashboard sign-in field.

5. Add a teammate

Your teammate runs (on their machine):

npm i -g lockstep-cli
lockstep login --api http://localhost:8080 --dev --dev-id 2 --dev-login bob
cd their-project
lockstep init
lockstep connect --project "my-team"   # joins the existing project

Both developers are now in the same project. They'll see each other on the Members page in the dashboard.

6. Start coding with your AI agent

Open Claude Code (or any MCP-compatible agent) in the repo. On session start, the agent receives a Lockstep replay of everything that happened since the last session — changes, binding decisions, open questions, and assigned tasks.

As you work, contract changes are captured automatically and routed to teammates' inboxes.

Production setup: For real GitHub-based auth (no --dev flag needed), register a GitHub App and fill in the keys in .env. Set NODE_ENV=production and LOCKSTEP_DEV_LOGIN=0. See DEPLOY.md for Railway/cloud deployment.

Project Structure

packages/core/   # Fastify API + PostgreSQL (Drizzle ORM), RLS-isolated, append-only
packages/cli/    # lockstep-cli — login, init, connect, capture, MCP server
packages/web/    # Next.js dashboard — decisions, contracts, deps, activity
actions/pr-check # GitHub Action — Tier-2 reconciliation gate for PRs

CLI Commands

Development

npm run build         # Build all workspaces
npm run typecheck     # Type-check all workspaces
npm run test          # Run all tests
npm run lint          # Lint all workspaces
npm run format        # Format with Prettier
npm run dev:core      # Start core API in watch mode

See CONTRIBUTING.md for branch conventions, PR process, and code style.

Deployment

Lockstep runs in two modes (12-factor config):

• Self-host: docker compose up on your infra — you register your own GitHub App
• Managed cloud: Multi-tenant SaaS with RLS isolation

See DEPLOY.md for step-by-step Railway deployment instructions.

Architecture

• 26-table schema with row-level security (RLS) for tenant isolation
• Append-only ledger — decisions are immutable, versioned with content-addressable storage
• Vendor-neutral adapter pattern — new AI agent integrations are a single adapter file
• Zod validation on every boundary, TypeScript strict mode throughout
• Zero source code stored — only decisions, contracts, and metadata flow through the system

Security

See SECURITY.md for our responsible disclosure policy.

License

MIT © Naman Jain