StepCheck Dev

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

Deterministic Anti-Context-Rot State Engine · BYOK Token-Firewall Proxy · Streamable HTTP MCP Server · Split-Pane Visual Workspace. 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)

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.