Anvil

Prerequisites

Setup

# Install uv (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies (creates .venv/ automatically)
uv sync

# Create .env file with your API keys
echo "OPENAI_API_KEY=sk-..." > .env

OPENAI_API_KEY=sk-...              # for gpt-4o, gpt-4
ANTHROPIC_API_KEY=sk-ant-...       # for Claude models
GEMINI_API_KEY=...                 # for Gemini models

Optional: Web Search (Deep Research)

uv sync --extra search
export TAVILY_API_KEY="tvly-..."

GUI

# Install gradio
uv sync --extra gui

# Launch
uv run anvil gui                    # Default port 7860
uv run anvil gui --port 8080        # Custom port
uv run anvil gui --share            # Public link (Gradio hosting)

CLI

# Interactive agent (default model = gpt-4o)
uv run anvil

# Interactive agent with model aliases
uv run anvil repl --model sonnet
uv run anvil repl --model opus
uv run anvil repl --model flash
uv run anvil repl --model deepseek

# Use full model names
uv run anvil repl --model claude-sonnet-4-20250514
uv run anvil repl --model gemini/gemini-2.5-flash

# With files pre-loaded
uv run anvil repl src/anvil/cli.py

# With initial message
uv run anvil repl -m "Add error handling to the main function"

# Fetch raw documents (Scout sources; fetch-only)
uv sync --extra fetch
uv run anvil fetch "AI note taking" --source producthunt --max-documents 50

# Resume fetch (uses `data/sessions/<id>/state.json`)
uv run anvil fetch --resume <session_id>

# Web research (orchestrator-workers; requires Tavily)
uv sync --extra search
export TAVILY_API_KEY="tvly-..."
uv run anvil research "competitive analysis of AI coding agents"

# Research profiles
uv run anvil research --profile quick "competitive analysis of AI coding agents"   # default
uv run anvil research --profile deep "competitive analysis of AI coding agents"    # ~15–20m, includes round-2 gap fill

Reference: `docs/DEEP_RESEARCH_SYSTEM_REFERENCE.md` explains what “Deep Research” systems do (and what’s still needed to reach Anthropic/ChatGPT-level behavior).

    # Saved artifacts (default)
    # - `data/sessions/<session_id>/meta.json`
    # - `data/sessions/<session_id>/research/report.md`
    # - `data/sessions/<session_id>/research/report.json` (structured)
    # Flags: --profile, --session-id, --data-dir, --output, --no-save-artifacts, --min-citations, --min-domains,
    #        --target-web-search-calls, --max-web-search-calls, --max-web-extract-calls, --verify-max-tasks, --best-effort

# Resume research (reruns failed workers; fails unless all succeed)
uv run anvil research --resume <session_id>

# Sessions (list/show/open)
uv run anvil sessions list
uv run anvil sessions list --kind research
uv run anvil sessions open <session_id>

# Options
uv run anvil --help
uv run anvil repl --no-lint        # Disable auto-linting
uv run anvil repl --no-auto-commit # Disable auto-commit
uv run anvil repl --dry-run        # Preview changes without applying

Commands (inside the agent)

Supported Models

Features

Development

# Install with dev dependencies
uv sync --extra dev

# Run tests (runs inside .venv)
uv run pytest

# Run tests verbose
uv run pytest -v

# Activate venv manually (optional, for IDE integration)
source .venv/bin/activate

Project Structure

src/
├── anvil/          # AI coding agent
│   ├── cli.py          # Entry point
│   ├── config.py       # Configuration + model aliases
│   ├── linter.py       # Python linter
│   ├── tools/          # Tool registry
│   ├── git.py          # Git operations
│   ├── files.py        # File operations
│   ├── shell.py        # Shell commands
│   ├── parser.py       # Response parsing
│   └── history.py      # Message history
│
├── scout/          # Fetch-only sources + storage (no CLI)
│   ├── services/       # FetchService
│   ├── sources/        # Data sources (HN, Reddit, PH, GitHub)
│   ├── storage.py      # Session persistence (writes raw.jsonl + sqlite)
│   └── session.py      # Fetch resume state.json
│
└── common/
    └── llm.py      # Shared LLM utilities

Fetch (Scout sources)