capo-cli 0.4.0

# Capo

A Rust-native coding agent CLI. Single binary, library-first, focused on shipping correct code through a small set of well-understood tools.

```
$ capo
```

## Install

```bash
cargo install capo-cli
```

The crate is published as `capo-cli` (the name `capo` was already taken on
crates.io); the installed binary is still `capo`.

Or grab a pre-built binary from the latest [GitHub Release](https://github.com/motosan-dev/capo/releases).

## Quickstart

```bash
export ANTHROPIC_API_KEY=sk-ant-...
capo                  # interactive TUI
capo -p "fix the failing test in src/auth/mod.rs"   # print mode
capo -c               # continue the most recent session in this directory
capo --resume         # pick a recent session
```

Capo reads `AGENTS.md` / `CLAUDE.md` from the current directory upward, so per-project context is automatic.

## Supported models

Default: `claude-sonnet-4-6` (Anthropic). Configure in `~/.capo/agent/settings.json`:

```json
{
  "model": { "provider": "anthropic", "name": "claude-sonnet-4-6", "max_tokens": 8192 }
}
```

API keys live in `~/.capo/agent/auth.json` (mode `0600`) or the `ANTHROPIC_API_KEY` env var.

## Tools

| Tool | What it does |
|---|---|
| `read` | Read a file. Always allowed. |
| `grep` | Regex search over file contents. Always allowed. |
| `find` | List files/directories by glob. Always allowed. |
| `ls` | List a directory's entries. Always allowed. |
| `write` | Create or overwrite a file. Prompts unless allowlisted. |
| `edit` | Patch an existing file via unique-string replacement. Prompts unless allowlisted. |
| `bash` | Run a shell command via PTY. Prompts every time unless allowlisted. |

Configure allowlists in `~/.capo/agent/permissions.toml`. See `docs/superpowers/specs/2026-04-23-capo-design.md` §4 for the full permission model.

## Commands & editor

Inside the TUI:

- Type `/` for the command palette — `/help`, `/quit`, `/new`, `/model`,
  `/compact`, `/resume`.
- Type `@` to fuzzy-search and insert a project file path.
- A line starting with `!` runs a shell command and sends its output to
  the agent; `!!` runs it and shows the output without sending.
- `--resume` (or `/resume`) opens an interactive picker of recent
  sessions for the current directory.

## JSON / RPC mode

Capo can speak structured JSON instead of running its TUI, for use from scripts and IDE plugins:

- **One-shot:** `capo -p "<prompt>" --json` runs a single turn and streams the result as line-delimited JSON. See [`docs/json.md`](docs/json.md).
- **Persistent:** `capo --rpc` runs a long-lived server speaking bidirectional JSONL over stdin/stdout. See [`docs/rpc.md`](docs/rpc.md).

## Skills

Markdown files in `~/.capo/agent/skills/<name>/SKILL.md` (or flat `<name>.md`) become discoverable skills. They follow the [Agent Skills standard](https://agentskills.io/integrate-skills):

```markdown
---
name: rust-error-triage
description: Use when debugging Rust compile errors or runtime panics
---

Body content (loaded by the model via the `read` tool when the description matches).
```

Per-project skills live at `<repo>/.capo/skills/`.

## MCP

Capo speaks the [Model Context Protocol](https://modelcontextprotocol.io). Servers configured in `~/.capo/agent/mcp.toml` are connected at startup; their tools become available as `<server>__<tool>` (rendered as `<server>:<tool>` in the UI):

```toml
[servers.github]
transport = "stdio"
command = "github-mcp-server"
args = ["--scope", "read-only"]
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }
```

## Using `capo-agent` as a library

```rust
use capo_agent::{AppBuilder, Auth, Settings};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let agent_dir = capo_agent::agent_dir();
    let app = AppBuilder::new()
        .with_settings(Settings::load(&Default::default())?)
        .with_auth(Auth::load(&agent_dir)?)
        .with_builtin_tools()
        .build()
        .await?;

    let stream = app.send_user_message("list every .rs file in src/".into());
    use futures::StreamExt;
    futures::pin_mut!(stream);
    while let Some(_event) = stream.next().await { /* render UI events */ }
    Ok(())
}
```

See `crates/capo-agent/examples/list_rust_files.rs` for a runnable version.

## Architecture

Three crates, all under `crates/`:

- `capo-tui` — Elm-style MVU TUI runtime/rendering; consumes `capo-agent` UI event types.
- `capo-agent` — coding-agent SDK; built on `motosan-agent-loop`.
- `capo` — the binary you install.

Detailed design lives in `docs/superpowers/specs/2026-04-23-capo-design.md`.

## License

MIT — see [LICENSE](LICENSE).