Skip to content

legacy

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

legacy

README.md

Note: This is the archived TypeScript implementation of Attocode (v0.2.6). The active Python implementation is at the repository root. See the main README for the current project.

Attocode (TypeScript - Legacy)

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