StepCheck Dev

Live: 131-session audit receipt · 50-turn interactive replay

Cloudflare + pre-commit for coding agents. A deterministic layer between your agent and the model that stops two things that go wrong in every long session: the agent quietly drops a decorator or a guard clause around turn 25 because the file it is editing has been sitting in context as a stale 500-line read, and you pay for all of those reads again at full price every time you pause longer than the provider's cache window. Teams get the same problem multiplied: more AI pull requests than a senior engineer can review for cross-file omissions, on a frontier-model bill driven by trivial edits over uncompacted history.

Three steps, none of them in your prompt:

1. stepcheck audit --card — sixty seconds, no server: reads your local Claude Code transcripts and shows the dollars lost to cache-cliff re-reads, the share of Read tokens spent on bodies the agent never used, and the exact turns where a decorator or guard went missing. Nothing but totals leaves the machine.
2. stepcheck hooks && stepcheck up — invisible daily protection: a PreToolUse hook turns large file reads into AST skeletons, every edit runs Gates A/B/C (dropped decorator or guard: blocked; changed signature: callers flagged DIRTY_OMISSION_RISK), and the Stop hook refuses to end the turn until those callers are re-verified.
3. Door 1 proxy + PR bot — for teams: accordion compaction of old tool results, a cache-cliff shield, gate-backed routing of focused edits to a cheaper model, and stepcheck ci --report (or the GitHub Action) posting a blast-radius and in-toto provenance checklist on every PR.

Licensing is opt-in (STEPCHECK_REQUIRE_KEY=1); with it unset everything in this repository runs locally with no key. Ubiquitous language and the two public testing seams live in GLOSSARY.md.

Layout

Run (turnkey)

pipx install git+https://github.com/lalithasutam/stepcheck-dev   # the `stepcheck` CLI, no clone needed
pip install -e .            # …or from a clone (editable)
(cd frontend && npm install && npm run build)   # once: compiled Studio served at /studio
stepcheck up                # one port (:8420): Studio UI + Door 1 proxy + REST + MCP + WS
stepcheck benchmark         # 50-turn coding-rot benchmark
stepcheck review            # architecture-review.html
stepcheck preview           # stepcheck-studio-preview.html (self-contained replay)
stepcheck audit             # your own cache-cliff waste + Read-tool bloat, no server needed → stepcheck-audit.html
stepcheck ci backend        # headless gate: parse + attestations + Gates A/B/C for every module (CI/PR)
stepcheck llms              # docs/llms.txt + docs/llms-full.txt from README, GLOSSARY, LAUNCH and benchmarks/results.json
stepcheck hooks             # .claude/hooks + settings wiring: Read over threshold -> skeleton, Edit of a locked module -> deny, Stop while dirty -> block
stepcheck ci . --report     # the headless gate plus a Markdown PR checklist: touched modules, re-verified callers, conserved symbols, in-toto digests
stepcheck audit --card      # stepcheck-audit-card.svg + a copy-paste badge line; file names and session ids never appear

Door 1: accordion compaction and tier routing

Every proxied turn through /v1/messages or /v1/chat/completions passes a three-band compactor: the last four messages stay verbatim, older Python source blocks over 150 tokens are replaced in place by their AST skeleton, dead-end turns are pruned, and after a cache-cliff gap the oldest band folds into one OKF session-state frame. The dry-run response carries a stepcheck.compaction block with per-band token counts. Routing is opt-in: x-stepcheck-tier: auto (or STEPCHECK_TIER_POLICY=auto) sends a focused single-symbol turn to STEPCHECK_FAST_MODEL first and re-sends it to the requested frontier model only when a gate rejects the draft; without the header nothing changes.

TypeScript and JavaScript projects

.ts, .tsx, .js and .jsx files are indexed next to .py (declaration files, node_modules, dist, build and out are skipped). Relative imports become graph edges, top-level declarations render as brace-elided skeletons, patch ops splice exact line spans, and Gates A/B plus the DSSE attestation apply unchanged; Gate C has no invariants for TypeScript yet, and class members are not individually addressable.

Checkouts and patch ops address methods too: focus=["StateKernel.commit"] emits that one method verbatim inside a class skeleton, and replace_symbol / delete_symbol on "Class.method" splice only its lines. A name always addresses its whole definition group (@overload stubs + implementation, a @property with its setter). StateKernel.provenance(session_id, node_id) exports the latest attestation as an in-toto Statement v1 inside a DSSE envelope (application/vnd.in-toto+json), the shape cosign and Witness consume; the signature is the kernel's deterministic SHA-256 scheme, not a key.

Claude Code slash commands (work out of the box after cloning)

.claude/commands/ ships four project commands. They need the gateway running (stepcheck up) and the stepcheck MCP server connected (claude mcp add --transport http stepcheck http://127.0.0.1:8420/mcp/); CLAUDE.md supplies the rules they enforce.

Run (development)

# backend + tests
cd backend && pip install -r requirements.txt && python -m pytest -q
python server.py                         # gateway on :8420 (PORT overrides)

# frontend
cd frontend && npm install && npm run dev   # Studio on :5173
# open http://localhost:5173/?session=<session_id from POST /v1/step/init>

# benchmark + report
python3 benchmarks/coding_rot_benchmark.py
python3 benchmarks/generate_review.py

# extension (compile check; load the folder via VS Code "Run Extension")
cd extension && npm install && npm run compile

Door 1 in one call

SID=$(curl -s localhost:8420/v1/step/init -d '{"project_root":"/path/to/project"}' \
      -H 'content-type: application/json' | jq -r .session_id)
curl -s localhost:8420/v1/messages \
  -H "x-stepcheck-session: $SID" -H "x-stepcheck-node: billing" \
  -H 'content-type: application/json' \
  -d '{"model":"claude-sonnet-4-5","max_tokens":512,"messages":[...]}'
# add x-api-key + x-stepcheck-upstream (or STEPCHECK_UPSTREAM_BASE) to forward BYOK;
# without them you get the deterministic dry-run with stepcheck.sent_messages.

Testing rules (skill precedence)

tdd + codebase-design override python-testing-patterns on mocking: never mock internal modules, AST parsers, YAML validators, or hash functions. Tests hit Seam 1 / Seam 2 only, against concrete non-tautological fixtures (hand-written projects, hand-calculated telemetry numbers).

Security model

Gate C exec-loads the agent's staged module in an isolated namespace under a step/time guard so callable invariants can run against it. That is an isolated namespace, not a security sandbox: run the gateway in a container when the agent is untrusted. Python projects only for now.

License

Apache-2.0 — see LICENSE and NOTICE. Everything in this repository is the open core (kernel, gates, MCP server, BYOK proxy, Studio, stepcheck ci and stepcheck audit). If StepCheck gets real use, the paid product will be a team layer (shared attestation ledger, org-wide CI gate); the core stays open.