🦀
Metacognition for AI agents.
A repo-native governance kernel for bounded, convergent, proof-backed work.
Works with Cursor, Claude Code, Codex, Amp, Pi, Antigravity, Grok, and other coding agents.
Keep your harness. Govern the work.
Decapod gives coding agents a persistent way to check their work against the project's intent. Requirements, decisions, task ownership, and validation evidence stay with the repository across agents and sessions.
An agent plans and implements a change. Decapod keeps track of what that change must satisfy and the evidence required to call it complete. Failed checks and unmet requirements remain visible for the next iteration or handoff.
That is the metacognitive loop: establish intent, do the work, check the result, and resolve what remains. The project retains the basis for judging its progress as the work changes hands.
Run this inside your project:
cargo binstall decapod && decapod initOpen your preferred coding agent and describe the change you want. Decapod supplies the project guidance and workflow the agent uses to plan, implement, and validate it.
| Concern | What stays with the project |
|---|---|
| Intent | Specs and scoped plans describing purpose, expected behavior, and boundaries |
| Decisions | Engineering decisions, their context, and relevant source references |
| Ownership | Task claims, overlap checks, and isolated workspaces for parallel work |
| Rules | A shared Constitution and project-specific overrides |
| Completion | Configured checks, validation results, and the evidence required for acceptance |
| Continuity | Plans, work history, and unresolved validation state for the next agent |
Bounded means the work has explicit scope, constraints, and ownership.
Convergent means progress is checked against recorded intent, with unmet requirements carried forward until resolved.
Proof-backed means completion is supported by recorded evidence from the project's validation requirements.
Project specs describe the system's purpose, architecture, and expected behavior. The agent creates a scoped plan before implementation, making the intended change and its boundaries explicit.
The agent retrieves relevant guidance with source references, follows the Constitution and project overrides, and records decisions as it works.
Parallel agents can claim separate tasks, check for overlap, and use isolated workspaces. Ownership stays explicit as work moves between contributors.
Decapod runs the configured validation workflow and associates the results with the current change. Failed checks and missing required evidence keep completion unresolved.
The agent uses those results to address outstanding requirements and validate again. What has been verified remains available for inspection.
Another agent can continue the same work using the recorded plan, decisions, task ownership, and validation state. Unfinished obligations survive the session that created them.
Your existing project tools, tracker, CI, and pull request process remain part of the workflow.
Decapod is a Rust CLI. Each invocation runs, returns its result, and exits. It is local-first and daemonless.
State lives with the project:
.decapod/
├── governance.json # Plans, work history, claims, validation results
├── managed/specs/ # Purpose, architecture, expected behavior
├── workspaces/ # Isolated task checkouts
├── config.toml # Project and validation settings
└── OVERRIDE.md # Project-specific engineering guidance
Validation runs locally by default, with optional remote Buildkite preflight. The configured checks and recorded evidence define what Decapod can recognize as verified completion.
Governed execution architecture · Configuration reference
Decapod includes engineering guidance for architecture, security, testing, and other development decisions. Agents consult it during planning and implementation.
.decapod/OVERRIDE.md adds project-specific instructions. The repository carries the shared rules and local requirements together, giving each agent the same starting point.
Conflicts that require a decision remain visible so they can be resolved explicitly and preserved for subsequent work.
Documentation · Agent API · Agent contract
Research paper · Research site
Bug reports, reproducible failure cases, documentation fixes, and pull requests are welcome.
See the contributing guide for the development workflow and the security policy for reporting vulnerabilities.