Metadata-Version: 2.4
Name: attocode
Version: 0.2.18
Summary: Production AI coding agent
Project-URL: Homepage, https://github.com/eren23/attocode
Project-URL: Repository, https://github.com/eren23/attocode
Project-URL: Bug Tracker, https://github.com/eren23/attocode/issues
Project-URL: Changelog, https://github.com/eren23/attocode/blob/main/CHANGELOG.md
Author: eren23
License-Expression: LicenseRef-Attocode
License-File: LICENSE
Keywords: ai,cli,coding-agent,developer-tools,llm,mcp,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Code Generators
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: mcp>=1.0
Requires-Dist: numpy>=2.4.2
Requires-Dist: pathspec>=0.12.0
Requires-Dist: psutil>=6.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: structlog>=24.1
Requires-Dist: tenacity>=9.0
Requires-Dist: textual>=1.0.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: tomli-w>=1.0
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40; extra == 'anthropic'
Provides-Extra: code-intel
Requires-Dist: fastapi>=0.115; extra == 'code-intel'
Requires-Dist: networkx>=3.0; extra == 'code-intel'
Requires-Dist: python-multipart>=0.0.18; extra == 'code-intel'
Requires-Dist: uvicorn[standard]>=0.34; extra == 'code-intel'
Provides-Extra: dev
Requires-Dist: bcrypt>=4.0; extra == 'dev'
Requires-Dist: bump-my-version>=0.28; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.14; extra == 'dev'
Requires-Dist: pytest-textual-snapshot>=1.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: python-jose[cryptography]>=3.3; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: pymdown-extensions>=10.0; extra == 'docs'
Provides-Extra: full
Requires-Dist: anthropic>=0.40; extra == 'full'
Requires-Dist: fastapi>=0.115; extra == 'full'
Requires-Dist: networkx>=3.0; extra == 'full'
Requires-Dist: openai>=1.50; extra == 'full'
Requires-Dist: python-multipart>=0.0.18; extra == 'full'
Requires-Dist: sentence-transformers>=3.0; extra == 'full'
Requires-Dist: tree-sitter-bash; extra == 'full'
Requires-Dist: tree-sitter-c; extra == 'full'
Requires-Dist: tree-sitter-c-sharp; extra == 'full'
Requires-Dist: tree-sitter-cpp; extra == 'full'
Requires-Dist: tree-sitter-css; extra == 'full'
Requires-Dist: tree-sitter-elixir; extra == 'full'
Requires-Dist: tree-sitter-go; extra == 'full'
Requires-Dist: tree-sitter-hcl; extra == 'full'
Requires-Dist: tree-sitter-html; extra == 'full'
Requires-Dist: tree-sitter-java; extra == 'full'
Requires-Dist: tree-sitter-javascript; extra == 'full'
Requires-Dist: tree-sitter-json; extra == 'full'
Requires-Dist: tree-sitter-kotlin; extra == 'full'
Requires-Dist: tree-sitter-lua; extra == 'full'
Requires-Dist: tree-sitter-php; extra == 'full'
Requires-Dist: tree-sitter-python; extra == 'full'
Requires-Dist: tree-sitter-ruby; extra == 'full'
Requires-Dist: tree-sitter-rust; extra == 'full'
Requires-Dist: tree-sitter-scala; extra == 'full'
Requires-Dist: tree-sitter-swift; extra == 'full'
Requires-Dist: tree-sitter-toml; extra == 'full'
Requires-Dist: tree-sitter-yaml; extra == 'full'
Requires-Dist: tree-sitter-zig; extra == 'full'
Requires-Dist: tree-sitter>=0.23; extra == 'full'
Requires-Dist: uvicorn[standard]>=0.34; extra == 'full'
Requires-Dist: watchfiles>=1.0; extra == 'full'
Provides-Extra: graph
Requires-Dist: networkx>=3.0; extra == 'graph'
Provides-Extra: openai
Requires-Dist: openai>=1.50; extra == 'openai'
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=3.0; extra == 'semantic'
Provides-Extra: semantic-nomic
Requires-Dist: einops; extra == 'semantic-nomic'
Requires-Dist: sentence-transformers>=3.0; extra == 'semantic-nomic'
Provides-Extra: service
Requires-Dist: alembic>=1.14; extra == 'service'
Requires-Dist: arq>=0.26; extra == 'service'
Requires-Dist: asyncpg>=0.30; extra == 'service'
Requires-Dist: bcrypt>=4.0; extra == 'service'
Requires-Dist: cryptography>=41.0; extra == 'service'
Requires-Dist: fastapi>=0.115; extra == 'service'
Requires-Dist: httpx-oauth>=0.15; extra == 'service'
Requires-Dist: networkx>=3.0; extra == 'service'
Requires-Dist: pgvector>=0.3; extra == 'service'
Requires-Dist: pydantic-settings>=2.0; extra == 'service'
Requires-Dist: pygit2>=1.14; extra == 'service'
Requires-Dist: python-jose[cryptography]>=3.3; extra == 'service'
Requires-Dist: python-multipart>=0.0.18; extra == 'service'
Requires-Dist: redis[hiredis]>=5.0; extra == 'service'
Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'service'
Requires-Dist: uvicorn[standard]>=0.34; extra == 'service'
Provides-Extra: tree-sitter
Requires-Dist: tree-sitter-bash; extra == 'tree-sitter'
Requires-Dist: tree-sitter-c; extra == 'tree-sitter'
Requires-Dist: tree-sitter-c-sharp; extra == 'tree-sitter'
Requires-Dist: tree-sitter-cpp; extra == 'tree-sitter'
Requires-Dist: tree-sitter-css; extra == 'tree-sitter'
Requires-Dist: tree-sitter-elixir; extra == 'tree-sitter'
Requires-Dist: tree-sitter-go; extra == 'tree-sitter'
Requires-Dist: tree-sitter-hcl; extra == 'tree-sitter'
Requires-Dist: tree-sitter-html; extra == 'tree-sitter'
Requires-Dist: tree-sitter-java; extra == 'tree-sitter'
Requires-Dist: tree-sitter-javascript; extra == 'tree-sitter'
Requires-Dist: tree-sitter-json; extra == 'tree-sitter'
Requires-Dist: tree-sitter-kotlin; extra == 'tree-sitter'
Requires-Dist: tree-sitter-lua; extra == 'tree-sitter'
Requires-Dist: tree-sitter-php; extra == 'tree-sitter'
Requires-Dist: tree-sitter-python; extra == 'tree-sitter'
Requires-Dist: tree-sitter-ruby; extra == 'tree-sitter'
Requires-Dist: tree-sitter-rust; extra == 'tree-sitter'
Requires-Dist: tree-sitter-scala; extra == 'tree-sitter'
Requires-Dist: tree-sitter-swift; extra == 'tree-sitter'
Requires-Dist: tree-sitter-toml; extra == 'tree-sitter'
Requires-Dist: tree-sitter-yaml; extra == 'tree-sitter'
Requires-Dist: tree-sitter-zig; extra == 'tree-sitter'
Requires-Dist: tree-sitter>=0.23; extra == 'tree-sitter'
Provides-Extra: tree-sitter-all
Requires-Dist: tree-sitter-language-pack>=0.6; extra == 'tree-sitter-all'
Provides-Extra: watch
Requires-Dist: watchfiles>=1.0; extra == 'watch'
Description-Content-Type: text/markdown

