Estigia

[estigIA — AI harness. Light. Local. Agentic.]

[CI] [License: MIT] [Rust 1.97+] [MCP: 37 tools] [Linux, macOS, Windows] [Glama MCP server]

estigIA — workflow authority for AI coding agents

Your agent says it claimed the issue, that the review passed, that the branch is current. Estigia turns those sentences into things that were checked: the claim lives in a local store (~/.estigia/state.db), every later write is measured against it, every step that cannot be undone re-verifies it, and a review verdict is bound to exact bytes, so a push invalidates it.

One binary, under whatever agent you already use; it does not run your model. Its only detached processes are a reviewer CLI and the declared checks (which).

El río del juramento. Lo que un agente promete, queda ligado a unos bytes exactos.

Leteo is the river of forgetting. Estigia is the river of the oath — the gods swore by its waters, and perjury cost nine years outside Olympus. Two rivers of the same underworld, opposite jobs: one makes you forget, the other holds you to it.

What it feels like

Mostly, nothing: a run that has claimed nothing works as before. When it refuses, it says what it read and what to do about it:

$ git push origin HEADestigia: git push: gh issue view failed (1): none of the git remotes ... (read-failed)  [world-action] the tracker could not be read; write nothing and retry the readerror: failed to push some refs

The tracker could not be read is a different answer from you may not push, and Estigia will not turn the first into the second. That distinction is most of the design.

FLOW — Focused, Lean, Outcome-driven, Witnessed

FLOW is Estigia's own methodology: how a run takes a piece of work from an issue to a merge.

• Focused: small work stays small. Understood work is done directly, not planned, and exploration is in proportion.
• Lean: one writer, the smallest topology that works, and review only as heavy as the risk.
• Outcome-driven: done means the issue's acceptance criteria hold, with evidence, merged and verified.
• Witnessed: deterministic evidence first, then review by a context that did not write the change, and the merge at the reviewed head.

It rests on two pillars: the claimed issue is the record of the work, and the publication is the review candidate. Four principles follow from them: small work stays small; review is sized by risk; a review lineage gets a bounded number of corrections (Corrections per lineage, default 3); and the heavyweight two-judge review (Judgment Day) runs only when asked for.

You start it with flow (analyse and build, choosing the next issue from the tracker), flow dev [issue] (build) or flow triage (analyse and file at most one evidenced issue). A run then goes through five steps, which may merge or repeat:

flowchart LR    understand["Understand"] --> route["Route"] --> execute["Execute"] --> verify["Verify"] --> deliver["Deliver"]    verify -->|"finding"| execute

Work that spans sessions or divides into units with their own acceptance keeps an ordered checklist on the claimed issue (task), never in a file. FLOW is how a run works; the workflow below is what Estigia enforces while it does.

The workflow

The workflow is the part a run cannot talk its way around: the states an issue moves through and the checks at each boundary. FLOW runs inside it.

flowchart TD    analysis(["analysis"]) --> ready(["ready"])    ready --> claim["claim"]    claim --> inprogress(["in-progress"])    inprogress -.-> blocked(["blocked"])    blocked -.-> inprogress    inprogress --> publish["publish"]    publish --> review(["review by risk tier"])    review --> verdict["verdict on exact bytes"]    verdict -->|"push: republish"| publish    verdict --> deliver["deliver"]    deliver -->|"approved"| release["release"]    release --> done(["done"])    deliver -.->|"needs a person"| person["hand-back"]    person -.-> deliver
    classDef state fill:none,stroke:gray,stroke-width:2px    classDef action fill:none,stroke:gray,stroke-dasharray:4 3    class analysis,ready,inprogress,blocked,review,done state    class claim,publish,verdict,deliver,person,release action

Rounded nodes are states, square nodes are actions; dotted edges are the exceptions. What the gate holds at each boundary:

