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.
The Action collects no data: it reads the repository and the pull request, and downloads a release it attests.
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
Command staircase is the command line of stAirCase: it stands between an AI agent and your repository, asks for a decision on every change, commits only what was approved, and writes the audit chain and the change certificate that prove it.
|
Command staircase is the command line of stAirCase: it stands between an AI agent and your repository, asks for a decision on every change, commits only what was approved, and writes the audit chain and the change certificate that prove it. |
|
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 is a local HTTP API for approving out of process.
|
Package approvalhttp is a local HTTP API for approving out of process. |
|
internal/audit
Package audit provides append-only checkpoint writing outside the SQLite database so that tamper evidence survives DB-level attacks.
|
Package audit provides append-only checkpoint writing outside the SQLite database so that tamper evidence survives DB-level attacks. |
|
internal/barrier
Package barrier lets a test hold a process at a named point, so a kill drill can wait until the process has reached a boundary and then kill it.
|
Package barrier lets a test hold a process at a named point, so a kill drill can wait until the process has reached a boundary and then 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/chain
Package chain is the audit chain's rule: how an entry is hashed, how a run's entries are verified, and how big one entry may be.
|
Package chain is the audit chain's rule: how an entry is hashed, how a run's entries are verified, and how big one entry may be. |
|
internal/changeset
Package changeset links runs of several repositories under one id.
|
Package changeset links runs of several repositories under one id. |
|
internal/crypto
Package crypto holds the workspace keys: AES-256-GCM encryption of the stored secrets, key rotation with a crash-safe journal, and the Ed25519 key that signs audit checkpoints and change certificates.
|
Package crypto holds the workspace keys: AES-256-GCM encryption of the stored secrets, key rotation with a crash-safe journal, and the Ed25519 key that signs audit checkpoints and change certificates. |
|
internal/diag
Package diag holds the logs kept for a person to read when something went wrong: the hosted-session log (host/<session>.log) and the run's debug log.
|
Package diag holds the logs kept for a person to read when something went wrong: the hosted-session log (host/<session>.log) and the run's debug log. |
|
internal/domain
Package domain holds the plain types the other packages share: vendors, projects, cases, stories, topologies, runs and the records of what happened in a run.
|
Package domain holds the plain types the other packages share: vendors, projects, cases, stories, topologies, runs and the records of what happened in a run. |
|
internal/engine
Package engine holds the logic that works on projects and files without touching a run: the dependency order of projects, path globs, the repository map and the ignore rules.
|
Package engine holds the logic that works on projects and files without touching a run: the dependency order of projects, path globs, the repository map and the ignore rules. |
|
internal/gate
Package gate is the pre-run quality gate.
|
Package gate is the pre-run quality gate. |
|
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/history
Package history is the one replay of a run's audit chain (ADR 0010): what a verified chain says a run bound, proposed, decided, parked, adopted, offered and delivered.
|
Package history is the one replay of a run's audit chain (ADR 0010): what a verified chain says a run bound, proposed, decided, parked, adopted, offered and delivered. |
|
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 that redacts sensitive fields.
|
Package obs provides structured logging that redacts sensitive fields. |
|
internal/orchestrator
Package orchestrator implements the stAirCase run lifecycle.
|
Package orchestrator implements the stAirCase run lifecycle. |
|
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 is the workspace database (SQLite): vendors, projects, cases, stories, topologies, runs, secrets, and the hash-chained event log of each run.
|
Package persistence is the workspace database (SQLite): vendors, projects, cases, stories, topologies, runs, secrets, and the hash-chained event log of each run. |
|
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: rules, guards, drift supervision, limits, task and evidence approval), so CI can assert what a policy must and must not do.
|
Package policysim runs expected-outcome scenarios against a policy file through the same admission code a real run uses (the deciders: rules, guards, drift supervision, limits, task and evidence approval), so CI can assert what a policy must and must not do. |
|
internal/profile
Package profile is what is true of a project for every run of it (a spec of the first real project): the paths a person must always decide, the paths a change may touch, the checks, the sandbox.
|
Package profile is what is true of a project for every run of it (a spec of the first real project): the paths a person must always decide, the paths a change may touch, the checks, the sandbox. |
|
internal/relversion
Package relversion keeps every place that names the current release in step with the CHANGELOG, which is the one source of the version.
|
Package relversion keeps every place that names the current release in step with the CHANGELOG, which is the one source of the version. |
|
internal/sandbox
Package sandbox runs commands and checks confined: in the macOS sandbox, Linux bubblewrap or Landlock, or a docker container.
|
Package sandbox runs commands and checks confined: in the macOS sandbox, Linux bubblewrap or Landlock, or a docker container. |
|
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 authenticates the webhook approval channel with HMAC-SHA256, in both directions.
|
Package webhookauth authenticates the webhook approval channel with HMAC-SHA256, in both directions. |
|
internal/wslock
Package wslock provides the advisory file locks (flock) shared by the runner and `secret rotate`.
|
Package wslock provides the advisory file locks (flock) shared by the runner and `secret rotate`. |
|
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. |
|
tools/setversion
command
Command setversion makes every place that names the current release say the version the CHANGELOG's newest release heading gives: the pinned Action example, the fixture's default, the site's links and its setup guide (see internal/relversion).
|
Command setversion makes every place that names the current release say the version the CHANGELOG's newest release heading gives: the pinned Action example, the fixture's default, the site's links and its setup guide (see internal/relversion). |
Click to show internal directories.
Click to hide internal directories.