# iEvo CLI

Self-evolving AI agent framework CLI tool.

## Project

- **Name**: ievo-cli
- **Language**: Python 3.13+
- **Framework**: Typer + Rich + Textual (TUI)
- **Package manager**: uv (hatchling build)
- **Entry point**: `ievo` → TUI dashboard | `ievo <cmd>` → CLI

## Architecture

```
src/ievo/
├── cli.py              # Typer app, registers all commands
├── commands/           # One file per command group
│   ├── init.py         # ievo init — project scaffold
│   ├── add.py          # ievo add — install from marketplace
│   ├── remove.py       # ievo remove
│   ├── update.py       # ievo update
│   ├── list_cmd.py     # ievo list
│   ├── run.py          # ievo run — launches Claude session
│   ├── team.py         # ievo team (Phase 2)
│   ├── learn.py        # ievo learn log/push/status — EVO
│   └── dev.py          # ievo dev new/test/publish
├── core/               # Business logic
│   ├── config.py       # Paths, URLs, project root detection
│   ├── project.py      # ievo.yaml manifest model
│   ├── agent.py        # agent.yaml model (AgentPackage, SandboxConfig)
│   ├── docker.py       # Docker sandbox (check, build, command builder)
│   └── registry.py     # Marketplace registry (fetch, cache, download)
├── tui/                # Textual TUI dashboard
│   └── app.py          # IevoApp: agents table, pipeline, evo log, file tree
└── utils/
    └── console.py      # Rich theme, success/error/info helpers
```

## Key patterns

- **Project detection**: `find_project_root()` walks up looking for `ievo.yaml`
- **Registry**: cached at `~/.ievo/cache/registry.yaml`, fetched from GitHub raw
- **Agent install**: downloads from marketplace or creates local scaffold
- **Run**: Docker sandbox by default, `--local` for direct Claude CLI. Builds command with ROLE.md as system prompt + memory files + `--allowedTools`
- **Docker sandbox**: agents run in `ievoai/sandbox:latest` container with project as volume mount. Tool-level isolation via `--allowedTools` (not `--network none` — Claude needs API access). Auto-builds image if missing
- **TUI**: `ievo` without args launches Textual dashboard (4 tabs: Agents, Pipeline, Evolution, Files)
- **Async**: registry fetch/download use httpx async

## Commands reference

```bash
# Project lifecycle
ievo init [name]                    # Create ievo.yaml, spec/, plans/, agents/
ievo add <agent> [agent...]         # Pull from marketplace + resolve deps
ievo remove <agent> [--force]       # Remove agent (checks dependents)
ievo update [agent]                 # Update to latest marketplace version
ievo list [--marketplace]           # Show installed or available agents

# Running
ievo run <agent> [-m msg] [-p file] [--model opus|sonnet|haiku] [--local]
ievo team <agents...>               # Phase 2

# Evolution
ievo learn log <agent> [--last N]   # Show EVOLUTION_LOG.md
ievo learn push [agent]             # Send anonymized logs (opt-in)
ievo learn status [agent]           # Evolution stats

# Development
ievo dev new <name>                 # Scaffold agent locally
ievo dev test <agent>               # Run eval suite (Phase 2)
ievo dev publish <agent>            # Publish to marketplace (Phase 2)
```

## Dependencies

- typer — CLI framework
- rich — terminal formatting
- textual — TUI dashboard (from Rich creators)
- pyyaml — YAML parsing (ievo.yaml, agent.yaml, registry.yaml)
- httpx — async HTTP for marketplace registry
- pydantic — data validation (future use)

## Related repos

- [ievo-ai/ievo.ai](https://github.com/ievo-ai/ievo.ai) — landing page
- ievo-ai/marketplace — agent registry (planned)
- ievo-ai/sdk — dev template (planned)

## Conventions

- Use `from ievo.utils.console import success, error, info, warn, step` for output
- All commands are separate files in `commands/`
- Async operations (network) use `asyncio.run()` at command level
- Project root required: use `require_project()` which exits with error if no ievo.yaml