• One state at a time, in the local store; labels are a projection, written and read back. blocked names an exact exit condition and who discharges it.
• A claim before the first write. The earliest live claim wins, and the gate re-verifies it on every write it sees and at every irreversible step.
• A verdict bound to exact bytes — epoch, head, base and digest. Any push invalidates it: republish and ask again. A body says Refs #<n>, never a closing keyword.
• Release last, after the evidence is posted (details).

The contract an agent reads is skill/SKILL.md; the GitHub half is delivery.md; review cost per tier is in review-cost.md.

Install

Pick one route. Each is copy-paste.

Linux, macOS:

curl -fsSL https://raw.githubusercontent.com/asanabrial/estigia/main/scripts/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/asanabrial/estigia/main/scripts/install.ps1 | iex

npm (installs and sets up in one step):

npx -y @asanabrial/estigia setup --all

Cargo (needs Rust):

cargo install estigia

Then register it in your agents, and check:

estigia setup --all      # or: estigia tuiestigia statusestigia doctor

Linux archives need glibc 2.39+ (not Debian 12, Ubuntu 22.04, RHEL 9); there, use cargo install estigia. The installers check the archive against its published checksum and refuse a mismatch. The binary lands in ~/.local/bin/estigia (%LOCALAPPDATA%\estigia\bin\estigia.exe on Windows); ESTIGIA_INSTALL_DIR moves it and ESTIGIA_VERSION takes a tag other than the latest. The npm package carries no binary: it fetches the same archive, and it is what the MCP registry entry starts (mcp-name: io.github.asanabrial/estigia). A source build has no installer record, so the commands that write into your agents ask for --allow-source-build (why); cargo install --git https://github.com/asanabrial/estigia takes main. The Dockerfile builds a server-only image; none is published.

Set it up in your agents

Installing the binary changes nothing on its own.

1. estigia tui opens the setup screen; s shows what it will write. Without it: estigia setup claude-code for one agent, estigia setup --all for all; --dry-run on either writes nothing.

2. Optionally route a role to a model, the spelling the screen ends by printing:

   sh

   estigia config set "Model routing" "developer=inherit" --agent claude-code

3. In a repository where any agent may write, estigia guard installs a pre-push hook that refuses a push no live claim authorises, whoever typed it.

setup installs the skill, a directive in the agent's instruction file and the hooks, which go into every agent with an event able to refuse — five of them, in a gate that reads five dialects. What else it writes is in what it writes.

Verify

1. estigia status: what is installed, where, and whether each agent is told (tools on) and stopped (gate on).
2. estigia doctor: skill, gh, remote, guard, prune, permission and the rest, read-only.
3. estigia sessions, feed, where, needs-person and changes (uncommitted work) are read-only too.

Uninstall

Uninstall removes what Estigia created and nothing else: not another tool's block, not your notes, not a file of its own you have since edited, which it keeps and names. Run in this order:

estigia uninstall --all --dry-run   # changes nothing; says what the next line will doestigia uninstall --all             # or: estigia uninstall claude-codeestigia guard --uninstall           # in each repository with the push guardestigia config forget               # in each checkoutcargo uninstall estigia             # source build only; otherwise delete the binaryrm -rf ~/.estigia                   # optional, read the warning first

1. The dry run is safe to repeat; estigia uninstall claude-code leaves the other agents alone.
2. uninstall --all takes Estigia out of every agent.
3. guard --uninstall removes only a hook Estigia wrote, and must go before the binary, which the hook calls.
4. config forget removes <checkout>/.git/estigia/, the repository settings every uninstall survives; it says which file it removed.
5. Remove the binary by the route you installed with. Installer script or npm: delete ~/.local/bin/estigia (or $ESTIGIA_INSTALL_DIR/estigia); on Windows delete %LOCALAPPDATA%\estigia\bin\estigia.exe (or under %ESTIGIA_INSTALL_DIR%) and take that directory out of the user PATH. A source build: cargo uninstall estigia.

