attocode

v0.2.6

Published

3 days ago

Production AI coding agent for your terminal - multi-provider support, context management, MCP integration

0High
0Medium
0Low

ai agent llm coding-assistant claude anthropic openai gpt terminal cli mcp model-context-protocol developer-tools code-generation attocode

Attocode

A production-ready AI coding agent for your terminal.

Features

Multi-provider support - Anthropic, OpenRouter, OpenAI
Memory system - Remembers context across sessions
Planning & Reflection - Breaks down complex tasks
File change tracking - Full undo capability
Context compaction - Never runs out of context in long sessions
Session persistence - Resume where you left off
Sandbox execution - Safe command execution
MCP integration - Connect external tools

Quick Start

1. Install

From npm (recommended):

npm install -g attocode

Or build from source:

git clone https://github.com/eren23/attocode.git
cd attocode
npm install
npm run build
npm link

Now attocode is available everywhere in your terminal.

2. Set up your API key

# Option A: Anthropic (recommended)
export ANTHROPIC_API_KEY="sk-ant-..."

# Option B: OpenRouter (100+ models)
export OPENROUTER_API_KEY="sk-or-..."

# Option C: OpenAI
export OPENAI_API_KEY="sk-..."

Add to your ~/.bashrc or ~/.zshrc to persist.

3. Run the setup wizard

attocode init

This creates your config at ~/.config/attocode/config.json.

4. Start coding

attocode

Usage

Interactive mode (default)

attocode

Single task

attocode "List all TypeScript files and explain the project structure"

With specific model

attocode -m anthropic/claude-opus-4 "Review this code for security issues"

Commands

Once in the REPL:

| Command | Description | |---------|-------------| | /help | Show all commands | | /status | Show session metrics | | /checkpoint | Save current state | | /restore | Restore a checkpoint | | /undo | Undo last file change | | /history | Show file change history | | /compact | Compact context (for long sessions) | | /save | Save session | | /load | Load a previous session | | /exit | Exit attocode |

Skills & Agents

Extend attocode with custom skills and agents:

# Initialize project directory
/init

# Create a custom skill
/skills new code-review

# Create a custom agent
/agents new domain-expert

# List available skills/agents
/skills
/agents

# Spawn an agent
/spawn researcher "Find all API endpoints"

Directory structure:

.attocode/              # Project-level
├── skills/             # Custom skills
└── agents/             # Custom agents

~/.attocode/            # User-level (shared across projects)
├── skills/
└── agents/

See docs/skills-and-agents-guide.md for the complete guide.

MCP Servers

Connect external tools via the Model Context Protocol.

Configuration Files

MCP servers are configured in JSON files. Attocode loads configs in order (later overrides earlier):

| Location | Scope | Priority | |----------|-------|----------| | ~/.config/attocode/mcp.json | User-level (all projects) | Lower | | .mcp.json | Project-level (this project) | Higher |

Setup

1. Create a config file:

# User-level (shared across all projects)
mkdir -p ~/.config/attocode
touch ~/.config/attocode/mcp.json

# Or project-level (this project only)
touch .mcp.json

2. Add server configurations:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "/path/to/allowed/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-sqlite", "~/database.db"]
    }
  }
}

3. Verify with commands:

/mcp              # List connected servers
/mcp tools        # List available MCP tools
/mcp search <q>   # Search and load tools

Environment Variables

Use ${VAR_NAME} syntax to reference environment variables in configs:

