<p align="center">🦀</p>
<p align="center">
<code>cargo install decapod && decapod init</code>
</p>
<p align="center">
<strong>Decapod</strong><br />
The governance runtime for AI coding agents.
</p>
<p align="center">
Local-first, repo-native, and built for verifiable delivery.
</p>
<p align="center">
<a href="https://github.com/DecapodLabs/decapod/actions"><img alt="CI" src="https://github.com/DecapodLabs/decapod/actions/workflows/ci.yml/badge.svg"></a>
<a href="https://crates.io/crates/decapod"><img alt="crates.io" src="https://img.shields.io/crates/v/decapod.svg"></a>
<a href="https://github.com/DecapodLabs/decapod/blob/master/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
<a href="https://ko-fi.com/decapodlabs"><img alt="Ko-fi" src="https://img.shields.io/badge/Support-Ko--fi-ff5f5f?logo=ko-fi&logoColor=white"></a>
</p>
---
## Why Decapod 🧠
AI coding agents can write code fast. Shipping it safely is the hard part.
Decapod gives agents a consistent operational contract: guided execution, enforceable boundaries, and auditable completion signals. It replaces "looks done" with explicit outcomes.
Decapod is **invoked by agents; it never runs in the background**. It is a single executable binary that provides deterministic primitives:
- Retrieve **canon (constitution .md fragments)** as context.
- Provide authoritative schemas for **structured state** (todos, knowledge, decisions).
- Run deterministic **validation/proof gates** to decide when work is truly done.
Example gate: *forbid direct pushes to protected branches* — fails if the agent has unpushed commits on main.
AGENTS.md stays tiny (entrypoint). OVERRIDE.md handles local exceptions. Everything else is pulled just-in-time.
Traces: `.decapod/data/traces.jsonl`. Bindings: `context.bindings`. Architecture-agnostic (not coupled to a specific OS or CPU).
Recent independent research confirms this design direction: [Evaluating AGENTS.md](https://arxiv.org/pdf/2602.11988) (Gloaguen et al., ETH SRI, 2026; [AgentBench repo](https://github.com/eth-sri/agentbench)) found that LLM-generated context files tend to reduce agent performance while increasing cost by over 20 %; human-written minimal requirements can help slightly. Decapod was built independently and without knowledge of ETH SRI's AgentBench research or this paper.
<p align="center">
☕ Like Decapod? <a href="https://ko-fi.com/decapodlabs"><strong>Buy us a coffee on Ko-fi</strong></a> 💙
</p>
## Assurance Model ✅
Decapod is built around three execution outcomes:
- `Advisory`: guidance toward the next high-value move.
- `Interlock`: hard stops for unsafe or out-of-policy flow.
- `Attestation`: structured evidence that completion criteria were met.
## Operating Model ⚙️
```text
Human Intent
|
v
AI Agent(s) <----> Decapod Runtime <----> Repository + Policy
| | |
| | +-- Interlock (enforced boundaries)
| +------- Advisory (guided execution)
+------------ Attestation (verifiable outcomes)
```
## Features ✨
- Agent-native CLI and RPC surface for deterministic operation.
- Guided project understanding through structured prompting.
- Standards-aware execution aligned with project policy.
- Workspace safety for isolated implementation flow.
- Validation and completion gates with explicit pass/fail outcomes.
- Multi-agent-ready orchestration surface for tooling integrations.
## Getting Started 🚀
```
cargo install decapod
decapod init
```
Then use your agents as normal. Decapod works on your behalf from inside the agent.
Learn more about the [embedded constitution](constitution/core/DECAPOD.md).
Override constitution defaults with plain English in `.decapod/OVERRIDE.md`.
## Contributing 🤝
```bash
git clone https://github.com/DecapodLabs/decapod
cd decapod
cargo build
cargo test
decapod validate
```
## Documentation 📚
- Development guide: [CONTRIBUTING.md](CONTRIBUTING.md)
- Security policy: [SECURITY.md](SECURITY.md)
- Release history: [CHANGELOG.md](CHANGELOG.md)
## Support 💖
- 🐛 [File an issue](https://github.com/DecapodLabs/decapod/issues)
- ☕ [Support on Ko-fi](https://ko-fi.com/decapodlabs)
## License 📄
MIT. See [LICENSE](LICENSE).