Lockstep

About Lockstep

Stops parallel agents from colliding on shared hotspot files like lockfiles and route registries.

Price: $19 one-time

Included free

• Hotspot auto-detection via the dependency graph (high fan-in files)
• Manual hotspot declaration
• Soft-lock warnings when another session is editing a hotspot
• Static list of currently locked files with owning session
• Auto-release on session end / timeout

Unlocked with a license

• Live, auto-refreshing locked-files panel
• Hard-lock enforcement via Claude Code PreToolUse hooks (self-configured — see below)

Getting a license

Open the Lockstep sidebar (activity bar icon) and click Get License. After purchase you'll receive a license key — paste it into the sidebar and click Activate License. Keys are machine-locked; use Move to another machine… in the sidebar before reinstalling on a new device.

How locking works

Hotspots are files with many dependents (auto-detected from the workspace's dependency graph) plus anything you declare manually. Every time a hotspot file is saved, Lockstep refreshes a lock entry for it in .lockstep/locks.json, owned by the current VS Code window (a random session id) and this machine. Before any save, Lockstep checks that file for a live lock owned by someone else and — if found — shows a warning naming the other session. This is a soft lock: it never blocks the save, it just tells you someone else is probably touching the same file. Use Lockstep: Show Active Locks to see what's currently held, and Lockstep: Release My Locks to clear your own entries early (e.g. before switching branches).

With a license, Show Active Locks opens a live, auto-refreshing panel instead of a static list, so a team lead can leave it open and watch lock activity in real time.

v2 (planned): hard-lock enforcement via Claude Code hooks

Soft locks only warn — they can't stop an agent from writing to a file. A future version adds real enforcement by wiring .lockstep/locks.json into a Claude Code PreToolUse hook that blocks file-editing tool calls against a file locked by a different session. This isn't implemented by the extension itself (installing hooks into another tool's config is out of scope for a VS Code extension) — but you can wire it up yourself today with a script like this, registered as a PreToolUse hook for Edit/Write in your Claude Code settings:

#!/usr/bin/env node
// .lockstep/hooks/pretooluse-guard.js — sketch only, not installed by this extension.
const fs = require('fs');
const path = require('path');

const input = JSON.parse(fs.readFileSync(0, 'utf8'));
const filePath = input?.tool_input?.file_path;
if (!filePath) process.exit(0);

const locksPath = path.join(process.cwd(), '.lockstep', 'locks.json');
let locks = {};
try { locks = JSON.parse(fs.readFileSync(locksPath, 'utf8')); } catch { /* no locks yet */ }

const entry = locks[path.resolve(filePath)];
const mySessionId = process.env.LOCKSTEP_SESSION_ID;
if (entry && entry.sessionId !== mySessionId && new Date(entry.expiresAt).getTime() > Date.now()) {
  console.error(`Blocked: ${filePath} is locked by another Lockstep session until ${entry.expiresAt}.`);
  process.exit(2); // non-zero exit blocks the tool call in Claude Code
}
process.exit(0);

Implementation notes

• The dependency graph is regex-based (see @batch2/dependency-graph), not a type-checker — hotspot detection is a heuristic, not a guarantee.
• .lockstep/locks.json and .lockstep/config.json are plain JSON meant to be gitignored (or committed, if your team wants shared manual hotspot declarations).