@lockstep-ai/lockstep
Advanced tools
Cryptographic verification for AI coding agents. Stop trusting your AI agent — verify it.
CI/CD with cryptographic provenance for AI-generated code.
Stop trusting your AI agent. Verify it.
Define steps. Hash expectations. Let the agent work. If it followed the plan, the hashes match. If it didn't, you'll know exactly where it broke.
When you give an AI coding agent a complex task, it vibes through it. It decides what steps to take. It sometimes skips things. It sometimes says "Done!" when it isn't. There's no accountability, no audit trail, and no way to prove what actually happened.
Lockstep generates verifiable execution receipts -- cryptographic proof that an AI agent complied with a specified process and passed every validation.
Important: Lockstep proves compliance, not correctness. It proves the agent followed your plan and met your criteria. It doesn't claim the code is optimal or future-proof. That precision is what makes it trustworthy.
Install Lockstep globally:
npm install -g @lockstep-ai/lockstep
Configure authentication for the AI Judge:
lockstep setup
🔧 Lockstep Setup
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
How do you want to authenticate the AI Judge?
[1] Use my Claude subscription (zero setup)
[2] Use an API key (maximum control)
Select [1/2]: 1
Checking for Claude CLI...
Claude CLI found: 1.0.16
✅ Configuration saved — ~/.locksteprc
Your Claude subscription will be used for AI Judge evaluations.
Run lockstep run to get started.
Create a spec from a template:
lockstep init nextjs-saas
✅ Created .lockstep.yml from template "nextjs-saas"
Next steps:
1. Edit .lockstep.yml to define your build steps
2. Run lockstep validate to check your spec
3. Run lockstep run to execute
Or write your own .lockstep.yml (see The Spec File below), then run it:
lockstep run
🔒 Lockstep v0.1.0
📋 Loaded spec: .lockstep.yml (3 steps)
🤖 Agent: claude-code
🧠 Judge: claude-sonnet-4-6 (subscription mode)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 1/3 ▸ Initialize project
🤖 Running Claude Code...
⏱ Completed in 42s
🔍 Validating...
✅ package.json exists
✅ app/layout.tsx exists
✅ package.json contains "next"
🔒 Hash: a1b2c3d4...e5f6
✅ Step Initialize project verified
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 2/3 ▸ Build landing page
🤖 Running Claude Code...
⏱ Completed in 1m 15s
🔍 Validating...
✅ app/page.tsx exists
✅ Pattern matches in app/page.tsx
✅ Build succeeds
🧠 AI Judge: Median 7.8/10 [7.5, 8.0, 7.8] (threshold: 6.0)
🔒 Hash: f7a8b9c0...d1e2
✅ Step Build landing page verified
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 3/3 ▸ Add tests
🤖 Running Claude Code...
⏱ Completed in 38s
🔍 Validating...
✅ jest.config.ts exists
✅ All tests pass (exit code 0)
✅ Build succeeds
🔒 Hash: 3c4d5e6f...7a8b
✅ Step Add tests verified
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ ALL STEPS VERIFIED
🔒 Chain hash: 3c4d5e6f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d
📄 Receipt: .lockstep/receipt.json
📝 Report: .lockstep/report.md
Total time: 2m 35s | Steps: 3/3 | Total attempts: 3
Each step's output is hashed. Each hash chains to the next. The final receipt is a self-contained proof of what happened.
┌──────────────────────────────────────────┐
│ .lockstep.yml │
│ Your spec: steps, prompts, validators │
└─────────────────┬────────────────────────┘
│
▼
┌────────────────────────────────────────────────────┐
│ For each step: │
│ │
│ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
│ │ Prompt │───▶│ Agent │───▶│ Validate │ │
│ │ (hash) │ │ executes │ │ results │ │
│ └──────────┘ └──────────┘ └─────┬──────┘ │
│ │ │
│ ┌──────────────┴──┐ │
│ │ All passed? │ │
│ └──┬───────────┬───┘ │
│ yes│ │no │
│ ▼ ▼ │
│ ┌────────────┐ ┌────────┐ │
│ │ Hash step │ │ Retry │ │
│ │ Chain link │ │ (up to │ │
│ └─────┬──────┘ │ max_n) │ │
│ │ └────────┘ │
└───────────────────────────┼───────────────────────┘
│
▼
┌──────────────────────────────────────┐
│ Execution Receipt │
│ Chain hash + per-step proofs │
│ Independently verifiable │
└──────────────────────────────────────┘
If any step fails validation, Lockstep retries with the failure context injected into the prompt. If it still fails after max_retries, execution stops. The receipt records every attempt.
A .lockstep.yml spec defines configuration, context, and steps with validators:
version: "1"
config:
agent: "claude-code"
max_retries: 3
step_timeout: 300
context: |
Building a REST API with Express.js and TypeScript.
Use Zod for validation. Return consistent JSON responses.
steps:
- name: "Initialize project"
prompt: |
Create an Express.js project with TypeScript.
Set up tsconfig.json, install dependencies, create src/index.ts.
validate:
- type: file_exists
target: "package.json"
- type: file_exists
target: "src/index.ts"
- type: file_contains
path: "package.json"
pattern: "express"
- name: "Build user endpoints"
prompt: |
Create CRUD endpoints for users at /api/users.
Include input validation with Zod schemas.
validate:
- type: file_exists
target: "src/routes/users.ts"
- type: command_passes
command: "npx tsc --noEmit"
- type: ai_judge
criteria: |
Evaluate the user endpoints. Score 1-10:
1. Are all CRUD operations implemented?
2. Is input validation present with Zod?
3. Are error responses consistent?
Return JSON: {"scores": [<n>,<n>,<n>], "reasoning": "..."}
threshold: 6.0
evaluation_method: "file_content"
evaluation_targets:
- "src/routes/users.ts"
- name: "Add tests"
prompt: |
Write tests for the user endpoints using Jest.
Cover happy paths and error cases.
validate:
- type: file_exists
target: "src/__tests__/users.test.ts"
- type: test_passes
command: "npm test"
timeout: 60
- type: command_passes
command: "npx tsc --noEmit"
Each step must have at least one structural or functional validator. The ai_judge validator cannot be the sole validator on any step -- it must be layered on top of concrete checks.
The AI Judge is how Lockstep handles subjective quality -- things like "is this landing page well-structured?" or "does this code follow best practices?" that a file existence check can't answer.
Here's how it works:
ai_judge validator runs three independent evaluations. The median score is used, not the mean. This eliminates outlier hallucinations.temperature: 0 for maximum determinism.threshold: 6.0). The median must meet or exceed it.max_variance to reject results where judges disagree too much. If the spread across runs exceeds this, the validator fails regardless of score.ai_judge cannot be the only validator on a step. You must have at least one structural or functional check (like file_exists or command_passes) alongside it.Two authentication modes:
| Mode | Setup | How it works |
|---|---|---|
| Subscription | lockstep setup (select option 1) | Runs claude -p subprocess using your Claude subscription. Zero API keys needed. |
| API key | lockstep setup (select option 2) | Calls the Anthropic API directly with your ANTHROPIC_API_KEY. Temperature 0, maximum control. |
Anyone with the receipt file can independently verify the hash chain:
lockstep verify .lockstep/receipt.json
🔒 Lockstep Receipt Verification
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📄 Receipt: .lockstep/receipt.json
📋 Spec: .lockstep.yml
Spec hash: ✅ matches
Chain integrity: ✅ all 3 step hashes valid
Step 1/3: ✅ hash a1b2c3d4...e5f6 verified
Step 2/3: ✅ hash f7a8b9c0...d1e2 verified
Step 3/3: ✅ hash 3c4d5e6f...7a8b verified
Chain hash: ✅ 3c4d5e6f...7a8b
Completeness: ✅ 3/3 steps present
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Status: ✅ VALID — receipt is untampered
Verification recomputes every step hash and checks the chain links. If anyone modifies the receipt, the hashes break.
| Type | Required Fields | Description |
|---|---|---|
file_exists | target | Asserts a file exists at the given path |
file_not_exists | target | Asserts a file does NOT exist at the given path |
file_contains | path, pattern | Asserts file contents match a string or regex (is_regex: true) |
file_not_contains | path, pattern | Asserts file contents do NOT match a string or regex |
command_passes | command | Asserts a shell command exits with code 0 |
command_output | command, pattern | Asserts command stdout matches a string or regex |
api_responds | url, status | Asserts an HTTP endpoint returns the expected status code |
json_valid | path | Asserts a file contains valid JSON (optional schema for structure) |
type_check | -- | Runs TypeScript type checking (default: npx tsc --noEmit) |
lint_passes | -- | Runs the linter (default: npx eslint .) |
test_passes | command | Runs a test command and asserts exit code 0 |
ai_judge | criteria, threshold | AI evaluation with median-of-3 scoring (see The AI Judge) |
All validators accept an optional label field (display only, not hashed) and optional: true (failure won't block the step).
Initialize a spec from a built-in template:
lockstep init <template>
| Template | Description |
|---|---|
blank | Empty starter template with a single example step |
nextjs-saas | Full-stack Next.js SaaS with auth, database, and dashboard |
rest-api | Express.js REST API with TypeScript, CRUD, and tests |
solana-program | Solana on-chain program using the Anchor framework |
lockstep templates # list all available templates
| Command | Description |
|---|---|
lockstep run [spec-file] | Execute a spec and generate a verified receipt |
lockstep validate [spec-file] | Validate a spec file without running it |
lockstep init [template] | Create a new .lockstep.yml from a template |
lockstep verify <receipt-file> | Verify the integrity of an execution receipt |
lockstep templates | List available spec templates |
lockstep setup | Configure authentication for the AI Judge |
lockstep run options:
| Flag | Description |
|---|---|
--dry-run | Validate spec and show plan without executing |
--step <n> | Run only step N (1-indexed) |
--from <n> | Start execution from step N |
--verbose | Show detailed output |
--no-color | Disable colored output |
--output <path> | Custom output directory for receipt files |
| Agent | Status |
|---|---|
| Claude Code | Supported |
| Cursor | Coming soon |
| GitHub Copilot | Coming soon |
For developers: Stop manually checking if the agent cut corners. Define your expectations once, run the agent, and get a cryptographic receipt proving every validation passed.
For teams: A senior engineer defines the spec. A junior runs the agent. The receipt proves compliance with the senior's criteria -- no trust required, no review bottleneck.
For enterprises: SOC2, ISO 27001, regulated fintech -- cryptographic receipts proving exact process compliance. Every step hashed, every validation recorded, every receipt independently verifiable.
Contributions are welcome. Please open an issue first to discuss what you'd like to change.
git checkout -b feature/my-feature)npm run lint && npm test && npm run buildMIT -- see LICENSE for details.
FAQs
Cryptographic verification for AI coding agents. Stop trusting your AI agent — verify it.
The npm package @lockstep-ai/lockstep receives a total of 0 weekly downloads. As such, @lockstep-ai/lockstep popularity was classified as not popular.
We found that @lockstep-ai/lockstep demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
Two compromised GitHub Actions were re-enabled with malicious tags intact, exposing thousands of downstream repositories to Mini Shai-Hulud.
Research
/Security News
A malicious Firefox extension fetches its payload after installation to evade detection, steal Google session cookies, and automate account takeover.
Research
/Security News
The compromise affects MemTensor's MemOS, an open source memory framework for large language models (LLMs) and AI agents. Both npm package @memtensor/memos-cloud-openclaw-plugin and the PyPI package MemoryOS are compromised. They drop cross-platform Go binaries that exfiltrate developer secrets.