Seshat — AI builds fast. Seshat makes it last.

seshat validate: ok 16 blocks 25 connectors 2 services Seshat governs its own repo — dogfooded since day one

Before a temple rose in ancient Egypt, Seshat stretched the cord — measuring out its foundations before the first stone was laid. When it stood, she wrote it down.

Mistress of Builders · Mistress of the House of Books Lay it out. Keep it true. Write it down. — this is that, for software.

I · Architecture

Lay the system out.

A living constraint graph in .seshat/ — blocks, connectors, services. One YAML file per entity, reviewed like code. Whether the system exists yet or not.

Start from nothing

The graph exists before the code does.

Author blocks, contracts and invariants in an empty repo — every element carries a rationale, so nothing enters the system without a purpose on record. Plans preview as ghost geometry on the canvas; agents then implement at machine speed inside contracts that were decided before they started. Blocks begin honest grey and turn green as guarding tests land.

Start from what you have

Ten years of code gets a record in an afternoon.

Map an existing repo into the graph, incrementally. Pervasive things — the database, auth — become contexts you sit inside, not nodes with edges to everything. Where nothing can be verified yet, blocks render unverified instead of falsely green. Then the human pass: write the rationale the code never had, and freeze what must not move.

uuid: 1f6b2c…
kind: block
name: Billing
rationale: charges are the only money-moving path
ownedFiles: [src/billing/**]
contract:
  methods: [{ name: charge }]
invariants:
  - id: amount-minor-int
    text: amounts are integer minor units
tests:
  - path: test/billing.test.ts
    guards: [charge, amount-minor-int]

What an entry looks like

The record is data, not prose. A block says what it owns, what it promises, which invariants hold, which tests guard them — and why it exists at all. It travels in the repo and gets reviewed in the same pull request as the code it governs.

Connectors get entries of their own: transport, auth, design pattern, pinned schemas. They own the contract of the interaction.

Every element has a purpose

No orphan parts, no mystery glue. If a block can't say why it exists, it doesn't belong in the system.

rationale · required reading

Connectors are first-class

An interaction is an entity, not a line. Sync or async, REST or events, which auth, which schema — pinned by hash so a schema edit is an architecture change.

mTLS + payments:capture · sha256-pinned

One graph, every altitude

Blocks, contexts, services — the same system at three zoom levels, live in the browser. Blast radius answers what breaks before you change it.

seshat up --open · 127.0.0.1 only

II · Management

Let the agents build.

Agents supply the how, at machine speed. You stay in the loop as the architect. The built-in workflow keeps every change on course — deterministic, local, no LLM in the loop.

dev@payments — zsh

$ 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 spec delta, local to the clone, spent on first use.

0–3

Exit codes are a contract0 pass · 1 violations · 2 spec invalid · 3 internal — frozen and CI-safe.

Small changes land. Architecture changes get reviewed.

Seshat draws one line and never blurs it: a change within a contract flows straight through; touching a contract, connector or invariant is a decision. Renovation, with permits — intent, spec delta, blast radius and diff in one review, decided by you. And the rules always evaluate against the base spec, so a rulebook rewrite can't ride in the commit that needs it.

III · Records

Keep every decision.

Every change lands in a journal whose entries are metadata only — it physically cannot carry code. The decision outlives the pull request.

conforming

Healthy

The contract is upheld. Changes inside it flow through untouched.

5 conforming · 2h ago

drifting

Contract violated

A change crossed the contract. Seshat names the invariant and points at the code.

1 drift · Billing.charge()

frozen

Untouchable

Marked off-limits. Edits are held until the freeze is lifted — itself an approved architecture change.

no activity · frozen 34d

violation

Hard failure

A workflow rule fired. The change is named, held, and never lands as-is.

1 violation · change held

unverified

Honest grey

Nothing can prove this contract yet — so Seshat says so. Guardrails still enforce.

degraded · not unprotected

Never blurred

Small changes and architecture changes stay visibly distinct on every block's activity trail, forever.

3 changes · 1 arch · 2h ago

Derived, never stored

State is computed from the record every time. The graph cannot lie about the territory.

deriveState(entity, findings, coverage)

On file, forever

Approved architecture changes land as journal entries with their approval hash. Findings keep their identity across unrelated edits.

spec.changed · approval.recorded

Trust, stated flatly

Nothing to take on faith.

The journal cannot carry codeEntries are schema-enforced metadata — paths, hashes, counts. Never source, diffs, or secrets.

Checks never phone homeThey run locally against the git index. The network is touched only by seshat update and opt-in telemetry.

Updates are signeded25519, verified offline before anything is trusted, applied only on explicit consent. Offline, it fails safe.

Seshat governs SeshatThis repo ships through its own graph and its own workflow — from the first commit.

Install

Governed in under a minute.

$npm install -g seshat

$cd your-repo && seshat init

$seshat install-hooks # arm the workflow

$seshat up --open # the live graph

Updates ship through seshat update, rolled out in stages from the control plane.

RuntimeNode ≥ 22

VCSgit

Platformslinux · macOS · arm64 / x64

Latest releasev0.1.0 · stable

Telemetryoff by default · anonymous

Hooks are chain-safe: an existing pre-commit hook is preserved and still runs, and uninstall restores it byte-exact.