Anvil

Model-agnostic runtime for end-to-end software execution with LLMs: planning work, orchestrating tools, and making changes safely in real codebases.

How It Works

Anvil runs an agent loop for real software work: the model receives a task, plans the work, selects the next action, executes inside a sandbox, and iterates until the job is complete. Anvil provides the runtime layer for multi-step planning, tool orchestration, and controlled execution while leaving reasoning and decision-making to the model.

Supported providers: OpenAI · Anthropic · Ollama (local)

Quick Start

# Install from source
git clone https://github.com/v0idum/anvil.git
cd anvil
python -m venv .venv && source .venv/bin/activate
pip install -e .

# Run an ad-hoc task (no project setup required)
anvil run "Create a Python function that calculates fibonacci numbers" \
  --provider ollama \
  --model qwen2.5-coder:14b

# Or initialize a project for multi-step builds
anvil init my-project
cd my-project
anvil plan "Build a REST API with Flask that manages a todo list"
anvil build

Installation

Requirements:

• Python 3.12+
• One of: Ollama (local, free), OpenAI API key, or Anthropic API key

Optional (recommended):

• Docker — for sandboxed code execution
• ripgrep — enables the search tool
• universal-ctags — enables the inspect and outline tools

pip install -e .          # core install
pip install -e ".[dev]"   # includes pytest and ruff for development

Usage

anvil run — Execute a one-off task

No project initialization needed. Point any LLM at a task and let it work.

# With Ollama (default, free, local)
anvil run "Add error handling to src/main.py"

# With OpenAI
anvil run "Write unit tests for the utils module" \
  --provider openai --model gpt-4o --token $OPENAI_API_KEY

# With Anthropic
anvil run "Refactor the database layer to use async" \
  --provider anthropic --model claude-sonnet-4-20250514 --token $ANTHROPIC_API_KEY

anvil init — Set up a project

Creates a .anvil/ directory with configuration for multi-step workflows.

anvil init my-app          # create new directory
anvil init .               # initialize current directory

anvil plan — Generate an implementation plan

Asks the LLM to analyze your description, ask clarifying questions, and produce a structured plan with tasks, milestones, and acceptance criteria.

anvil plan "Build a CLI tool that converts markdown to HTML with syntax highlighting"

anvil build — Execute the plan

Runs each task from the plan autonomously, with session checkpointing for crash recovery.

anvil build                # execute plan from .anvil/plan.json

anvil config — View configuration

anvil config               # show current .anvil/config.toml

Configuration

Anvil stores project config in .anvil/config.toml. You can also pass options via CLI flags or environment variables.

Setting	CLI Flag	Env Variable	Default
Provider	--provider	ANVIL_PROVIDER	ollama
Model	--model	ANVIL_MODEL	qwen2.5-coder:14b
API Token	--token	ANVIL_TOKEN	—
Sandbox	—	—	local

Architecture

src/anvil/
├── core/         # Agent loop, config, protocol parsing, sandbox, security
├── providers/    # LLM adapters (OpenAI, Anthropic, Ollama)
├── tools/        # Runtime operations and registry
├── planning/     # Task decomposition and plan generation
├── build/        # Plan execution with session checkpointing
└── retrieval/    # Package registry lookups (PyPI, npm, crates.io)

Testing

# Unit tests (no LLM required)
pytest tests/

# Integration tests (requires Ollama or API key)
pytest tests_integration/ -m integration

# With a specific provider
ANVIL_TEST_PROVIDER=openai ANVIL_TEST_TOKEN=$OPENAI_API_KEY pytest tests_integration/ -m integration

Docker

The docker/ directory contains the base image for sandboxed execution (Ubuntu 24.04 with Python, Node.js, Rust, ripgrep, and ctags). Anvil builds and manages this image automatically when you use Docker sandboxing.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Security

See SECURITY.md for reporting vulnerabilities.

License

MIT