{
  "servers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Popular MCP Servers

| Server | Package | Description | |--------|---------|-------------| | Filesystem | @anthropic/mcp-server-filesystem | Read/write files in allowed directories | | GitHub | @anthropic/mcp-server-github | GitHub API integration | | SQLite | @anthropic/mcp-server-sqlite | Query SQLite databases | | Postgres | @anthropic/mcp-server-postgres | Query PostgreSQL databases | | Brave Search | @anthropic/mcp-server-brave-search | Web search via Brave | | Puppeteer | @anthropic/mcp-server-puppeteer | Browser automation |

Find more at MCP Servers Directory.

Configuration

Config file: ~/.config/attocode/config.json

{
  "providers": {
    "default": "openrouter"
  },
  "model": "anthropic/claude-sonnet-4",
  "maxIterations": 50,
  "timeout": 300000,
  "memory": { "enabled": true },
  "planning": { "enabled": true },
  "sandbox": { "enabled": true },
  "resilience": {
    "incompleteActionAutoLoop": true,
    "maxIncompleteAutoLoops": 2,
    "autoLoopPromptStyle": "strict",
    "taskLeaseStaleMs": 300000
  },
  "hooks": {
    "enabled": true,
    "shell": {
      "enabled": false,
      "defaultTimeoutMs": 5000,
      "envAllowlist": ["SLACK_WEBHOOK_URL"],
      "commands": [
        {
          "id": "notify-on-complete",
          "event": "run.after",
          "command": "node",
          "args": ["./scripts/hook-notify.js"],
          "timeoutMs": 3000
        }
      ]
    }
  }
}

Behavior Tuning (Incomplete Recovery)

These settings control what happens when the model replies with "I'll do X" but has not executed the action yet:

resilience.incompleteActionAutoLoop: Automatically retry incomplete runs in TUI.
resilience.maxIncompleteAutoLoops: Maximum retry runs before terminal [INCOMPLETE].
resilience.autoLoopPromptStyle: Guidance style for retries (strict or concise).
resilience.taskLeaseStaleMs: Requeue stale in_progress tasks to pending at run boundaries.

For swarm runs, resilience.dispatchLeaseStaleMs in swarm config controls stale dispatched task recovery back to ready.

Branch Change Highlights

Added bounded incomplete-action recovery (future_intent / incomplete_action) in TUI.
Added run-boundary stale task lease recovery in core task manager.
Added stale dispatched-task recovery in swarm queue/orchestrator.
Added lifecycle shell-hook coverage for completion/recovery/run phases.

Lifecycle Hooks (Trigger External Automations)

You can trigger scripts on lifecycle events (for notifications, logging, CI checks, policy alerts).

Common lifecycle events:

run.before, run.after
iteration.before, iteration.after
completion.before, completion.after
recovery.before, recovery.after
llm.before, llm.after
tool.before, tool.after

Shell hooks receive JSON on stdin:

{
  "event": "run.after",
  "payload": { "...": "event-specific data" }
}

File Locations (XDG compliant)

| Purpose | Location | |---------|----------| | Config | ~/.config/attocode/config.json | | Sessions DB | ~/.local/share/attocode/sessions.db | | History | ~/.local/state/attocode/history | | Cache | ~/.cache/attocode/ |

CLI Options

attocode [COMMAND] [OPTIONS] [TASK]

Commands:
  init                    Interactive setup wizard

Options:
  -h, --help              Show help
  -v, --version           Show version
  -m, --model MODEL       Model to use (e.g., anthropic/claude-sonnet-4)
  -p, --permission MODE   Permission mode: strict, interactive, auto-safe, yolo
  -i, --max-iterations N  Max agent iterations (default: 50)
  -t, --task TASK         Run single task non-interactively
  --tui                   Force TUI mode
  --legacy                Force legacy readline mode
  --trace                 Enable trace capture to .traces/
  --debug                 Enable debug logging
  --swarm [CONFIG]        Enable swarm mode (optional config path)
  --swarm-resume ID       Resume a previous swarm session
  --paid-only             Use only paid models in swarm auto-detection
  --theme THEME           UI theme: dark, light, auto
  --yolo                  Shorthand for --permission yolo

Tracing & Performance Analysis

Attocode includes comprehensive tracing capabilities for understanding agent behavior, debugging issues, and optimizing performance.

Quick Start

# Enable tracing when starting attocode
attocode --trace

# View trace summary after running commands
/trace

# Analyze efficiency issues
/trace --analyze

Trace Commands

| Command | Description | |---------|-------------| | /trace | Show current session trace summary | | /trace --analyze | Run efficiency analysis on trace | | /trace issues | List detected inefficiencies | | /trace fixes | List pending improvements | | /trace export [file] | Export trace JSON for LLM analysis |

Trace Viewer CLI

For detailed offline analysis, use the trace-viewer tool:

# Navigate to the trace viewer
cd tools/trace-viewer

# Build (first time)
npm install && npm run build

# View trace summary
npx tsx bin/trace-viewer.ts .traces/

# Timeline view
npx tsx bin/trace-viewer.ts .traces/ --view timeline

# Token flow analysis
npx tsx bin/trace-viewer.ts .traces/ --view tokens

# Generate HTML report
npx tsx bin/trace-viewer.ts .traces/ --output html

# Compare two sessions
npx tsx bin/trace-viewer.ts compare <baseline.jsonl> <comparison.jsonl>

See docs/tracing-guide.md for the complete tracing documentation.

Architecture

Attocode follows a modular architecture:

┌─────────────────────────────────────────────────────┐
│                    Entry Point                       │
│                 src/main.ts (CLI + TUI)              │
└─────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────┐
│                  ProductionAgent                     │
│  ┌─────────────┐ ┌─────────────┐ ┌───────────────┐  │
│  │   Hooks     │ │   Memory    │ │   Planning    │  │
│  └─────────────┘ └─────────────┘ └───────────────┘  │
│  ┌─────────────┐ ┌─────────────┐ ┌───────────────┐  │
│  │   Safety    │ │  Economics  │ │Context Engine │  │
│  └─────────────┘ └─────────────┘ └───────────────┘  │
└─────────────────────────────────────────────────────┘
        │                  │                  │
        ▼                  ▼                  ▼
┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│ LLM Providers│   │ Tool Registry│   │ Integrations │
│ - Anthropic  │   │ - File Ops   │   │ - Sessions   │
│ - OpenRouter │   │ - Bash       │   │ - MCP Client │
│ - OpenAI     │   │ - Search     │   │ - Compaction │
└──────────────┘   └──────────────┘   └──────────────┘

See docs/architecture.md for the complete architecture documentation.

Documentation

| Document | Description | |----------|-------------| | Architecture | System design and data flow | | API Reference | Core interfaces and types | | Extending | Adding providers, tools, integrations | | Skills & Agents | Custom skills and agents | | Tracing | Performance analysis | | Modes Guide | TUI, REPL, plan, subagent, and swarm modes | | Swarm Mode | Multi-model parallel orchestration | | Troubleshooting | Common issues and solutions |

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Uninstall

# If installed from npm
npm uninstall -g attocode

# If installed from source
npm unlink -g attocode

# Remove config and data (optional)
rm -rf ~/.config/attocode
rm -rf ~/.local/share/attocode
rm -rf ~/.local/state/attocode
rm -rf ~/.cache/attocode

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Attocode

Features

Quick Start

1. Install

2. Set up your API key

3. Run the setup wizard

4. Start coding

Usage

Interactive mode (default)

Single task

With specific model

Commands

Skills & Agents

MCP Servers

Configuration Files

Setup

Environment Variables

Popular MCP Servers

Configuration

Behavior Tuning (Incomplete Recovery)

Branch Change Highlights

Lifecycle Hooks (Trigger External Automations)

File Locations (XDG compliant)

CLI Options

Tracing & Performance Analysis

Quick Start

Trace Commands

Trace Viewer CLI

Architecture

Documentation

Contributing

Uninstall