# Attocode

Production AI coding agent built in Python. Features a Textual-based TUI, multi-agent swarm orchestration, intelligent budget management, and a safety sandbox system.

**[Documentation](https://eren23.github.io/attocode/)** | **[PyPI](https://pypi.org/project/attocode/)**

## Features

- **Interactive TUI** --- Rich terminal interface with live tool status, streaming, plan/task panels, and keyboard shortcuts (powered by [Textual](https://textual.textualize.io/))
- **Single-turn mode** --- Run one-shot prompts from the command line for scripting and automation
- **Swarm mode** --- Multi-agent orchestration with a standalone Python hybrid coordinator (`attoswarm`) and heterogeneous backends
- **Budget management** --- Token-based economics with doom-loop detection, phase tracking, and budget extension dialogs
- **Safety sandbox** --- Platform-aware command isolation (Seatbelt on macOS, Landlock on Linux, Docker, or allowlist fallback)
- **Session persistence** --- SQLite-backed sessions, checkpoints, goals, audit logs, and permission grants that persist across prompts
- **MCP support** --- Connect external tools via the Model Context Protocol
- **Multi-provider** --- Anthropic, OpenRouter, OpenAI, Azure, and ZAI adapters
- **Research campaigns** --- Multi-experiment research workflows with dedicated worktrees, hypothesis tracking, and persistent campaign state
- **Skills & agents** --- Extensible skill and agent system with project-level and user-level customization

## Requirements

- Python 3.12+
- An API key for at least one LLM provider (e.g. `ANTHROPIC_API_KEY`)

## Installation

### Development install (recommended)

```bash
git clone https://github.com/eren23/attocode.git
cd attocode

uv sync --all-extras          # creates .venv, installs everything
```

### Global install (recommended for end users)

```bash
cd attocode
uv tool install --force . --with anthropic --with openai
```

This installs three commands globally: `attocode`, `attocodepy`, and `attoswarm`.

### Optional provider extras

```bash
uv sync --extra anthropic     # Anthropic SDK (recommended)
uv sync --extra openai        # OpenAI SDK
uv sync --extra tree-sitter   # AST parsing for code analysis
uv sync --extra semantic      # Semantic search embeddings (sentence-transformers)
uv sync --extra dev           # Development tools (pytest, mypy, ruff)
uv sync --all-extras          # All of the above
```

Set your API key:

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
# Or for OpenRouter:
export OPENROUTER_API_KEY="sk-or-..."
```

## Quick Start

**Single-turn** --- ask a question and get one response:

```bash
attocode "List all Python files in this project"
```

**Interactive TUI** --- launch the full terminal interface:

```bash
attocode
```

**Swarm mode** --- decompose a task across multiple parallel agents:

```bash
attocode --swarm "Build a REST API for a todo app with tests"
```

**Hybrid swarm mode** --- process-boundary orchestration via `attoswarm`:

```bash
attocode swarm start .attocode/swarm.hybrid.yaml "Build a REST API for a todo app with tests"
```

**Research campaign** --- run structured multi-experiment research:

```bash
attocode research start "Evaluate caching strategies for the query layer"
```

## Swarm Command Chooser

Use these commands based on the scenario:

```bash
# New standalone swarm
attocode swarm start .attocode/swarm.hybrid.yaml "$(cat tasks/goal.md)"

# Follow-up / phase-2 swarm based on a previous swarm result
attocode swarm continue .agent/hybrid-swarm/demo-1 --config .attocode/swarm.hybrid.yaml "$(cat tasks/goal-phase2.md)"

# Resume the exact same run
attoswarm resume .agent/hybrid-swarm/demo-1

# Reattach the dashboard
attocode swarm monitor .agent/hybrid-swarm/demo-1
```

Important distinction:

- `start` = new standalone run
- `continue` = new child run from previous swarm output
- `resume` = same run dir, same persisted goal

Use `--tasks-file` only with structured decomposition files such as
`tasks.yaml` or `tasks.md`, not with high-level goal docs like `goal.md`.

## CLI Reference

| Flag | Short | Description |
|------|-------|-------------|
| `PROMPT` | | Positional --- run single-turn with this prompt |
| `--model` | `-m` | LLM model to use |
| `--provider` | | LLM provider (`anthropic`, `openrouter`, `openai`, `azure`, `zai`) |
| `--permission` | `-p` | Permission mode: `strict`, `interactive`, `auto-safe`, `yolo` |
| `--yolo` | | Shorthand for `--permission yolo` (auto-approve all) |
| `--task` | `-t` | Task description (alternative to positional prompt) |
| `--max-tokens` | | Maximum response tokens |
| `--temperature` | | LLM temperature (0.0--1.0) |
| `--max-iterations` | `-i` | Maximum agent iterations |
| `--timeout` | | Request timeout in seconds |
| `--resume` | | Resume a previous session by ID |
| `--tui` / `--no-tui` | | Force TUI or plain REPL mode |
| `--theme` | | TUI theme (`dark`, `light`, `auto`) |
| `--trace` | | Save JSONL execution traces to `.attocode/traces/` |
| `--swarm` | | Enable swarm mode (optional: path to config YAML) |
| `--swarm-resume` | | Resume a previous swarm session by ID |
| `--hybrid` | | Route swarm execution to standalone `attoswarm` orchestrator |
| `--paid-only` | | Only use paid models (no free tier) |
| `--record` | | Record session for visual replay |
| `--debug` | | Enable debug logging |
| `--non-interactive` | | Run in non-interactive mode |
| `--version` | | Show version and exit |

## Architecture

```
src/attocode/
  types/           Type definitions (messages, agent, config)
  agent/           Core agent orchestrator and builders
  core/            Execution loop, subagent spawner, tool executor
  providers/       LLM provider adapters (Anthropic, OpenRouter, OpenAI, Azure, ZAI)
  tools/           Built-in tool implementations (file ops, bash, search)
  integrations/    Feature modules organized by domain:
    budget/          Economics, budget pools, doom-loop detection
    context/         Context engineering, compaction, codebase analysis
    safety/          Policy engine, sandbox (seatbelt/landlock/docker)
    persistence/     SQLite session store, checkpoints, goals
    agents/          Shared blackboard, delegation protocol
    tasks/           Task decomposition, planning, verification
    skills/          Skill loading and execution
    mcp/             MCP client and tool integration
    quality/         Learning store, self-improvement, health checks
    utilities/       Hooks, rules, routing, logging, retry
    swarm/           Multi-agent orchestrator (20 modules, 10k+ lines)
    streaming/       Streaming and PTY shell
    lsp/             Language server protocol integration
  tricks/          Context engineering techniques
  tracing/         Trace collector, event types, cache boundary tracking
  tui/             Textual TUI (app, widgets, dialogs, bridges, styles)
```

## Lessons

The [`lessons/`](lessons/) directory contains a **26-lesson course** teaching you to build production-ready AI coding agents from scratch. The lessons use TypeScript and cover everything from the core agent loop to multi-agent coordination.

```bash
cd lessons
npm install
npm run lesson:1
```

The lessons are also available on the [documentation site](https://eren23.github.io/attocode/lessons/).

## Legacy TypeScript Version

The [`legacy/`](legacy/) directory contains the original TypeScript implementation of Attocode (v0.2.6). The Python version is the active implementation and has surpassed the TypeScript version in features. See [`legacy/PORTING_REPORT.md`](legacy/PORTING_REPORT.md) for a detailed feature comparison.

## Testing

```bash
uv run pytest tests/unit/ -x -q          # Quick unit tests
uv run pytest tests/ --cov=src/attocode  # With coverage
uv run ruff check src/ tests/            # Linting
```

## Documentation

Full documentation is available at **[eren23.github.io/attocode](https://eren23.github.io/attocode/)**.

- [Architecture](docs/ARCHITECTURE.md) --- Module relationships and data flow
- [Providers](docs/PROVIDERS.md) --- LLM provider adapter reference
- [Sandbox](docs/SANDBOX.md) --- Platform-aware command isolation
- [Budget](docs/BUDGET.md) --- Token economics and doom-loop detection
- [MCP](docs/MCP.md) --- Model Context Protocol integration
- [Swarm Guide](docs/swarm-guide.md) --- Multi-agent orchestration
- [Hybrid Swarm](docs/hybrid-swarm-operations.md) --- Start vs continue vs resume, monitor/detach flows, and runbook
- [Research Campaigns](docs/research-guide.md) --- Multi-experiment research workflows with dedicated worktrees
- [Contributing](CONTRIBUTING.md) --- How to contribute

## License

See [LICENSE](LICENSE) for details.
