Anneal

Optimal context selection for AI coding assistants. Cooling random context down to exactly what your AI needs.

Anneal reads your codebase's structural graph, formulates "which chunks are optimal?" as a QUBO problem, solves with simulated annealing, and returns the minimum context set for your task.

Quick Start

pip install anneal-context
cd your-project
anneal init          # builds graph from source, writes config

That's it. anneal init parses your codebase using tree-sitter, extracts functions, classes, and import relationships, and writes the graph to .anneal/graph.db. Then point your MCP client at anneal-server and you're ready to go.

How It Works

1. Build graph — anneal init walks your source tree and extracts structural relationships via tree-sitter, supporting 20+ languages (Python, JavaScript, TypeScript, Go, Rust, Java, Ruby, C/C++, and more)
2. Generate candidates — keyword matching + graph topology identify relevant chunks
3. Formulate QUBO — minimize token cost, maximize relevance, reward dependency coverage
4. Solve via simulated annealing — SpinChain engine finds optimal selection
5. Return results — stability-ranked, dependency-ordered chunks within your token budget

Requirements

• Python 3.11+

Installation

pip install anneal-context

Or with uv:

uv tool install anneal-context

Setup

Primary: anneal init

cd your-project
anneal init          # builds graph from source, writes config

anneal init uses tree-sitter to parse your codebase directly — no external tools required. It supports 20+ languages including Python, JavaScript, TypeScript, Go, Rust, Java, Ruby, C/C++, C#, Kotlin, Swift, Scala, PHP, and more.

The command:

• Walks your source files
• Extracts functions, classes, and import relationships
• Builds .anneal/graph.db
• Writes a default .anneal/config.toml

Add .anneal/ to your .gitignore.

Optional: Advanced Graph Sources

If you have code-review-graph or Graphify installed, Anneal merges their graph data alongside the built-in tree-sitter graph. This can provide additional structural signals (e.g., review history from code-review-graph, or Claude-generated summaries from Graphify).

# code-review-graph
npx code-review-graph install

# Graphify (Claude Code)
/plugin marketplace add safishamsi/graphify && /graphify

Configuration

Default config is written by anneal init. You can customize .anneal/config.toml:

[budget]
default_tokens = 5000
strategy = "balanced"   # "minimal" | "balanced" | "thorough"

[solver]
backend = "simulated-annealing"
num_reads = 100
num_sweeps = 1000

MCP Server Setup

Claude Code

Add to .claude/settings.json:

{
  "mcpServers": {
    "anneal": {
      "command": "anneal-server"
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "anneal": {
      "command": "anneal-server"
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[[mcp_servers]]
name = "anneal"
command = "anneal-server"

Cursor / VS Code + Copilot / Aider

Any MCP-compatible client: run anneal-server via stdio transport.

Tools

get_optimal_context

Parameters:
  task_description: str     -- what you want to do
  token_budget: int | None  -- max tokens (default: 5000)
  include_files: list[str]  -- always include these paths
  exclude_files: list[str]  -- never include these paths
  strategy: str             -- "balanced" | "minimal" | "thorough"

Returns:
  selected_chunks: list[{path, content, relevance_score, tokens}]
  total_tokens: int
  budget_utilization: float
  stability_score: float
  dependency_graph: dict

get_status

Returns graph source availability, node counts, solver config.

Development

git clone https://github.com/ameyakhot/anneal
cd anneal
uv venv && source .venv/bin/activate
uv pip install -e /path/to/spinchain
uv pip install -e ".[dev]"
python -m pytest tests/ -v

License

MIT