Sidecat A Python prototype
The first generation proved the shape of the problem: AI-assisted work needs durable records, resumable orchestration, and governed external effects. It is retired — its job was to find the real edges of the problem, and it did.
Architecture
Three generations, one problem.
Sidecat is on its third build of the same idea: serious AI-assisted work needs durable state, explicit authority, and recoverable evidence — not just the ability to act. Each generation kept what survived and shed what had grown heavy.
Start with the master design — the short human artifact from the 2026-07-03 design run: ten patterns, two operator decisions, diagrams, and pointers to the typed verdict corpus and archived run record. The story of how it was made is on the blog.
A Go runtime
The second generation made those ideas usable day to day — durable work records, gates, evidence, receipts, and service checks. We still run it: it is the control plane the current rebuild is coordinated through. It also exposed the cost of a sprawling command surface, so the next build mines it for mechanisms rather than preserving its whole shape.
A ground-up rebuild
The current generation is a rebuild around a smaller language, stricter object contracts, and clearer surfaces. It keeps the lessons that survived and drops the accumulated surface area, so the durable record — not a pile of commands — is the thing you work with.
Governance model
The core record is an effect attempt.
Sidecat organizes work as a typed graph and represents protected or observable actions as effect attempts. AAuth can enrich those records, but the same shape also works for Unix permissions, containers, Git ACLs, credential custody, operator review, cloud IAM, and observe-only logging.
Subject
The actor, agent, session, process, package, user, or sidecatd node making the attempt.
Effect
The action shape: file.write, git.push, model.call, dns.update, credential.admit, or another declared effect.
Target
The resource being touched: file, repository, branch, service, credential, model, domain, environment, or remote node.
Context
The work graph around the attempt: scope, work item, work cycle, plan, package, authority zone, and effective state.
Decision and result
The decision, the observed result, and the receipt or evidence refs that support the claim.
The invariant is simple: every protected or observable action can be represented as a Sidecat effect attempt, even when no AAuth artifact exists. Every AAuth artifact may attach to an effect attempt, but no effect attempt requires AAuth.
Services and clients
sidecatd owns authority; clients project it.
The current Sidecat shape is a service substrate with focused clients around it, not one giant application. sidecatd remains the source of authority. Clients help agents and operators see, act, review, replay, or reason over that state.
sidecatd
The local authority service. It owns work records, operations, evidence, receipts, messages, and the authority boundary.
sidecat
The agent and operator command client. It should become a thin way to start work, call operations, inspect records, and resume.
Sideinfra
The intelligence client. It derives trust gaps from sidecatd projections, repo facts, and profile declarations, but it does not own authority.
Sidebar
The operator review client. It presents reviewable units and sends decisions back to Sidecat services.
Sidebird
The replay and overview client. It explains what happened, why it happened, and which evidence supports the story.
Sidespy
The live visibility client. It watches current activity and warnings without becoming a review or authority surface.
Authority
Governance, authorization, and enforcement stay separate.
Authority zones are Sidecat-native boundaries. They say where effects should be tracked, explained, limited, evidenced, authorized, or blocked. They do not grant power by themselves, and they do not mean AAuth is required.
Governance
What is being attempted, why, under which scope, work item, cycle, package, authority zone, and evidence expectation.
Authorization
Which identity, grant, token, credential, approval, operating-system user, ACL, or role applies to the attempt.
Enforcement
What actually permits, blocks, delegates, or observes the effect: Sidecat, AAuth, Unix, containers, Git, cloud IAM, operator review, or a custom adapter.
Claims to evidence
What each step has actually proven.
Earlier preview milestones shipped with scenario corpora and evidence maps. Those historical details shaped the current rebuild, but the active source truth now lives in the repository's formal files, tests, fixtures, package files, release notes, and service-owned Sidecat work records.
Claim. A shell command runs under custody: retained stderr/stdout evidence, derived gaps, a review packet, and a replay frame — even when the command "passes."
Evidence. Scenario corpus: 79 assertions across 22 stories, plus a live demo. The signature story: a release check that passes while preserving a hidden warning for review.
Claim. A small script activates an environment and lowers capture forms into the same custody path; validation is a no-effect planning surface with machine-actionable diagnostics.
Evidence. Scenario corpus: 147 assertions across 36 stories. Diagnostics carry stage, cause, form kind, and recovery action — no English parsing required.
Claim. Packages preview through simulate → admit → activate, each step stored and explainable; activation never grants ambient authority.
Evidence. Scenario corpus: 90 assertions across 15 stories against stored simulation, admission, and activation records.
Claim. Session hooks declare and fire inside the session record with full provenance; watches are admitted standing autonomy with mandatory budget and TTL, whose state derives entirely from durable records. Polling is not firing — only the job record is the firing.
Evidence. A live end-to-end demo: a CLI-admitted watch fires on a script-lowered capture, hook and watch lenses narrate every firing back to its trigger, and an independent observer tails the same records read-only. A dedicated scenario corpus covers suspension, default re-trigger blindness, and quiet polling.
Claim. Authority is proven, never asserted: authority_granted derives from a verifiable Ed25519 receipt bound to the exact effect, inputs, and applied result. Governed advisor calls retain their exact request bytes before the provider is called — the founding incident, made structurally impossible — and record the provider-reported model identity as a claim distinct from what was requested.
Evidence. Scenario corpus: 24 assertions across 7 stories, including a byte-exact recomputation of the request hash from the retained bytes, crash recovery from a seeded mid-call record, and the lens naming every model claim "recorded, not endorsed". A live demo runs the full story; tamper batteries prove that changing any bound byte breaks the grant.
Claim. Every record kind lives on one durable, append-only SQLite plane, and the plane is the default posture. The append-only constraint turns into stronger custody — the full failure-table history of every advisor call persists durably as revisioned rows.
Evidence. A daemon booted with no flags serves every record kind from the plane; a legacy files-mode data directory migrates losslessly at boot. The earlier corpora pass in both storage modes, with the store mode recorded in each summary.
Claim. Credentials are admitted standing authority with an endpoint allowlist, purposes, a budget, and a lifetime. The secret is late-bound — the transport injects it after the send journal — never enters any record, and egress outside the allowlist is denied durably.
Evidence. A real-transport advisor call keeps its receipt binding intact and emits a usage event; the secret on disk is 0600 and absent from every record, enforced by an inversion validator; budget and lifetime exhaustion suspend, and later calls deny before assembly.
Claim. A human decision recorded through the review surface changes the work state in the daemon and creates a tracked follow-through obligation — a decision that needs evidence is an obligation, not a note — visible in replay and binding on resume.
Evidence. Scenario corpus: 46 assertions across 6 stories, plus a replay test in which a second agent's resume brief reflects the undecided blocking review, without any chat history.
Claim. Work records and evidence move between environments with custody intact: a sealed, content-addressed bundle exports, verifies offline, refuses tampering, and imports all-or-nothing into a clean environment, with retention classes enforced rather than described.
Evidence. Scenario corpus: 27 assertions across 3 stories, plus a replay-against-imported-capture test. An adversarial multi-lens review hardened the import path before it landed.
Claim. The milestones compose. One runnable scenario walks install → capture → review decision → replay → resume → package activation → advisor call through connector custody → export, in a fresh environment, with a single green or red signal.
Evidence. Scenario corpus: 21 assertions across 7 stories, walking one work reference, one credential, and one daemon through every seam — green on the built surfaces, surfacing nothing missing. A no-new-features milestone that separates feature-complete from release-ready.
None of these are tagged releases, production runtimes, or stable command surfaces. They are build milestones of an active rebuild, each one verified before it lands. The earlier line proved action-first command experiments, local operator authority, package JSON calls, a manually run AAuth-backed GitLab push proof, and the first formal effect_attempt governance model. The Sidecat operation line carries those lessons into the operation catalog and workbench line. The roadmap lays out the rest of that climb.
Design notes
The design, in its own words.
Short, dated public adaptations of working design notes from the fourth-generation line. The active source truth is the repository state: the Gen5 architecture maps, code, tests, and Sidecat work records.
The master design
The short human artifact for the 2026-07-03 design run: ten patterns, two operator decisions, diagrams, and pointers to the typed verdict corpus and archived run record.
System tenets — the Emacs lessons
The eight tenets that make Sidecat a system rather than an application: primitives over features, one authority boundary, the crystallization gradient.
Authority receipts
authority_granted is derived, never asserted: every grant binds to a verifiable Ed25519 receipt over the exact effect, inputs, and result.
Advisor calls under custody
The question is kept before it is sent, the answering model is recorded as a claim, and every failure lands in a loud typed state.
Hooks and watches
Session hooks as invited extension; watches as admitted standing autonomy with mandatory budget and TTL. Polling is not firing.
The record plane
An append-only SQLite plane with honest conflicts, revisioned transitions, crash recovery, and an independent read-only observer.
Connector custody
Real service credentials as admitted standing authority, whose secret is the one absence the records are designed to have.
Where it is headed
The durable record is the product.
The rebuild is organized around one idea: the object system — work, authority, evidence, review, replay — is the source of truth, and every surface is a lens over it. The goal is governance that speeds work up rather than slowing it down: less time rebuilding context, fewer silent failures, and clear hand-offs between an operator and one or more agents.
Durable state
Work survives across sessions, so the assistant, operator, and review surfaces all refer to the same record instead of a chat history.
Explicit authority
Anything that spends trust — commits, pushes, deploys, external calls — goes through explicit authority and leaves a receipt. Agents are keyless; the daemon holds keys and grants effects one at a time.
Recoverable evidence
What happened is retained next to what the agent was shown, so the work can be reviewed, replayed, and recovered. Absence is a recorded fact, not a silent default.
Replayable language
Work is expressed in a small, durable language — ten verbs, locked deliberately — so a later agent can re-read and resume it rather than reconstruct it.
The near work is the climb to hosted sidecat.org: account identity, operator approvals, credential grants, sidecatd-to-sidecatd federation probes, API-first agent access, messaging, replay, and package-driven effects. AAuth is first-class where it helps, especially for agent identity and mission-shaped authorization, but Sidecat's graph still works when governance is observe-only, local, containerized, Git-backed, operator-mediated, or cloud-policy-backed. The roadmap orders the climb; the blog carries the reasoning.