README
¶
stAirCase
AI agents propose. You approve. Only what you approved is committed - and you can prove it.
AI coding agents are fast, but it is hard to know exactly what they changed, who agreed to it, and whether what was committed is what was reviewed.
stAirCase sits between AI agents and your repository:
- the agents work in a separate copy of your repository, never in your checkout;
- every change they want to make is a proposal that waits for a decision - by you, or by a rule you wrote;
- at the end, stAirCase commits exactly the approved bytes on a new branch, and nothing else;
- every decision is recorded on a tamper-evident audit chain, and the commit carries a signed change certificate that anyone can verify, and rebuild: from the base commit and the approved proposals, anyone can reproduce the commit's exact tree.
It is one program with no dependencies except git (and ssh-keygen, if you sign
decisions or reviews with SSH keys). Your agent setup, plans and evidence live in a
workspace outside your repositories.
Put staircase in front of your agent
In any git repository, with nothing to set up:
staircase claude "add a /health endpoint that returns 200" # or: staircase codex "..."
Every change the agent wants to make comes to you first. At the end, exactly what you approved is on a new branch, with a certificate you can check:
staircase verify staircase/run-1
✅ Commit 33279b77f9ba: valid change certificate, CAL 3
requested by dev@example.com (the git email of the checkout: unauthenticated)
run #1 from 188a7dda520e, assisted by Claude Code
1 decision(s) by operator
Add --rebuild and it also replays the approved proposals and checks that the commit
holds exactly what they produce. A pull request can be required to carry such
certificates (and that rebuild) with the
stAirCase GitHub Action.
See it work in one minute
No API key and no network needed - the demo uses a stand-in model:
git clone https://github.com/b070nd/stAirCase.git
cd stAirCase
./demo/run-demo.sh
An agent proposes to create, edit and delete a file, and waits for you each time. At the end the demo proves that the new branch holds exactly those changes and that your checkout did not change. Two more modes show the safety checks at work:
./demo/run-demo.sh --tamper # a command changes an approved file → you decide, it is put back
./demo/run-demo.sh --drift # the agent works outside its task → the run is stopped
Install
brew install b070nd/staircase/staircase
Or go install github.com/b070nd/stAirCase/src/cmd/staircase@latest, or download a
signed archive for Linux, macOS or Windows (experimental). See Install,
including how to verify a download.
Then follow Getting started: your first real run in about 15 minutes.
What you get
| Approval bound to bytes | stAirCase computes itself what each approved change produces, and commits only that. Anything else fails the run. |
| Your checkout untouched | every run works in its own git worktree, on its own staircase/run-N branch. |
| Evidence you can hand over | a hash-chained audit log, Ed25519-signed exports, a signed certificate per commit, a SLSA verification summary, optional anchoring in the public Rekor log. |
| Reproducible, not just signed | staircase rebuild (or verify --rebuild) reproduces a commit's tree from its approved proposals; the specification has test vectors and an independent implementation. |
| Approve your way | in the terminal, in a browser page, from a script (local HTTP API), from a service (signed webhook), with rules, or with a reviewer model; sign your decisions with an SSH key. |
| Approve the task, on evidence | agree a task and its scope once, and let your checks and reviewer models decide each change inside it instead of a sample; you approve the whole change at the end. |
| Survives a crash | each approval is kept before the agent hears it; staircase resume carries on with an interrupted run (Claude Code, Gemini CLI and Codex pick up their own session); staircase recover commits exactly what it had approved. |
| For teams | rules, trusted keys and blueprints from one governance repository, pinned in every workspace; a CI check that requires certificates, from the protected branch. |
| Runs stay on task | give each story the paths it may change; anything else comes to you, and a run that keeps wandering is stopped. |
| Setup as code | keep agents, prompts, cases and limits as a blueprint in its own repository; runs are pinned to its exact content. |
| Any major model | Anthropic, OpenAI, Google, xAI, or any model through an OpenAI-compatible gateway - mixed in one team. Budget caps per project. |
| Shell off by default | agents can only ask to run commands when you allow it, and a person approves each one. |
| Claude Code and Codex, governed | staircase claude "task" or staircase codex "task": the agents you already use, with every change going through the same approvals (experimental); Gemini CLI and OpenCode are there too (staircase gemini, staircase opencode; both have run against a real login once or twice, OpenCode is still experimental), and any agent that edits your checkout (Cursor) is covered by staircase seal. |
Know the limits
stAirCase controls what reaches your repository, and confines what agents do on your machine:
| Where it runs | |
|---|---|
| Edits and reads | only through stAirCase's tools, only inside the run's own worktree |
| Shell commands and checks | an OS sandbox (macOS sandbox-exec, Linux bubblewrap or Landlock, Claude Code's own sandbox): no network, writes only in the worktree, no access to your credentials or stAirCase's keys; --sandbox required refuses to run without one |
| The agent program itself | as your user (Claude Code, Codex, or stAirCase's runtime); for stronger isolation, run stAirCase in a container or VM |
| Agents that edit your checkout (Cursor) | outside stAirCase until you seal their staged changes (CAL 2) |
| What the agent reads, and what the model provider receives | not confined: a run sends code to your model provider, and a sandboxed command can read files you can; pick a confidentiality profile |
Read the safety boundary before you use it on a project you care about. stAirCase is at 1.0: its six interfaces follow semantic versioning (compatibility); the agent adapters are not part of that promise and Gemini CLI and OpenCode are still experimental.
Documentation
Everything is in docs/ - start with Concepts (five minutes) and Getting started.
Security
How stAirCase protects your code, its known limits, and how to report a vulnerability privately: SECURITY.md.
Roadmap
Where stAirCase is going: every change an AI agent makes carries a signed, verifiable change certificate, and the repository can require it. Built so far: zero-setup sessions for Claude Code, Codex and Gemini CLI (OpenCode experimental), the certificate and its specification, rebuild from a ledger, signed decisions, approval on evidence, recovery, team governance and the CI check. Next is what only users can show: real pilots on sensitive repositories, and more real runs of every agent. The full plan, what has been verified against real agents and what has not, and its reasoning are in ROADMAP.md and the compatibility table.
Contributing
Contributions are welcome. See CONTRIBUTING.md; make check is
the test every change must pass.
License
MIT © 2026 Botond Biro
Directories
¶
| Path | Synopsis |
|---|---|
|
demo
|
|
|
demotool
command
Command demotool is the offline demo's stand-in model and its small helpers, so the demo needs neither an API key nor Python.
|
Command demotool is the offline demo's stand-in model and its small helpers, so the demo needs neither an API key nor Python. |
|
src
|
|
|
cmd/staircase
command
|
|
|
internal/agent
Package agent is stAirCase's own agent runtime: the tools a model may call, the model clients, and the topology graph that drives them in-process.
|
Package agent is stAirCase's own agent runtime: the tools a model may call, the model clients, and the topology graph that drives them in-process. |
|
internal/approvalhttp
Package approvalhttp exposes a local HTTP API for out-of-process HITL approval.
|
Package approvalhttp exposes a local HTTP API for out-of-process HITL approval. |
|
internal/audit
Package audit provides append-only checkpoint writing outside the SQLite database so that tamper evidence survives DB-level attacks (CHECK 9.2.2).
|
Package audit provides append-only checkpoint writing outside the SQLite database so that tamper evidence survives DB-level attacks (CHECK 9.2.2). |
|
internal/barrier
Package barrier lets a test hold a process at a named point, so a kill drill can wait until the process has really reached a boundary and only then hard-kill it.
|
Package barrier lets a test hold a process at a named point, so a kill drill can wait until the process has really reached a boundary and only then hard-kill it. |
|
internal/blueprint
Package blueprint reads a blueprint - a project's automation (agents, prompts, routing, cases, stories and their scope) kept as files in its own repository - into an immutable snapshot identified by its content hash.
|
Package blueprint reads a blueprint - a project's automation (agents, prompts, routing, cases, stories and their scope) kept as files in its own repository - into an immutable snapshot identified by its content hash. |
|
internal/certificate
Package certificate is the change certificate (docs/adr/0002): a small in-toto statement about one commit, signed in a DSSE envelope, that says how the change was made and decided.
|
Package certificate is the change certificate (docs/adr/0002): a small in-toto statement about one commit, signed in a DSSE envelope, that says how the change was made and decided. |
|
internal/gate
Package gate implements the stAirCase pre-run quality gate system.
|
Package gate implements the stAirCase pre-run quality gate system. |
|
internal/governance
Package governance installs a team's rules and trusted keys from a governance repository into a workspace, pinned to an exact commit (ROADMAP phase 4: git as the control plane).
|
Package governance installs a team's rules and trusted keys from a governance repository into a workspace, pinned to an exact commit (ROADMAP phase 4: git as the control plane). |
|
internal/llm
Package llm talks to chat models that can call tools, over plain HTTPS: one OpenAI-compatible client (the LLM gateway, OpenAI, xAI, Gemini) and one Anthropic client, plus recording and offline replay of their exchanges.
|
Package llm talks to chat models that can call tools, over plain HTTPS: one OpenAI-compatible client (the LLM gateway, OpenAI, xAI, Gemini) and one Anthropic client, plus recording and offline replay of their exchanges. |
|
internal/obs
Package obs provides structured logging with automatic redaction of sensitive fields (CHECK 10.1.2).
|
Package obs provides structured logging with automatic redaction of sensitive fields (CHECK 10.1.2). |
|
internal/orchestrator
Package orchestrator implements the stAirCase run lifecycle state machine.
|
Package orchestrator implements the stAirCase run lifecycle state machine. |
|
internal/orchestrator/runtest
Package runtest runs an in-process agent against a throwaway workspace and repository, for tests of the orchestrator and of agents.
|
Package runtest runs an in-process agent against a throwaway workspace and repository, for tests of the orchestrator and of agents. |
|
internal/persistence
Package persistence - RotationLock provides a filesystem advisory lock that prevents concurrent key-rotation operations (CHECK 4.3.3).
|
Package persistence - RotationLock provides a filesystem advisory lock that prevents concurrent key-rotation operations (CHECK 4.3.3). |
|
internal/plan
Package plan is what compile produces and run executes: a case's topology, prompts and context as canonical JSON, checked before every run.
|
Package plan is what compile produces and run executes: a case's topology, prompts and context as canonical JSON, checked before every run. |
|
internal/policy
Package policy evaluates auto-approval rules against HITL yield requests.
|
Package policy evaluates auto-approval rules against HITL yield requests. |
|
internal/policysim
Package policysim runs expected-outcome scenarios against a policy file through the same admission code a real run uses (the deciders: policy rules, guards, drift supervision, limits, task and evidence approval), so that what a policy must do and must not do can be asserted in CI.
|
Package policysim runs expected-outcome scenarios against a policy file through the same admission code a real run uses (the deciders: policy rules, guards, drift supervision, limits, task and evidence approval), so that what a policy must do and must not do can be asserted in CI. |
|
internal/signal
Package signal asks an evaluation model, such as TypeSafe AI's Jev, typed questions about a proposed change.
|
Package signal asks an evaluation model, such as TypeSafe AI's Jev, typed questions about a proposed change. |
|
internal/sshsig
Package sshsig signs and checks payloads with SSH keys, through ssh-keygen (the format git uses for SSH-signed commits).
|
Package sshsig signs and checks payloads with SSH keys, through ssh-keygen (the format git uses for SSH-signed commits). |
|
internal/testdeps
Package testdeps is for tests that need a program the machine may not have.
|
Package testdeps is for tests that need a program the machine may not have. |
|
internal/vsa
Package vsa builds SLSA Verification Summary Attestations (VSA v1, SLSA v1.2) for commits that `staircase verify` accepted: what was verified, by whom, under which policy, from which attestations.
|
Package vsa builds SLSA Verification Summary Attestations (VSA v1, SLSA v1.2) for commits that `staircase verify` accepted: what was verified, by whom, under which policy, from which attestations. |
|
internal/webhookauth
Package webhookauth provides HMAC-SHA256 request/response authentication for the webhook approval channel.
|
Package webhookauth provides HMAC-SHA256 request/response authentication for the webhook approval channel. |
|
tools/jeveval
command
Command jeveval measures an evaluation model (such as typesafe-ai/jev) on labelled code changes with the questions stAirCase's signal asks (signal.ReviewQuestions): accuracy, calibration (Brier score), missed risky changes, latency and cost.
|
Command jeveval measures an evaluation model (such as typesafe-ai/jev) on labelled code changes with the questions stAirCase's signal asks (signal.ReviewQuestions): accuracy, calibration (Brier score), missed risky changes, latency and cost. |
Click to show internal directories.
Click to hide internal directories.