Skip to content

Advanced Features

This guide covers Attocode's advanced capabilities: plan mode, task decomposition, conversation threading, subagent spawning, and permission modes.

Plan Mode

Plan mode switches the agent to a read-only state where file writes are intercepted and queued as proposed changes for your review before execution.

Entering Plan Mode

/plan                    # Switch to plan mode
/mode plan               # Same thing

Plan Workflow

flowchart LR
    Draft[Draft Plan] --> Discuss[Discuss / Refine]
    Discuss --> Approve["/approve"]
    Discuss --> Reject["/reject"]
    Approve --> Execute[Execute Steps]
    Execute --> Complete[Done]
    Reject --> Draft
  1. Draft — The agent generates a multi-step plan with dependency ordering
  2. Discuss — You review and provide feedback; the agent refines the plan
  3. Approve — Accept the plan with /approve
  4. Execute — The agent executes steps in dependency order
  5. Checkpoint — Progress is checkpointed between steps

Plan Commands

Command Description
/plan Enter plan mode
/show-plan Display the current plan
/approve Approve the current plan
/reject Reject the plan (with optional reason)

How Plans Work

Each plan step has:

  • A description of what to do
  • Dependencies on other steps (resolved automatically)
  • Estimated token budget
  • Status: pending → in_progress → completed/skipped/failed

Steps execute in dependency order — a step only starts when all its dependencies are completed or skipped.

Proposed Changes in Plan Mode

While in plan mode, any file write or edit the agent attempts is intercepted and queued:

/show-plan              # See queued changes

Each proposed change shows the tool name, file path, and arguments. You can approve or reject individual changes or in bulk.

Agent Modes

Attocode supports 4 operation modes that control what tools are available:

Mode Read Write Execute Agents Use Case
BUILD (default) Yes Yes Yes Yes Full implementation
PLAN Yes Intercepted No No Review changes before execution
REVIEW Yes No No No Code review, read-only analysis
DEBUG Yes No Tests only No Diagnosis with test execution

Switching Modes

/mode build     # Full access (default)
/mode plan      # Read-only with change proposals
/mode review    # Pure read-only
/mode debug     # Read + test commands

DEBUG Mode Test Whitelist

In debug mode, only test-related commands are allowed:

pytest, python -m pytest, npm test, npx jest,
cargo test, go test, make test, mypy, ruff check,
tsc --noEmit, eslint

Task Decomposition

Attocode can automatically break complex tasks into sub-tasks with dependency tracking.

Complexity Classification

Tasks are classified into 4 tiers based on weighted heuristic scoring:

Tier Score Range Description
SIMPLE < 0.5 Single-step, straightforward
MEDIUM 0.5–1.5 Multi-step, moderate complexity
COMPLEX 1.5–2.5 Significant planning needed
DEEP_RESEARCH > 2.5 Extensive exploration and multi-file changes

Scoring signals include task length, presence of complex keywords (refactor, migrate, architect), dependency patterns ("first...then"), scope indicators (file paths), and whether it's a question vs. action.

Automatic Decomposition

/auto "Build a REST API with authentication, tests, and documentation"

The decomposer:

  1. Classifies complexity
  2. Splits into subtasks with dependencies
  3. Creates a TaskManager DAG
  4. Executes tasks in dependency order

Task Management

/goals               # List active goals
/goals add "..."     # Add a goal
/goals done 1        # Mark goal complete

Tasks track 6 states: pending → blocked → in_progress → completed/failed/skipped

Blocked tasks automatically unblock when their dependencies complete.

Thread Forking

Create branching conversation threads to explore alternative approaches without losing your current work.

Creating a Fork

/fork                              # Fork at current point
/fork "Alternative approach"       # Fork with label

A fork copies the conversation history up to the current point into a new thread. The original thread remains unchanged.

Thread Management

Command Description
/fork [label] Create a new thread branch
/threads List all threads
/switch <thread-id> Switch to a different thread
/rollback Roll back to the fork point
/restore Restore from a previous state

Thread Tree

Threads form a hierarchy:

main
├── fork-a1b2c3d4 "Try React approach"
│   └── fork-e5f6g7h8 "With TypeScript"
└── fork-i9j0k1l2 "Try Vue approach"

You can switch between any thread at any time. Each thread maintains independent message history.

Subagent Spawning

Delegate sub-tasks to independent agent instances that run with their own budget and context.

Manual Spawning

/spawn "Analyze the test coverage in src/auth/"
/spawn --model gpt-5-mini "Find all API endpoint handlers"

