autocontext: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

autocontext is an iterative strategy generation and evaluation system. It runs a multi-agent loop where LLM agents collaboratively evolve strategies for pluggable scenarios, scoring them through tournament matches (game scenarios) or LLM judge evaluation (agent task scenarios) with Elo-based progression gating.

Repository Layout

The Python package lives under autocontext/ (not the repo root). All uv, pytest, and autoctx CLI commands must be run from the autocontext/ directory.

autocontext/                  # Python package root (pyproject.toml lives here)
  src/autocontext/            # Source code
    agents/                   # LLM agent roles (competitor, analyst, coach, architect, curator)
    knowledge/                # Knowledge processing (trajectory builder, skill export, search, solve-on-demand)
    loop/                     # Generation runner, event emitter, stage decomposition helpers (stage_helpers/)
    prompts/                  # Prompt template assembly
    config/                   # Pydantic settings from AUTOCONTEXT_* env vars
    storage/                  # SQLiteStore, ArtifactStore, split across sqlite_store_*/artifact_* mixin modules
    scenarios/                # Pluggable scenarios (grid_ctf, othello, custom/, agent tasks)
      custom/               # Natural-language → generated scenario pipeline (spec, codegen, validation, loading)
                            # Also: agent task pipeline (agent_task_designer, agent_task_codegen, agent_task_validator, agent_task_creator)
    execution/                # Execution supervisor, local/remote executors, LLM judge, task runner daemon
    providers/                # Multi-model LLM provider abstraction (Anthropic, OpenAI-compat, callable wrapper)
    notifications/            # Notification webhooks (Slack, HTTP, stdout, callback, composite)
    runtimes/                 # Agent runtime abstraction (Claude CLI, direct API)
    rlm/                      # REPL-loop mode (optional analyst/architect)
    mcp/                      # MCP server, tool implementations, sandbox manager
    server/                   # FastAPI dashboard + WebSocket events
  tests/                      # Pytest tests (~7700 tests)
  migrations/                 # SQLite migration SQL files (001-007, applied in filename order)
  dashboard/                  # Single-page HTML dashboard
  knowledge/                  # Runtime-generated: per-scenario playbooks, analysis, tools, hints, snapshots
  skills/                     # Runtime-generated: operational skill notes per scenario
  runs/                       # Runtime-generated: SQLite DB, event stream, generation artifacts
ts/                           # TypeScript package (autoctx on npm)
  src/                        # Source code
    scenarios/                # Scenario families, codegen, templates, materialization
      codegen/                # V8 isolate code generation for all 11 families (AC-436)
      templates/              # Pre-built scenario templates (AC-443)
    simulation/               # SimulationEngine: run, replay, compare, export, sweep DSL (AC-446)
    investigation/            # InvestigationEngine: evidence-driven diagnosis (AC-447)
    analysis/                 # AnalysisEngine: interpret and compare artifacts (AC-448)
    mission/                  # MissionManager, planner, adaptive executor, campaigns (AC-410, AC-435, AC-428)
    traces/                   # Public trace schema, redaction, export, publishers, data plane (AC-462–466)
    training/                 # Model strategy, backends (MLX/CUDA), prompt alignment, promotion (AC-456–460)
    domain/                   # Branded id types (RunId, ScenarioName, DbPath; AC-855), root-exported
    server/                   # InteractiveServer: WebSocket protocol + HTTP routing
      routes/                 # Extracted HTTP route handlers (12 modules; AC-852)
    mcp/                      # MCP server with tool implementations
    cli/                      # CLI entry point; command-handlers.ts barrel over commands/ (15 family modules; AC-853)
  tests/                      # Vitest tests (5000+ tests)
  migrations/                 # Shared SQLite migration SQL (cross-compatible with Python)
pi/                           # Pi coding agent extension (@autocontext/pi)
  src/                        # Extension with 5 tools (judge, improve, status, scenarios, queue)
  skills/                     # Autocontext skill for Pi
  prompts/                    # Prompt templates for Pi
infra/                        # Docker, Fly.io config, bootstrap script
scripts/                      # Top-level convenience scripts (demo.sh)
.claude/                      # Claude context, implementation plans, synced skill symlinks