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.
It is one program with no dependencies except git. 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 8a4ae8705334: valid change certificate, CAL 3
run #1 from 1ec6a66040cc, assisted by Claude Code
A pull request can be required to carry such certificates 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 file changes after you approved it → nothing is committed
./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, optional anchoring in the public Rekor log. |
| Approve your way | in the terminal, from a script (local HTTP API), from a service (signed webhook), with rules, or with a reviewer model. |
| 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). |
Know the limits
stAirCase controls what reaches your repository. It is not a sandbox: agents and approved shell commands run as your user. Read the safety boundary before you use it on a project you care about. stAirCase is pre-1.0.
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. Next up: staircase claude "task" with no setup, more agents
(Codex, Gemini CLI, OpenCode, Cursor), and a CI check that requires certificates. The
full plan and its reasoning are in ROADMAP.md.
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/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/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/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. |