Aptu Coder

aptu-coder

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 equivalently

APTU_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: Resul