convez.ai
MCP Server
lockstep-team-agent

lockstep

lockstep-team-agent/lockstep

Ver no GitHub
BomPluginScore · de 0 a 100

Keep your team's AI coding agents coordinated — without sharing source code.

Instalação

$npx convez-ai lockstep-team-agent/lockstep

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
12
Forks
0
Acompanhando
0
Saúde
75%
Último commit
há 1 semana
Versão
—
Issues abertas
12
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.


Why Lockstep?

When multiple developers use AI coding agents (Claude Code, Codex, Gemini CLI) on the same codebase, things break:

  • Agent A renames an API endpoint. Agent B keeps calling the old one.
  • Agent A decides on a new 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 that keeps every agent aware of every decision, contract change, and dependency — in real-time — without source code ever leaving the developer's machine.

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 happensWho gets notifiedHow
Contract surface changed (API route, proto, exported type)Every repo that registered a dependency on that surfaceInbox fan-out, delivered on next session replay
Decision proposed on a shared scopeAll project members see it in their decision listdecisions MCP tool / dashboard
Question asked (optionally scoped to a surface)All project membersInbox / dashboard
Task delegated to a specific teammateThe delegateeInbox / dashboard
PR touches a contract surface with no binding decisionThe PR authorGitHub Action check fails with violation list

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

Flows through LockstepNever leaves the machine
Decision text ("rename endpoint X to Y")Source code
Surface identifiers (POST /auth/session)File contents
Change summaries ("changed 3 files: routes/auth.ts, ...")Git diffs
Dependency edges (repo B consumes surface X)Credentials or secrets
Ownership rules (parsed from CODEOWNERS)Environment variables

Features

FeatureDescription
Cross-vendorWorks with Claude Code, Codex, Gemini CLI — any agent that supports MCP
Decision ledgerAppend-only, CAS-versioned decisions with propose/acknowledge workflow
Dependency graphAutomatic routing — changes to a surface notify every consumer
Ownership graphCODEOWNERS-powered ownership, auto-ingested on connect
Two-tier captureTier-1: real-time change capture. Tier-2: PR-level reconciliation gate
Questions & tasksCross-agent delegation — ask questions, assign tasks, get answers
MCP-native12-tool MCP server runs per-session on the developer's machine
DashboardNext.js UI for decisions, contracts, dependencies, activity, and tasks
Self-hostabledocker compose up on your own infra, or use the managed cloud
Secure by defaultRLS isolation, encrypted tokens, append-only audit trail, no secrets in code

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/naman7474/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:

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

CommandWhat it does
lockstep login [--api <url>]Authenticate via GitHub device flow (or --dev for local)
lockstep initWire MCP server + hooks into the current repo
lockstep connect [--project <name>]Link this repo to a shared project
lockstep invite <github-handle>Invite a teammate to your project
lockstep captureManually trigger change capture (also runs automatically)
lockstep status / lockstep doctorCheck auth + config health

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

  • 25-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

Ver o original no GitHub

Bom para

Relacionados