Before rm -rf ~/.estigia: state.db is the workflow store, one copy on this machine: claims, states, receipts, findings, verdicts, spend, tasks, the decision history, the session registry and the mailbox. Beside it: run pointers; jobs/; snapshots/ (up to three copies of the store); lifecycle/ (the binary's provenance records); workspaces/ and roots/; the screen's language; your checkouts list. The last uninstall --all takes the store and the run state and keeps the rest (per entry). Delete it only when you no longer want the history of what this machine's gate decided.

What REPLACE and OVERWRITE mean is in docs/what-it-writes.md.

A harness, not a document

The contract under skill/ is text an agent may ignore, so Estigia holds the tools: a PreToolUse gate, a Stop hook, a pre-push hook under git, and thirty-seven operations with schemas below. The local store is the authority; the tracker keeps a projection that never decides. The diagram, the loop plugins and the gate's rules are in what it writes.

The tools

Thirty-seven operations, table-driven. Thirty-one map to operations the binding must provide; send_message, ask, wait, inbox and list_sessions are answered by the local store and deliver composes the rest with the merge gate, outside the binding. tools/list carries each schema and a readOnlyHint. The seven delivery tools (claim, publish_review, collect_review_input, deliver, release, transition, review_status) carry _meta["anthropic/alwaysLoad"]; every tool takes compact (cost):

read   verify_claimread   list_stateread   review_statusread   review_readread   tasksread   list_sessionsWRITE  claimWRITE  handoffWRITE  heartbeatWRITE  transitionWRITE  commentWRITE  blocked_untilWRITE  taskWRITE  send_messageWRITE  askWRITE  waitWRITE  inboxWRITE  releaseWRITE  ensure_statesWRITE  start_branchWRITE  judge_workspacesWRITE  assistWRITE  pr_reviewWRITE  draft_prWRITE  ready_prWRITE  review_stagesWRITE  review_threadWRITE  createWRITE  publish_reviewWRITE  republish_reviewWRITE  handoff_reviewWRITE  record_review_findingWRITE  record_dispositionWRITE  collect_review_inputWRITE  escalate_reviewWRITE  record_spendWRITE  deliver

where, feed, status and flush are commands of estigia rather than tools; asking for one of them, or for a name the surface dropped, answers what replaces it. review_read also reads the review tier (view: tier) and the delivery target (view: target); collect_review_input also starts a reviewer (launch) and runs the declared checks (checks); deliver stops after the verdict or the CI release with until.

Thirty-seven tools. The contract names seventeen operations every binding must map; the tools absorbed some under a surviving name (why). Arguments are in each tool's schema.

Configuration

Thirty-two typed settings, in docs/configuration.md, grouped by theme and shown in one order by estigia config list, the setup screen and the reference alike. Each row says whose answer it is: this agent's, this repository's, every checkout's or this machine's.

The ratchet

A message may name a command only when running it discharges the block; a refusal carries a typed code and a runnable resolution (classes):

  run: estigia setup --all   # or one of: agents, claude-code, codex, opencode, pi, cursor, zcode, deepseek-harness

What this instrument does not measure

docs/honesty.md names what this crate does not check, each with the measurement that found it; docs/README.md maps the rest of the set.

Layout

src/harness/   the gate, the run pointer, the transport, the lifecycle protocol, doctorsrc/setup/     agent adapters, companions, dry-run, exact inversesrc/config/    typed model, the settings table as datasrc/cli/       dispatch, and the only place a refusal becomes an exit codeskill/         SKILL.md, bindings/, policies/, protocols/, references/, assets/, agents/ — not compileddocs/          the reference the sections above point at, one question eachscripts/       the two installers a release is fetched with, and the Windows source reinstall

AGENTS.md — which CLAUDE.md is a link to — is how an agent works here.

Exit codes

Four, and none of them means "something went wrong":

Why there are four: docs/refusal-classes.md.

Licence

MIT. Files derived from another MIT-licensed project carry its notice in THIRD_PARTY_NOTICES.md.