Metadata-Version: 2.4
Name: sutra-cli
Version: 0.3.9
Summary: Governed AI-development workspaces for Claude Code, Codex CLI, and future coding runtimes.
Author: Sutra Team
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,claude,cli,codex,governance
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Requires-Dist: gitpython<4.0,>=3.1.0
Requires-Dist: jinja2<4.0,>=3.1.0
Requires-Dist: pydantic<3.0,>=2.0.0
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: rich<14.0,>=13.0.0
Requires-Dist: typer<1.0,>=0.15.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest-tmp-files>=0.0.2; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://github.com/pypa/pipx):

```bash
pipx install sutra-cli
```

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

```bash
uvx --from sutra-cli sutra --help
```

For local development installation:

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

## Quick Start

```bash
# 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

| Command | Description |
|---------|-------------|
| `sutra init` | Initialize a governed workspace |
| `sutra sync` | Sync .sutra/ to configured runtimes |
| `sutra doctor` | Validate workspace integrity |
| `sutra context refresh` | Scan repo and update context |
| `sutra context show` | Display current context |
| `sutra context diff` | Show context changes |
| `sutra policy validate` | Validate policy files |
| `sutra guard enable` | Enable all guardrails |
| `sutra guard disable` | Disable guardrails |
| `sutra guard careful` | Enable destructive-command warnings |
| `sutra guard freeze <path>` | Restrict edits to a path |
| `sutra runtime add <runtime>` | Add a new runtime |
| `sutra report` | Generate evidence report |

## 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

| Profile | Agents | Best For |
|---------|--------|----------|
| `fullstack` | backend, frontend, security, QA | Full-stack web apps |
| `backend` | backend, security, QA | API/service projects |
| `frontend` | frontend, QA | Frontend-only projects |

## Roadmap

See [ROADMAP.md](file:///Users/bhushan/Documents/Projects/sutra/ROADMAP.md) for the detailed vision, target architecture, and target build phases.

## License

MIT
