Metadata-Version: 2.5
Name: carter-ai
Version: 0.22.0
Summary: AI agent scaffolding and workspace management for OpenCode
Project-URL: Homepage, https://github.com/mauriciomem/carter-ai
Project-URL: Repository, https://github.com/mauriciomem/carter-ai
Project-URL: Issues, https://github.com/mauriciomem/carter-ai/issues
Project-URL: Changelog, https://github.com/mauriciomem/carter-ai/releases
Author: mauriciomem
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: agents,ai,cli,devops,llm,opencode,scaffolding
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: jinja2>=3.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=2.3; extra == 'dev'
Requires-Dist: pytest>=9.0; extra == 'dev'
Requires-Dist: ruff>=0.17; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Description-Content-Type: text/markdown

# Carter

[![CI](https://github.com/mauriciomem/carter-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/mauriciomem/carter-ai/actions/workflows/ci.yml)

Carter turns [OpenCode](https://opencode.ai/v2/docs/) into a small team of AI
specialists: an architect, an engineer, a DevOps engineer, a security reviewer and
more, coordinated by one orchestrator called **Maestro**.

You describe the work in plain language. Maestro hands it to the right specialist,
and anything risky (a push, a `terraform apply`) waits for your approval.

## Why Carter

- **Specialists, not a generalist.** Each agent has its own instructions, model and
  permissions, so answers stay focused on one domain.
- **Safe by default.** Agents ask before risky actions, and only the DevOps agent can
  change infrastructure. No agent pushes: you do, with `carter push` (or you approve each push
  DevOps asks for).
- **Writes stay under your control.** Commits, pull requests and Jira updates are
  shown as a plan first and run only after you say yes.
- **Agents can have their own identity.** Optionally, agent commits are made under a GitHub
  account of their own and signed with its key, with you as the author
  ([Identity and signing](docs/guides/identity-and-signing.md)).
- **It remembers.** Lessons, decisions and plans are saved as plain Markdown files
  that you can read and edit.

## What you get

```mermaid
flowchart LR
  you([You]) --> M[Maestro]
  M --> A[Architect] & E[Engineer] & D[DevOps] & S[Security]
  M --> L[Learner] & P[PM] & N[Narrator]
```

| Agent | Ask it about |
|-------|--------------|
| **Maestro** | Anything. It answers simple questions itself and routes the rest |
| **Architect** | System design, cloud architecture, trade-offs, decision records |
| **Engineer** | Code, tests, refactoring, code review |
| **DevOps** | CI/CD, Terraform, containers, git. You push (or approve its push request); agents open the pull request |
| **Security** | Threat models, secure code review, vulnerability triage |
| **Learner** | Explanations and research, with sources |
| **PM** | Plans, roadmaps, risks |
| **Narrator** | PR descriptions, Jira comments, docs and announcements, with secrets and internal details removed |

Carter also ships 27 **skills**: step-by-step playbooks (Terraform, Go, threat
modeling, Jira, and more) that an agent loads only when the task needs one.

## Install

You need [uv](https://docs.astral.sh/uv/), git and OpenCode 2.1 or newer on your `PATH`.

```bash
uv tool install carter-ai    # from PyPI; or: pipx install carter-ai (needs Python 3.11 or newer)
carter install
```

> [!TIP]
> `carter: command not found`? Run `uv tool update-shell` and open a new terminal.

`carter install` writes the agents and skills to `~/.config/opencode/`, so they
work in every project. Upgrade with `uv tool upgrade carter-ai` and remove with
`carter uninstall` first, then `uv tool uninstall carter-ai`. Pinning a version, a
one-off run with `uvx`, moving from an earlier git install and verifying a release
are in the [install guide](docs/guides/install.md). To report a vulnerability, see
[SECURITY.md](SECURITY.md).

## First run

1. Start `opencode` in any project directory.
2. Switch to **carter-maestro**: press `Shift+Tab` until it is selected, or pick it
   from `/agents` (`Ctrl+X` then `A`).
3. Ask for something:

```text
Design a REST API for a task-management app.
Use carter-security to review src/auth.py.
ops: create a feature branch, commit my changes and open a pull request.
```

The specialists run as subagents, so you reach them through Maestro by naming them
or simply describing the task. The `ops:` prefix starts the
[approval flow for write operations](docs/guides/write-operations.md).

## Global install or per-project workspace

| | Global (`carter install`) | Workspace (`carter init`) |
|---|---|---|
| Where | `~/.config/opencode/` | `.opencode/agents/` in one project |
| Settings | Shipped defaults | Your `.carter/carter.yaml` (models, safety level, …) |
| Extras | — | Plans, session checkpoints and project knowledge in `.carter/` |

Start with the global install. Add a workspace when a project needs its own settings
or memory: see [Your first workspace](docs/guides/first-workspace.md).

## Safety in one paragraph

Every agent starts from "ask before doing anything". Reading and searching are free.
Local edits are allowed only for agents that need them. Pushing (`carter push`) and merging
are yours; agents may open, edit and comment on pull requests; publishing to Jira and Slack and
Vault secret reads are reserved for DevOps and always ask. Destructive or
infrastructure-changing commands ask too, and in `strict` mode they are blocked
outright. OpenCode enforces these rules, not the model. `carter install` also offers guards
(one question, you can decline) that cut Carter agents' shells off from your SSH keys and `gh`
login. Read
[Safety and permissions](docs/guides/safety-and-permissions.md) for the details and
the limits.

## Documentation

Start with the [docs index](docs/README.md). The most useful pages:

- [Using Carter](docs/guides/using-carter.md) · [Safety](docs/guides/safety-and-permissions.md) ·
  [Write operations](docs/guides/write-operations.md) · [Identity and signing](docs/guides/identity-and-signing.md) ·
  [Review-only CI](docs/guides/ci-review.md) · [MCP servers](docs/guides/mcp-servers.md)
- [CLI](docs/reference/cli.md) · [Configuration](docs/reference/configuration.md) ·
  [Troubleshooting](docs/troubleshooting.md) · [Contributing](docs/contributing/development.md)

## License

`GPL-3.0-only`. See [LICENSE](LICENSE).
