composto

Composto

Token-efficient code context for AI agents. Your file's full structure in a fraction of the tokens, with its causal history baked in.

Send your agent the structure, not the noise.

Composto compresses any source file into a Health-Aware IR that keeps exactly what your agent needs — signatures, types, control flow, dependencies — at 60-95% fewer tokens than raw code. On top of that, it surfaces the file's causal history (what historically changed and broke alongside the code you're touching) as advisory context. Local-first, MIT. Works with Claude Code, Cursor, and Gemini CLI.

$ composto ir src/memory/confidence.ts L1

USE:./types.js
OUT INTERFACE:ConfidenceContext
OUT INTERFACE:ScoreAndConfidence
FN:calibrationFactor(signals: Signal[])
      GUARD:[firing.length === 0 → 1.0, avg < 20 → 0.3, avg < 100 → 0.6]
FN:historyFactor(totalCommits: number)
      GUARD:[totalCommits < 50 → 0.2, totalCommits < 200 → 0.5, totalCommits < 1000 → 0.8]
OUT FN:computeScoreAndConfidence(signals: Signal[], ctx: ConfidenceContext)

# 541 tokens of raw code → 230 tokens of IR (57% fewer). Structure intact:
# every signature, dependency, and decision threshold survives.

Use it in 3 steps

# 1. See what your repo costs an AI — zero install, no API key, ~2s
cd your-project
npx composto-ai score          # scorecard: tokens, $/load, risk hotspots, a README badge

# 2. Install
npm install -g composto-ai

# 3. Wire it into your AI agent so it gets compact context automatically
composto init --client=claude-code                  # or cursor, or gemini-cli
composto init --client=claude-code --with-compress  # also auto-compress large Reads (saves tokens; see `stats`)
# Restart your client. Existing settings are merged, never overwritten.

That's it. Your agent now reads structure-preserving IR instead of raw files.

composto score .                       # shareable scorecard + README badge (add --json to pipe)
composto ir src/app.ts                 # compress one file to IR (L0/L1/L2/L3)
composto context src/ --budget 4000    # pack a directory into a token budget
composto context . --target <symbol>   # target file raw, surroundings as IR
composto context . --json              # machine-readable context for piping into agents
composto proxy --port 8787             # compression proxy — point your LLM base URL at it
composto impact src/auth/login.ts      # advisory causal history for a file
composto stats                         # hook telemetry + cumulative tokens saved

The core: token-efficient structural context

Composto's spine is a tree-sitter based AST compressor and a smart context packer. Compress any file to IR, or pack a whole directory into a token budget:

composto ir src/app.ts                 # compress a file to IR (L0/L1/L2/L3)
composto context src/ --budget 2000    # smart context within a token budget
composto benchmark .                   # see compression stats

See the IR Layers, Health-Aware IR, and Context Budget sections below for details.

On top: causal history as advisory context

Composto also indexes your git history and surfaces what historically changed and broke alongside the file you're editing — advisory context the agent weighs, not a gate. See Causal context below.

MCP plugin (Claude Code, Cursor, Claude Desktop)

The MCP server is bundled inside composto-ai. Install the package globally first, then register the server with your client:

npm install -g composto-ai

Claude Code:

claude mcp add composto -- composto-mcp

Cursor — add to ~/.cursor/mcp.json (or project-local .cursor/mcp.json):

{
  "mcpServers": {
    "composto": {
      "command": "composto-mcp"
    }
  }
}

Then restart Cursor and verify under Settings → MCP that composto is green.

Claude Desktop — add the same block to ~/Library/Application Support/Claude/claude_desktop_config.json.

Composto adds 5 tools to your AI assistant: composto_ir, composto_benchmark, composto_context, composto_scan, and composto_blastradius (the last one gated by COMPOSTO_BLASTRADIUS=1 during beta).

Cursor: one-command setup

Registering the MCP server only exposes the tools — Cursor's agent often defaults to its built-in read_file / codebase_search. To configure both the MCP server and a project rule that tells the agent when to call Composto, run:

cd your-project
composto init

This writes .cursor/mcp.json (project-local MCP registration) and .cursor/rules/composto.mdc (an alwaysApply: true rule that gets injected into every conversation). Existing files are merged, never overwritten. Restart Cursor and check Settings → MCP that composto is green.