Aptu Coder

aptu-coder

[crates.io] [SLSA Level 3] [OpenSSF Best Practices]

A Model Context Protocol (MCP) code-intelligence server that gives AI coding agents pre-parsed symbol tables and call graphs 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 tracing call graphs, 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 call graphs) rather than approximate (nearest-neighbor similarity).

Benchmarks

Auth migration task on Claude Code against Django (Python) source tree. Full methodology.

AeroDyn integration audit task on Claude Code against OpenFAST (Fortran) source tree. Full methodology.

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: deterministic verification (verify_anchors against fabricated path:line citations), 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 call graphs, 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. The same structural graph backs the Knowledge Graph resource surface below. 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: The Agentic SDLC Governance Stack, Context Engineering for Multi-Agent Reliability, and Orchestrating AI Agents: Subagent Architecture.

Supported Languages

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

Two transports are available. Streamable HTTP is recommended when using orchestrators that spawn delegates (e.g. goose coder): a single server process is shared across the orchestrator and all agents, eliminating extension-drift that occurs when each stdio subprocess gets its own isolated instance.

Streamable HTTP (recommended for multi-agent setups)

With Homebrew, one command starts the server on login and keeps it running:

brew services start aptu-coder

The Homebrew formula starts the server on port 49200 by default. Then add the extension once to ~/.config/goose/config.yaml:

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

Or for Claude Code:

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

To use a different port, set APTU_CODER_PORT before restarting:

APTU_CODER_PORT=4000 brew services restart aptu-coder

To start directly without brew services:

aptu-coder --port 49200# or equivalentlyAPTU_CODER_PORT=49200 aptu-coder

stdio (single-client use)

Suitable when only one process needs the server. The client owns the process lifecycle and spawns it automatically:

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": []    }  }}

Tools

All optional parameters may be omitted. Shared optional parameters for analyze_directory, analyze_file, and analyze_symbol:

Page size is server-owned; there is no client page_size parameter (passing one returns INVALID_PARAMS).

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

Knowledge Graph

analyze_symbol builds a structural graph of the codebase as a side effect: files, symbols, and modules as nodes, connected by typed edges (contains, calls, imports). That graph is exposed to agents as MCP resource templates for navigating relationships beyond a single symbol's immediate call graph. Resources are URI-addressed; use resources/templates/list to discover available templates.

Pagination: Results are paginated; pass the opaque cursor value from a previous response to fetch the next page.

Depth parameter: The blast-radius and blast-radius-bidirectional templates accept an optional depth query parameter (integer in range 1-5, default 3).

Max nodes parameter: The blast-radius-bidirectional template accepts an optional max_nodes query parameter (integer, default 50) that caps the visited node set during traversal.

Format parameter: All three query types accept an optional format query parameter (text or json, default json). When format=text, the response is a prompt-ready plain-text representation generated by render_subgraph_text instead of the JSON nodes/edges structure.

Cold cache: Call analyze_symbol on the directory first to build the graph. Resources return an informational message until the graph is available.

Output Management

For large codebases, several mechanisms prevent context overflow.

Pagination

analyze_file and analyze_symbol append 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_symbol path: /my/project symbol: my_function cursor: eyJvZmZzZXQiOjUwfQ==

exec_command output caps

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

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.

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 and analyze_symbol for call graphs, 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

Observability

For the JSONL schema, OTel configuration, and span attribute policy, see:

• OBSERVABILITY.md (repository root)
• docs/METRICS.md

Documentation

• AGENTS.md - Contributor reference: project structure, commands, rmcp footguns, tool parameter constraints
• ARCHITECTURE.md - Design goals, module map, data flow, language handler system, caching strategy
• CONTRIBUTING.md - Development workflow, commit conventions, PR checklist
• DESIGN-GUIDE.md - Design decisions, rationale, and replication guide for building high-performance MCP servers
• MCP Best Practices - Best practices for agentic loops, orchestration patterns, MCP tool design, memory management, and safety controls
• METRICS.md - Metrics schema, JSONL format, and retention policy
• ROADMAP.md - Development history and future direction
• SECURITY.md - Security policy and vulnerability reporting

License

Apache-2.0. See LICENSE for details.