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% (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.
| Mode | Sonnet 4.6 | Haiku 4.5 |
|---|
| MCP | 112k tokens, $0.39 | 406k tokens, $0.42 |
| Native | 276k tokens, $0.95 | 473k tokens, $0.53 |
| Savings | 59% fewer tokens, 59% cheaper | 14% fewer tokens, 21% cheaper |
AeroDyn integration audit task on Claude Code against OpenFAST (Fortran) source tree. Full methodology.
| Mode | Sonnet 4.6 | Haiku 4.5 |
|---|
| MCP | 472k tokens, $1.65 | 687k tokens, $0.72 |
| Native | 877k tokens, $2.85 | 2162k tokens, $2.21 |
| Savings | 46% fewer tokens, 42% cheaper | 68% fewer tokens, 68% cheaper |
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.
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
| Language | Extensions |
|---|
| Astro | .astro |
| C/C++ | .c, .cc, .cpp, .cxx, .h, .hpp, .hxx |
| C# | .cs |
| CSS | .css |
| Fortran | .f, .f77, .f90, .f95, .f03, .f08, .for, .ftn |
| Go | .go |
| HTML | .html, .htm |
| Java | .java |
| JavaScript | .js, .mjs, .cjs |
| JSON | .json |
| Kotlin | .kt, .kts |
| Markdown | .md, .mdx |
| Python | .py |
| Rust | .rs |
| TOML | .toml |
| TSX | .tsx |
| TypeScript | .ts |
| YAML | .yaml, .yml |
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
Quick Start
Build from source
The binary is at target/release/aptu-coder.
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
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": []
}
}
}
All optional parameters may be omitted. Shared optional parameters for analyze_directory, analyze_file, and analyze_symbol:
| Parameter | Type | Default | Description |
|---|
summary | boolean | auto | Compact output; auto-triggers above 50K chars |
cursor | string | -- | Pagination cursor from a previous response's next_cursor |
Page size is server-owned; there is no client page_size parameter (passing one returns INVALID_PARAMS).
| Tool | Purpose | Languages |
|---|
analyze_directory | Directory tree with LOC, function, and class counts; respects .gitignore; file paths in the output are relative to the working directory | all |
analyze_file | Functions, classes, and imports with signatures and line ranges; returns graceful fallback (line count, file head, no AST) for unsupported extensions | all |
analyze_module | Lightweight function and import index (~75% smaller than analyze_file); returns graceful fallback (empty index with note) for unsupported extensions | all |
analyze_symbol | Call graph for a named symbol across a directory; callers, callees, call depth | all |
edit_overwrite | Create or overwrite a file; creates parent directories | any file |
edit_replace | Replace a unique exact text block or all non-overlapping occurrences (replace_all=true); errors if zero or multiple matches; empty new_text deletes the block; CRLF normalized before matching; optional expected_content_hash (blake3 hex of raw bytes) rejects stale edits; concurrent edits to the same file are serialized per-path; returns occurrences_replaced count. Batch form: pass edits[] (array of {old_text, new_text, replace_all}) instead of old_text/new_text to apply multiple replacements to one file atomically (any invalid edit aborts with per-index errors, no write) | all |
exec_command | Run a shell command; returns stdout, stderr, exit code; output capped and filtered; the command is killed when the request is cancelled; server-owned post-exit drain window (500 ms default); heredoc rejected before spawn (file-write pattern, stdin-consuming flag, stdin parameter conflict, or missing closing delimiter); structuredContent carries metadata only (exit code, truncation, collection-error flags), command output lives in the text stream | any |
verify_anchors | Batch-verify path:line[:symbol] anchors against a workspace root: file exists, 1-based line within range, and optional word-boundary symbol match within a plus or minus 2 line window; fail-closed semantics, never fabricates success; structuredContent carries one verdict per anchor (exists, in_range, symbol_found, window_line) | all |
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.
| URI Template | Description |
|---|
aptu-coder://graph/{repo_hash}/blast-radius/{symbol}?depth={depth}&format={format} | BFS traversal from a symbol outward to configurable depth (default: 3). Returns caller/callee chains in a radial layout. |
aptu-coder://graph/{repo_hash}/subgraph/{symbol}?format={format} | The full subgraph (callers, callees, and their connections) for a single symbol. |
aptu-coder://graph/{repo_hash}/blast-radius-bidirectional/{symbols}?max_nodes={max_nodes}&depth={depth}&format={format} | Bidirectional BFS from one or more comma-separated seed symbols walking both callers and callees. |
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:
| Stream | Cap | Behavior |
|---|
| stdout | 30,000 chars | Tail-preserving; keeps the last 30k chars |
| stderr | 10,000 chars | Tail-preserving; errors appear at the end |
combined output_text | 50,000 chars | 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.
| Command | Behavior |
|---|
git pull | Strips diff-stat noise (pipe bars, create mode, delete mode, rename, mode change lines); empty output replaced with ok (up-to-date) |
git fetch | Strips From and ref-range lines; caps at 10 lines; empty output replaced with ok fetched |
git push | Strips remote: progress lines and To destination lines; caps at 10 lines; empty output replaced with ok pushed |
git log | Caps at 20 lines |
git status | Caps at 20 lines |
git show | Strips patch hunks (@@ headers and +/- diff lines); caps at 200 lines |
git commit | Strips GPG signing and gitleaks hook output; caps at 10 lines; empty output replaced with ok committed |
git diff | Strips ANSI escape sequences; caps at 100 lines; empty output replaced with ok (working tree clean) |
git add | Strips gitleaks hook output; caps at 5 lines; empty output replaced with ok staged |
cargo build | Strips Compiling / Checking / Downloading / Fresh lines; empty output replaced with ok (build clean) |
cargo test | Strips Compiling / Checking / Fresh lines |
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
| Variable | Default | Description |
|---|
APTU_CODER_DIR_CACHE_CAPACITY | 20 | LRU cache size for directory-analysis results. |
APTU_CODER_DISK_CACHE_DIR | $XDG_DATA_HOME/aptu-coder/analysis-cache | Directory shared by the L2 call-graph cache and the structural-graph cache used by analyze_symbol. Created automatically if it does not exist. |
APTU_CODER_DISK_CACHE_DISABLED | unset | Set to 1 to disable the L2 call-graph disk cache entirely. |
APTU_CODER_DISK_CACHE_MAX_BYTES | 536870912 (512 MiB) | Max size in bytes for the structural-graph disk cache. LRU-by-mtime eviction runs when exceeded. |
APTU_CODER_FILE_CACHE_CAPACITY | 100 | LRU cache size for file-analysis results. |
APTU_CODER_METRICS_EXPORT_FILE | unset | Absolute path for a one-shot JSONL metrics export on shutdown. |
APTU_CODER_PORT | unset | Port for streamable HTTP mode. Equivalent to --port N; --port takes precedence. When unset and --port is not passed, stdio mode is used. |
APTU_CODER_BEARER_TOKEN | unset | Bearer token for Streamable HTTP transport authentication. A warning is logged if the value is fewer than 32 characters. |
APTU_SHELL | unset | Shell for exec_command. Defaults to bash then /bin/sh. |
Observability
For the JSONL schema, OTel configuration, and span attribute policy, see:
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.