Sutra

Governed AI-development workspaces for Claude Code, Codex CLI, and future coding runtimes.

One .sutra/ source of truth. Many AI runtimes. Policy-driven autonomy. Evidence-backed delivery.

What is Sutra?

Sutra turns any repository into a governed AI-development workspace with:

• Reusable agents — specialized AI roles (backend, frontend, security, QA)
• Skills — composable methodology packs (TDD, code review, planning)
• Commands — structured workflows (/implement, /review, /ship)
• Guardrails — command deny lists, approval gates, path restrictions
• Evidence — audit trails for every AI-assisted session

Installation

You can install Sutra CLI globally using pipx:

pipx install sutra-cli

Alternatively, you can run it on the fly without installing using uvx:

uvx --from sutra-cli sutra --help

For local development installation:

git clone https://github.com/aincloudtools/sutra.git
cd sutra
pip install -e .

Quick Start

# Initialize a workspace in your target repository
cd your-project
sutra init --profile fullstack --runtime claude

# Add Codex as a second runtime
sutra runtime add codex

# Detect your stack
sutra context refresh

# Validate setup
sutra policy validate
sutra doctor

# Sync changes to runtimes
sutra sync

Then open Claude Code and use:

/implement add login validation
/review
/ship

Commands

Architecture

.sutra/              ← Source of truth (you own this)
├── sutra.yaml       ← Workspace config
├── project.yaml     ← Stack and validation
├── runtimes.yaml    ← Runtime settings
├── context/         ← AI project context
├── agents/          ← Agent role definitions
├── skills/          ← Composable skill packs
├── commands/        ← Slash command workflows
├── policies/        ← Guardrails and approval gates
└── evidence/        ← Audit trails

CLAUDE.md            ← Generated for Claude Code
.claude/             ← Generated for Claude Code
AGENTS.md            ← Generated for Codex CLI

Profiles

Roadmap

See ROADMAP.md for the detailed vision, target architecture, and target build phases.

License

MIT