Skip to content

Getting Started

Requirements

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

Installation

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

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

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

This installs three commands globally: attocode, attocodepy, and attoswarm. Re-run the same command to update after pulling new code.

Use this when you want attocode on PATH to run your local workspace directly:

uv tool install --force --editable --no-cache --from /absolute/path/to/attocode attocode

Example:

uv tool install --force --editable --no-cache --from /Users/eren/Documents/AI/first-principles-agent/attocode attocode

Note: this is a single command. If your terminal wraps lines, do not split the path.

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 semantic-nomic # Nomic embeddings (requires trust_remote_code)
Fallback: pip / pipx 
# Dev install
python -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"

# Global install with pipx (installs attocode, attocodepy, attoswarm)
pipx install --force .

API Key Setup

Set your API key as an environment variable:

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

Or configure it interactively:

attocode
# Then type: /setup

First Run

Interactive TUI

Launch the full terminal interface:

attocode

The TUI provides:

  • Live tool call status display
  • Keyboard shortcuts (see CLI Reference)
  • ~48 slash commands (/help to list them all)
  • Plan and task panels
  • Budget and context monitoring

Single-turn Mode

Ask a question and get one response:

attocode "List all Python files in this project"

Swarm Mode

Decompose a complex task across multiple parallel agents:

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

Configuration

Attocode reads configuration from a hierarchy of locations:

~/.attocode/              # User-level (global defaults)
  config.json
  rules.md
  skills/
  agents/

.attocode/                # Project-level (overrides user-level)
  config.json
  swarm.yaml
  rules.md
  skills/
  agents/

Priority: built-in defaults < ~/.attocode/ < .attocode/

Key config options (config.json)

{
  "model": "claude-sonnet-4-20250514",
  "provider": "anthropic",
  "max_tokens": 8192,
  "temperature": 0.0,
  "max_iterations": 25,
  "sandbox": { "mode": "auto" }
}

Initialize a project config directory:

attocode
# Then type: /init

Running from Anywhere

The attocode command always operates on the current working directory --- it reads .attocode/config.json from where you run it, so the install location doesn't matter.

uv tool install (recommended): Already on PATH after install --- attocode, attocodepy, and attoswarm all work from any directory. For editable local development installs, use:

uv tool install --force --editable --no-cache --from /absolute/path/to/attocode attocode

uv run (from the project directory):

cd /path/to/attocode
uv run attocode "your prompt"
Other options: shell alias, symlink **Shell alias:** Add to `~/.bashrc`, `~/.zshrc`, or `~/.config/fish/config.fish`: 
# bash / zsh
alias attocode="/absolute/path/to/attocode/.venv/bin/attocode"

# fish
alias attocode /absolute/path/to/attocode/.venv/bin/attocode

Next Steps