A real engineering workflow, run automatically.
Every change — human or agent — moves through the same steps: check against the graph, approve what changes the architecture, land what conforms. Deterministic, local, no LLM in the loop. Autonomy without the chaos.
$ git commit -m "billing: extend contract — charge(order, currency)" [seshat] check --staged R4 spec-change-approval .seshat/blocks/billing.yaml — semantic spec delta 9f2c4a requires approval ✗ 1 violation — change held (exit 1) $ seshat approve --staged recorded · deltaHash 9f2c4a · single-use $ git commit -m "billing: extend contract — charge(order, currency)" [seshat] check --staged ✓ pass (exit 0) · approval consumed
Boundaries holdFrozen parts of the system stay exactly as declared — by human or agent — until the architecture decision is revisited.
Tests keep their meaningA test that guards a contract method or invariant cannot silently disappear.
Architecture changes are decisionsSemantic spec deltas require an explicit seshat approve --staged — hash-bound to the exact staged tree, local to the clone, spent on first use.
Exit codes are a contract0 pass · 1 violations · 2 spec invalid · 3 internal — frozen and CI-safe.
Every block tells you where it stands.
Healthy
The contract is upheld. Code edits that stay inside it flow through the gate untouched.
5 conforming · last change 2h agoContract violated
A change crossed the block's contract. Seshat names the invariant and points at the code.
1 drift · Billing.charge() · 4m agoUntouchable
Marked off-limits. Any edit — human or agent — is held until the spec change is approved.
no activity · frozen 34dHard failure
A workflow rule fired: frozen touch, deleted guarding test, unapproved delta. The change is named, held, and never lands as-is.
check --staged → exit 1A spec your repo carries with it.
The graph lives as YAML in .seshat/ — one file per entity, stable UUIDs, reviewed like code. Git is the source of truth; Seshat is the enforcement.
Every element has a purpose
Blocks own files, contracts, invariants, guarding tests — and a rationale for why they exist. Connectors are first-class: they own the contract of the interaction. Services form the deploy topology above both. No orphan parts, no mystery glue.
.seshat/blocks/billing.yamlDeterministic checks
Seven rules, no heuristics in the enforcing path. Reads staged blobs straight from the git index — what gets checked is exactly what would land.
seshat check --staged · exit 0/1/2/3Approve flow
Semantic spec deltas are hashed. One approval, one consumption, by the first passing check. Formatting-only edits need nothing. Approvals live in the clone, never in the commit.
seshat approve --staged · deltaHash 9f2c4aNavigate the whole system
One command serves the system as a map — canvas, inspectors, findings, checks. Click into any block and see its purpose, contract and state. Watch it all change live while agents build.
seshat up --open · 127.0.0.1 onlyBuilt for autonomy
Agents build at machine speed inside declared structure. The daemon watches the worktree live, findings surface in the graph, and the workflow keeps every change on course — no babysitting.
live worktree watch · commit-time checksSigned, staged updates
Releases are ed25519-signed and verified before anything is trusted. Rollouts ramp by deterministic percentage buckets. Telemetry is opt-in, anonymous, aggregate-only.
seshat update · signature verified before applyThree commands to governed.
Scaffold the spec
Run once inside any git repo. Creates .seshat/ with guardrails and a commented example — nothing is enforced yet.
$ seshat init seshat init: initialized .seshat/ in ~/app created .seshat/blocks/ created .seshat/connectors/ created .seshat/services/ created .seshat/guardrails.yaml created .seshat/example-block.yaml
Author the graph
One YAML file per entity. Contracts, owned files, invariants, guarding tests — reviewed in the same PR as the code.
uuid: 1f6b2c… kind: block name: Billing ownedFiles: [src/billing/**] invariants: - id: amount-minor-int text: amounts are integer minor units
Arm the gate
Chain-safe: an existing pre-commit hook is preserved and runs after the check. Uninstall restores it byte-exact.
$ seshat install-hooks pre-commit hook installed (chain-safe) $ seshat check --staged pass (exit 0) $ seshat up --open seshat daemon listening at http://127.0.0.1:4870/ (pid 3121)
Autonomy needs architecture.
AI systems don't fail for lack of code — they fail for lack of structure. Seshat supplies the structure, and keeps it true while agents build.
Contracts as code
Blocks, connectors and invariants live in .seshat/ — one YAML file per entity, each with a stated purpose, versioned with the repo.
Agents at work
Agents implement autonomously inside the graph. The daemon re-evaluates on every change — drift shows the moment it hits disk.
On course
Checks run continuously and at commit time. Drift is caught, named, and corrected as part of the workflow — the system converges instead of decaying.
Governed in under a minute.
$npm install -g seshat$cd your-repo && seshat init$seshat install-hooks # arm the gate$seshat up --open # live graph UIseshat update — ed25519-signed, verified before apply, rolled out in stages. Offline or unsure, it fails safe and does nothing.
Node ≥ 22gitlinux · macOS · arm64 / x64v0.1.0 · stableoff by default · anonymousseshat update and opt-in telemetry.