How Subagents Work

  1. Budget allocation — Subagent receives 15% of parent's remaining tokens (clamped to 50K–200K)
  2. Independent context — Subagent starts fresh with its own message history
  3. Tool access — Inherits parent's tool registry and permissions
  4. Timeout — Hard timeout with a 30-second wrapup warning before termination
  5. Closure report — Returns a structured summary of findings, files modified, and remaining work

Budget Allocation

Parameter Default Description
fraction 0.15 15% of parent's remaining tokens
min_tokens 50,000 Minimum allocation
max_tokens 200,000 Maximum allocation
max_iterations 30 Iteration limit
max_duration_seconds 300 5-minute timeout

Graceful Shutdown

When a subagent approaches its timeout:

  1. Wrapup warning fires 30 seconds before the hard timeout
  2. Agent receives a signal to begin wrapping up
  3. Agent produces a closure report with summary, files modified, decisions made, and remaining work
  4. If the agent doesn't finish, it's terminated and results are collected

Closure Report Format

## Summary
What was accomplished

## Files Modified
- path/to/file1.py
- path/to/file2.py

## Key Decisions
- Chose approach X over Y because...

## Remaining Work
- Still need to implement Z

## Confidence: 0.85

Permission Modes

Control how aggressively the agent can act without your approval.

The 4 Modes

Mode Safe Tools Moderate Tools Dangerous Tools Use Case
strict Prompt Prompt Prompt Maximum safety
interactive (default) Auto-allow Prompt Prompt Balanced
auto-safe Auto-allow Auto-allow Deny Unattended execution
yolo Auto-allow Auto-allow Auto-allow Full autonomy

Setting Permission Mode

# Via CLI flag
attocode --permission strict
attocode --permission interactive
attocode --permission auto-safe
attocode --yolo                    # Shorthand for --permission yolo

# Via config
# .attocode/config.json
{
  "permission_mode": "interactive"
}

Tool Danger Classification

Level Tools Description
SAFE read_file, glob, grep, list_files, codebase_overview Read-only operations
LOW write_file, edit_file, spawn_agent File modifications, delegation
MEDIUM bash Shell command execution
HIGH Destructive operations rm, git push --force, etc.

Session-Scoped Permissions

When prompted for approval, press A to "Always Allow" a tool for the rest of the session. These grants are stored in the remembered_permissions table with fnmatch pattern matching.

Bash Danger Classification

Attocode classifies every bash command by risk level before execution, using the policy engine in integrations/safety/bash_policy.py.

Risk Levels

Risk Behavior Examples
SAFE Auto-allowed in interactive+ modes ls, cat, grep, git log, pwd, echo
WARN Requires approval in interactive/strict rm, sudo, chmod, git push, npm publish
BLOCK Always blocked rm -rf /, mkfs.*, dd if=...of=/dev/, curl \| bash

Classification Algorithm

Commands are checked in order (first match wins):

  1. Safe exact matches — 26 read-only commands (ls, cat, head, tail, wc, echo, pwd, which, git log, etc.)
  2. Safe prefixes — Read-only command prefixes (ls, cat, grep, git log, git diff, python -c, etc.)
  3. Blocked patterns — 12 regex patterns for destructive commands:
    • rm -rf / (recursive delete from root)
    • mkfs. (format filesystem)
    • dd if=.+of=/dev/ (write to raw device)
    • :> / (truncate system files)
    • curl | bash, wget | bash (remote code execution)
    • sudo rm, sudo chmod (privileged destructive ops)
  4. Warn patterns — 9 regex patterns for potentially risky commands:
    • \brm\b, \bsudo\b, \bchmod\b
    • \bgit\s+push, \bgit\s+reset, \bgit\s+checkout, \bgit\s+clean
    • \bnpm\s+publish
  5. Default — Unknown commands default to WARN (safe-by-default with review)

The permission mode then determines whether the classified risk level requires user approval:

Permission Mode SAFE WARN BLOCK
strict Prompt Prompt Denied
interactive Auto-allow Prompt Denied
auto-safe Auto-allow Auto-allow Denied
yolo Auto-allow Auto-allow Auto-allow

Quality Gate System

The swarm's quality gate evaluates worker outputs through multiple stages before accepting them.

Pre-Flight Checks (No LLM)

Four fast synchronous checks that catch obvious failures:

Check Trigger Result
V4 All target files empty or missing Auto-fail, score=1
V7 Task requires tool calls but got zero Auto-fail, score=0, rejected
V10 No files modified + no tool calls + task implies creation Auto-fail, score=1
V6 Closure report is all budget excuses Auto-fail, score=1

Concrete Filesystem Checks

