covenant-cli

Scaffold governed agent services. Exit reports, typed I/O, memory inheritance -- from the first line of code.

Why Covenant CLI?

Every AI agent framework gives you tools to build agents. None give you tools to govern them.

Covenant CLI scaffolds projects where governance is structural, not aspirational:

• Exit reports -- every service run writes what worked, what failed, and what the next run should know
• Typed I/O -- Pydantic models for every agent input and output, no Dict[str, Any]
• Memory inheritance -- agents read prior learnings before acting, not after failing
• Registry tracking -- every service and agent registered before it runs
• Convention rules -- IDE-native governance rules for Cursor and Claude Code

The difference between an agent that works once and an agent you can trust is governance.

Quick Start

pip install covenant-cli

# Create a governed project (default scaffold)
covenant init my-project
cd my-project

# Or create a FastAPI governed API
covenant init my-api --template api
cd my-api
pip install -r requirements.txt
uvicorn main:app --reload

# Or create a Django governed webapp
covenant init my-webapp --template webapp

# Add a governed service
covenant add-service research-agent

# Check project health
covenant status

Commands

User Journeys

Four documented paths through the tool:

• First-Time Setup -- scaffold a governed project from scratch
• Iterative Development -- the learning loop across runs
• Debugging a Failing Agent -- trace failures through exit reports
• Team Onboarding -- orient a new team member in minutes

The Governance Delta

Without covenant-cli, your agents:

• Run without purpose documentation
• Pass untyped data between steps
• Fail silently and repeat mistakes
• Have no memory of prior runs

With covenant-cli, your agents:

• Declare their mandate before acting
• Use Pydantic models for all I/O
• Write exit reports on every run
• Read inheritance before starting
• Track token usage and cost per run
• Coordinate through structured memos

Same agent SDK. Same model. Different discipline.

Project Structure

my-project/
├── GOVERNANCE.md              # 18 governance rules
├── registry/agents.json       # Service and agent registry
├── memory/
│   ├── inheritance/           # Exit reports from prior runs
│   └── memos/                 # Cross-service communication
├── .cursor/rules/             # Cursor IDE governance rules
├── .claude/rules/             # Claude Code governance rules
└── services/
    └── my-service/
        ├── manager.py         # Orchestrator with exit reports
        ├── agents/            # One agent per file
        ├── schemas/types.py   # Pydantic models
        └── tools.py           # Shared tools

Application Templates

covenant init supports three project templates via the --template flag:

All templates include the same governance foundation: GOVERNANCE.md, registry/agents.json, memory/ directories, and IDE convention rules. The template determines the application layer on top.

API Template

The API template generates a working FastAPI application:

my-api/
├── main.py                # FastAPI entry point
├── requirements.txt       # Python dependencies
├── runner.py              # Background task runner
├── routers/
│   ├── services.py        # Service CRUD + trigger endpoints
│   ├── runs.py            # Run detail + exit report endpoints
│   └── health.py          # Governance health check
├── models/
│   ├── schemas.py         # Pydantic request/response models
│   └── database.py        # File-based storage (reads same files as CLI)
├── GOVERNANCE.md
├── registry/agents.json
└── memory/

No database required -- the API reads the same governance files the CLI does.

What's New in v0.6.0

• Application templates -- covenant init --template api scaffolds a FastAPI governed agent API; --template webapp scaffolds a Django webapp
• Three templates -- default (CLI), api (FastAPI), webapp (Django) -- all sharing the same governance foundation

v0.5.0

• covenant doctor -- validate project environment health: Python version, SDK, API keys, registry integrity, governance, memory directories, IDE rules, and service scaffolding

v0.4.0

• Usage tracking -- token consumption and cost per service run, visible in covenant status
• covenant memo -- cross-service communication via structured memos (send/list/read)
• covenant consolidate -- distill exit reports into summaries with optional archiving
• covenant remember -- now searches memos and consolidated summaries (compiled-truth boost)
• Status dashboard -- unread memo count, last consolidation date, token totals per service
• 3 new governance rules -- track usage, communicate via memos, consolidate regularly

Roadmap

covenant-cli is heading toward runtime governance and intelligence. See ROADMAP.md for the full plan.

Coming next:

• covenant run <service> -- execute services with automatic exit reports and usage capture
• covenant watch -- live monitoring with failure context from prior runs
• Baseline tracking -- detect regression before it becomes a production incident
• covenant suggest -- evidence-based improvement recommendations from your project's own history
• Plugin system -- make any agent framework governable

Six detailed user journeys and the full phase-by-phase plan are in the roadmap.

Credits

Inspired by mutta by Alejandro Garcia Polo.

License

Covenant Public License v1.0 -- free for individuals and teams under $1M revenue. Contact the author for commercial licensing.