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

Features

• Interactive TUI --- Rich terminal interface with live tool status, streaming, plan/task panels, and keyboard shortcuts (powered by Textual)
• 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)

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

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

Global install (recommended for end users)

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

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

Optional provider extras

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:

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:

attocode "List all Python files in this project"

Interactive TUI --- launch the full terminal interface:

attocode

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

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

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

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

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

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

Swarm Command Chooser

Use these commands based on the scenario:

# 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

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/ 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.

cd lessons
npm install
npm run lesson:1

The lessons are also available on the documentation site.

Legacy TypeScript Version

The 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 for a detailed feature comparison.

Testing

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.

• Architecture --- Module relationships and data flow
• Providers --- LLM provider adapter reference
• Sandbox --- Platform-aware command isolation
• Budget --- Token economics and doom-loop detection
• MCP --- Model Context Protocol integration
• Swarm Guide --- Multi-agent orchestration
• Hybrid Swarm --- Start vs continue vs resume, monitor/detach flows, and runbook
• Research Campaigns --- Multi-experiment research workflows with dedicated worktrees
• Contributing --- How to contribute

License

See LICENSE for details.