For each modified file:

  • Existence check — File exists and is non-empty
  • JSON validation — json.load() for .json files
  • Brace balance — For .ts, .tsx, .js, .jsx, .py files (allows 3-char imbalance for template strings)

AST Checks

If an AST service is available, modified files are re-parsed to verify that symbols still exist after modification.

LLM Judge Evaluation

The final stage uses an LLM to score the output on a 1–5 scale:

Score Meaning
1 Failed — No useful output
2 Poor — Partial, significant issues
3 Acceptable — Works but has gaps
4 Good — Solid implementation
5 Excellent — Complete and well-tested

The judge call uses temperature=0.1 and max_tokens=800. On LLM error, the gate returns a neutral score of 3 with gate_error=True.

Artifact Detection

The quality gate identifies output artifacts from three sources:

  1. Explicit targets — task.target_files
  2. Modified files — task_result.files_modified
  3. Text mining — Regex extraction of file paths from output text (patterns like ./foo.ts, src/thing.py, /abs/path.js)

Learning & Self-Improvement

Attocode can learn from its mistakes and successes across sessions using the learning store and self-improvement protocol.

Learning Types

Type Description
PATTERN Recurring solution pattern
WORKAROUND Known workaround for a specific issue
ANTIPATTERN Approach that consistently fails
BEST_PRACTICE Validated effective technique
GOTCHA Subtle pitfall to watch for

Learning Lifecycle

flowchart LR
    P[PROPOSED] --> V{Validation}
    V -->|Approved| VA[VALIDATED]
    V -->|Rejected| R[REJECTED]
    VA --> A[ARCHIVED]
    R --> A

Each learning goes through:

  1. Proposed — Agent detects a pattern and proposes a learning
  2. Validated — User approves via the TUI validation dialog (Y/N/S shortcuts)
  3. Applied — Learning is injected into future prompts when relevant

Learnings with confidence ≥ 0.9 are auto-validated (configurable via auto_validate_threshold).

Confidence Tracking

Each learning has a confidence score (0.0–1.0):

  • Initial: Set by the proposer based on evidence strength
  • Boosted: +0.05 each time the learning is marked as helpful (capped at 1.0)
  • Used for: Eviction priority (low-confidence learnings evicted first), display ordering, auto-validation threshold

Retrieval

Learnings are stored in SQLite with FTS5 (Full-Text Search) for fast retrieval:

# Find relevant learnings for a task
context = learning_store.get_learning_context(
    query="authentication middleware",
    categories=["security"],
    max_learnings=5,
)

The retrieval pipeline:

  1. FTS5 search on description, details, keywords, and actions
  2. Fallback to LIKE queries if FTS returns nothing
  3. Category and action filtering
  4. Deduplicate by learning ID
  5. Sort by confidence (descending)
  6. Format as Markdown for LLM injection

Self-Improvement Protocol

The SelfImprovementProtocol provides immediate feedback on tool failures:

  • Failure diagnosis — Pattern-matches error messages against 8 known categories (FILE_NOT_FOUND, PERMISSION, TIMEOUT, SYNTAX_ERROR, etc.) and generates actionable fix suggestions
  • Success patterns — Records working argument signatures ({arg_name: type_name}) for each tool
  • Repeat detection — Warns after 3+ failures on the same tool: "This tool has failed 3 times. Consider a different approach."
  • Enhanced errors — Appends diagnosis and fix suggestion to error messages before showing them to the agent

Eviction Policy

The learning store is capped at 500 learnings (configurable). When the limit is exceeded:

  1. First: Delete REJECTED and ARCHIVED learnings (oldest first)
  2. Then: Delete VALIDATED learnings (lowest confidence first, then oldest)

Permission Mailbox (Swarm)

In swarm mode, worker agents can request permission for dangerous operations. The coordinator evaluates requests using a three-tier policy:

  1. Auto-approve: Read-only tools (grep, read_file, ast_query, etc.)
  2. Auto-deny: Destructive tools (delete_file, drop_table, rm_rf)
  3. Role-based: Workers with write_access=True can use write tools; others are rejected

Permission requests/responses flow through the agent inbox/outbox protocol.

Circuit Breaker & Exponential Backoff

Circuit Breaker

The HealthMonitor tracks per-model failure rates. When a model accumulates 3+ failures within 60 seconds, the circuit breaker trips and prevents new dispatches to that model until it recovers naturally (5% health per 60s idle).

Exponential Backoff

Failed tasks retry with exponential backoff: delay = min(2^attempt, 60s) + random_jitter. Retries are non-blocking — scheduled via asyncio.create_task() so the coordinator loop continues.