aptu-coder

Standalone MCP server for code structure analysis using tree-sitter. 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. Offloading this to a dedicated tool reduces token usage and speeds up coding with better accuracy.

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

Overview

aptu-coder is a Model Context Protocol server that gives AI agents precise structural context about a codebase: directory trees, symbol definitions, and call graphs, without reading raw files. It supports 18 languages (see Supported Languages) and integrates with any MCP-compatible orchestrator.

Supported Languages

All languages are enabled by default. Disable individual languages at compile time via Cargo feature flags.

Language	Extensions	Feature flag
Astro	.astro	always-on (regex via TypeScript frontmatter extractor)
C/C++	.c, .cc, .cpp, .cxx, .h, .hpp, .hxx	lang-cpp
C#	.cs	lang-csharp
CSS	.css	lang-css (tree-sitter; regex fallback when disabled)
Fortran	.f, .f77, .f90, .f95, .f03, .f08, .for, .ftn	lang-fortran
Go	.go	lang-go
HTML	.html, .htm	lang-html (stub; no extraction)
Java	.java	lang-java
JavaScript	.js, .mjs, .cjs	lang-javascript
JSON	.json	always-on (regex; first-level key extraction)
Kotlin	.kt, .kts	lang-kotlin
Markdown	.md, .mdx	lang-markdown
Python	.py	lang-python
Rust	.rs	lang-rust
TOML	.toml	always-on (regex; section header extraction)
TSX	.tsx	lang-tsx
TypeScript	.ts	lang-typescript
YAML	.yaml, .yml	lang-yaml (tree-sitter; regex fallback when disabled)

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:

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	integer	100	Items per page

Tool	Purpose	Languages
analyze_directory	Directory tree with LOC, function, and class counts; respects .gitignore	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; errors if zero or multiple matches; empty new_text deletes the block; CRLF normalized before matching	all
exec_command	Run a shell command; returns stdout, stderr, exit code; output capped and filtered; optional timeout_secs (kill on expiry) and drain_timeout_secs (post-exit drain window); heredoc missing delimiter rejected before spawn	any

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 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.

drain_timeout_secs controls how long the server waits after the child exits for any background subprocess still holding the pipe open. Default is 500 ms (0 or omitted). Negative values return INVALID_PARAMS. When the drain window expires before the pipe closes, 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 expose a 4-step recommended workflow for unknown repositories: survey the repo root with analyze_directory at max_depth=2, drill into the source package, run analyze_module on key files for a function/import index (or analyze_file when signatures and types are needed), then use analyze_symbol to trace call graphs. MCP clients that surface server instructions will present this workflow 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 for the L2 on-disk call-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 disk cache entirely.
APTU_CODER_EXEC_CACHE_CAPACITY	64	LRU cache size for exec_command results.
APTU_CODER_EXEC_CACHE_TTL_SECS	10	TTL in seconds for exec_command result cache.
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_PROFILE	unset	Tool subset: edit (edit tools + exec_command only), analyze (analyze tools + exec_command only). Also settable per-session via io.clouatre-labs/profile in MCP _meta.
APTU_SHELL	unset	Shell for exec_command. Defaults to bash then /bin/sh.

Telemetry

Variable	Default	Description
DISABLE_PROMPT_CACHING	unset	Set to 1 to disable prompt caching (recommended for single-pass subagent sessions).
DISABLE_PROMPT_CACHING_HAIKU	unset	Set to 1 to disable prompt caching for Haiku-specific pipelines only.
OTEL_EXPORTER_OTLP_ENDPOINT	unset	OTLP HTTP endpoint URL (e.g., http://localhost:4318). When set, enables trace, log, and metric export via OTLP/HTTP; noop providers when unset.
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT	unset	Reserved per OTel GenAI conventions; aptu-coder does not implement this -- bounded parameters are recorded as span attributes instead.
XDG_DATA_HOME	~/.local/share	Base directory for daily-rotated JSONL metrics files ($XDG_DATA_HOME/aptu-coder/metrics-YYYY-MM-DD.jsonl, 30-day retention).

Observability

The server emits two parallel, independent telemetry streams.

JSONL metrics (always-on) are written daily-rotated to $XDG_DATA_HOME/aptu-coder/ (fallback: ~/.local/share/aptu-coder/) regardless of configuration. Each record captures tool name, duration, output size, and result status. Files are retained for 30 days. See docs/OBSERVABILITY.md for the full schema.

OpenTelemetry export (opt-in) is enabled when OTEL_EXPORTER_OTLP_ENDPOINT is set to an OTLP HTTP endpoint URL. When set, the server initializes OpenTelemetry trace, log, and meter providers and exports asynchronously via OTLP/HTTP. When unset, noop providers are used with zero runtime overhead.

Each tool invocation is wrapped in a span carrying OpenTelemetry GenAI semantic attributes (gen_ai.system, gen_ai.operation.name, gen_ai.tool.name). W3C Trace Context is extracted from the MCP _meta field on each call, allowing MCP clients to propagate their trace context so tool spans appear as children in a distributed trace.

For the span attribute policy, the never-record list, and details on what is instrumented, see OBSERVABILITY.md at the repository root.

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
• OBSERVABILITY.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.