Aptu Coder

aptu-coder

A Model Context Protocol (MCP) code-intelligence server that gives AI coding agents pre-parsed symbol tables and structural code search instead of raw file bytes, cutting token usage by up to 59% in the cited benchmark conditions (see Benchmarks ). OpenSSF silver certified: fewer than 1% of open source projects reach this level.

[!NOTE]

Native agent tools (regex search, path matching, file reading) handle targeted lookups well. aptu-coder handles the mechanical, non-AI work: mapping directory structure, extracting symbols, and locating callers and implementors via structural search, so a coding agent's context window is spent reasoning instead of re-deriving structure on every call.

Most code-intelligence tooling for AI agents indexes a codebase into a cloud embedding or vector store and retrieves by similarity search. aptu-coder instead parses the codebase into a structural graph on-device with tree-sitter and serves it locally over MCP: no source code leaves the machine, and retrieval is exact (symbol tables and structural code search) rather than approximate (nearest-neighbor similarity).

Benchmarks

Paired comprehension tasks on Claude Code (MCP mode vs native shell search). Methodology: Django auth migration (v12) and OpenFAST AeroDyn integration audit (v13).

A real end-to-end multi-agent run against this repository itself: five refactoring issues (#1578–#1582) fixed by the coder skill in one orchestrated session — 23 subagent spawns (5 scout, 1 guard, 10 build, 7 check), ~1h42m, three human interventions — producing PRs #1584–#1588, all merged with CI green. Case study.

Scope of the benchmark claims

The token-savings figures above come from single, focused comprehension tasks where the agent used aptu-coder instead of shell search. Agentic coding loops have bash and ripgrep and can search the repo directly. The v19 benchmark program (N=20 paired sessions, pre-registered claim gate) measured aptu-coder in those loops: no measurable answer-quality gain over bash + ripgrep on structural fan-in tasks (pooled paired F1 diff mean -0.071, 95% CI [-0.179, +0.038]; gate NOT-SUPPORTED); tool activation itself was reliable when tools were surfaced directly. Recommended uses: premise grounding for multi-agent workflows, and non-agentic MCP consumers (IDE assistants, CI jobs, scoring pipelines).

Overview

aptu-coder is a comprehension layer for coding agents: it gives an agent harness precise structural context about a codebase, directory trees, symbol definitions, and callers and implementors via structural search, without the agent reading raw files or re-deriving structure on every call. That prevents context starvation on large or unfamiliar codebases while keeping the result set small enough to fit the model's context window. It supports 18 languages (see Supported Languages) and integrates with any MCP-compatible orchestrator.

Structural context is built once and reused: an on-disk cache keyed by blake3 content hashes keeps results correct across concurrent writes. For consumers that hold source text without an on-disk path, aptu-coder-core also exposes analyze_str as a public Rust library API (see ARCHITECTURE.md).

Further reading on the design philosophy, from the author's blog: The Agentic SDLC Governance Stack, Context Engineering for Multi-Agent Reliability, and Orchestrating AI Agents: Subagent Architecture.

Supported Languages

Astro, C/C++, C#, CSS, Fortran, Go, HTML, Java, JavaScript, JSON, Kotlin, Markdown, Python, Rust, TOML, TSX, TypeScript, YAML. The full extension map lives in crates/aptu-coder-core/src/lang.rs.

Installation

Homebrew (macOS and Linux)

brew install clouatre-labs/tap/aptu-coder

Update: brew upgrade aptu-coder

cargo-binstall (no Rust required)

cargo binstall aptu-coder

cargo install (requires Rust toolchain)

cargo install aptu-coder

Quick Start

Build from source

cargo build --release

The binary is at target/release/aptu-coder.

Configure MCP Client

stdio (default) — the client spawns and owns the server process; this works with orchestrators that spawn delegates (goose, pi) as well as single clients:

claude mcp add --transport stdio aptu-coder -- aptu-coder

Or add manually to .mcp.json at your project root (shared with your team via version control):

{

"mcpServers": { "aptu-coder": { "command": "aptu-coder", "args": [] } } }

Streamable HTTP (optional) — runs a single shared server process instead of one per client. Only worth it if you specifically want a daemon-style setup:

aptu-coder --port 49200            # or: brew services start aptu-coder

claude mcp add --transport http aptu-coder http://127.0.0.1:49200/mcp

For goose, add to ~/.config/goose/config.yaml:

extensions:

aptu-coder: type: streamable_http uri: http://127.0.0.1:49200/mcp name: aptu-coder timeout: 300

Tools

All optional parameters may be omitted. analyze_directory, analyze_file, and analyze_module accept summary (compact output, auto-triggers above 50K chars) and cursor (pagination token). Page size is server-owned; there is no client page_size parameter (passing one returns INVALID_PARAMS).

• analyze_directory -- directory tree with LOC, function, and class counts; respects .gitignore
• analyze_file -- functions, classes, and imports with signatures and line ranges; graceful fallback for unsupported extensions
• analyze_module -- lightweight function and import index (~75% smaller than analyze_file)
• edit_overwrite -- create or overwrite a file; creates parent directories
• edit_replace -- replace a unique exact text block (or all occurrences with replace_all); batch form edits[] applies multiple replacements atomically; optional expected_content_hash rejects stale edits
• exec_command -- run a shell command; output is capped, filtered, and returned with exit code; cancelled requests kill the command
• search_code -- structural code search in two modes: pattern (metavariable patterns with $X and $$$REST; Rust, Go, Python, and TypeScript) and symbol (definitions, callers, and implementors via the structural graph, all supported languages); byte-exact spans suitable for edit_replace; cursor-paginated

Tool parameters, constraints, and examples are available via your MCP client's tool inspector or tools/list response.

Output Management

For large codebases, several mechanisms prevent context overflow.

Pagination

analyze_file appends a NEXT_CURSOR: line when output is truncated. Pass the token back as cursor to fetch the next page. summary=true and cursor are mutually exclusive; passing both returns an error.

# Response ends with:

NEXT_CURSOR: eyJvZmZzZXQiOjUwfQ==

Fetch next page:

analyze_file path: /my/project/src/lib.rs cursor: eyJvZmZzZXQiOjUwfQ==

exec_command output caps

exec_command applies three independent byte-level caps to prevent large command outputs from flooding the context:

stdout keeps the last 30,000 chars, stderr the last 10,000 (tail-preserving, so errors appear at the end), and the combined output_text is capped at 50,000 chars as a safety net after interleaving.

The 30k stdout cap is data-driven: analysis of 27,981 observed exec_command calls shows only 0.33% exceed this limit. When any cap fires, output_truncated: true is set in the response and recorded in the JSONL metrics.

Recovering capped output: when output is capped, the response includes MCP resource links (aptu-overflow://slot-{seq}/stdout, /stderr, /interleaved) pointing to the full raw capture for that invocation (last-run-wins); read them via resources/read. If a filter capped the output, a hint line points to the pre-filter capture file.

A server-owned post-exit drain window (500 ms) waits for any background subprocess still holding the pipe open. If it expires before the pipe closes, exit_code is null and output_truncated: true is set.

exec_command output filters

A built-in filter table suppresses per-file noise from chatty CLI tools before output reaches the model. Filters apply to stdout, stderr, and interleaved output on success only; raw output is always preserved on failure.

Built-in rules cover the usual suspects: git pull/fetch/push strip diff-stat, remote-progress, and ref noise; git log/status cap at 20 lines; git show strips patch hunks; git diff strips ANSI escapes; git commit/add strip hook output; cargo build/test strip Compiling/Checking/Fresh progress lines. Clean output collapses to a short ok confirmation.

Project-local rules can be added in .aptu/filters.toml. Parse errors and unrecognized schema_version values (version != 1) fall back to the built-in table with a logged warning; no crash occurs. When a filter fires, filter_applied in structuredContent identifies which rule matched.

Non-Interactive Pipelines

In single-pass subagent sessions, prompt caches are written but never reused. Benchmarks showed MCP responses writing ~2x more to cache than native-only workflows, adding cost with no quality gain. Set DISABLE_PROMPT_CACHING=1 (or DISABLE_PROMPT_CACHING_HAIKU=1 for Haiku-specific pipelines) to avoid this overhead.

The server's own instructions are deliberately minimal, a single short paragraph: start with analyze_directory for a package/module map, then use analyze_module/analyze_file for per-file detail, with a pointer to docs/METRICS.md for JSONL metrics and jq recipes. MCP clients that surface server instructions will present this guidance automatically to the agent.

Environment Variables

Cache and runtime

| Variable | Default | Des