Aptu Coder

aptu-coder

AI コーディングエージェントに、生のファイルバイト列ではなく、あらかじめ解析されたシンボルテーブルと呼び出しグラフを提供する、Model Context Protocol（MCP）コードインテリジェンスサーバーです。引用したベンチマーク条件では、トークン使用量を最大 59% 削減します（「ベンチマーク」を参照）。OpenSSF シルバー認定済み。このレベルに達するオープンソースプロジェクトは 1% 未満です。

メモ

正規表現検索、パス照合、ファイル読み込みなどのネイティブエージェントツールは、対象を絞った検索に適しています。aptu-coder は、ディレクトリ構造のマッピング、シンボルの抽出、呼び出しグラフの追跡といった機械的で AI を必要としない作業を担います。そのため、コーディングエージェントは呼び出しごとに構造を再導出するのではなく、コンテキストウィンドウを推論に使えます。

AI エージェント向けのコードインテリジェンスツールの多くは、コードベースをクラウドの埋め込み表現やベクトルストアにインデックス化し、類似度検索で情報を取得します。一方、aptu-coder は tree-sitter を使ってコードベースをデバイス上で構造グラフに解析し、MCP 経由でローカルに提供します。ソースコードがマシンの外に出ることはなく、情報の取得は近似的な最近傍類似度検索ではなく、正確なシンボルテーブルと呼び出しグラフに基づきます。

ベンチマーク

Django（Python）のソースツリーを対象に、Claude Code で実施した認証移行タスクです。詳細な方法。

モード	Sonnet 4.6	Haiku 4.5
MCP	112k トークン、$0.39	406k トークン、$0.42
ネイティブ	276k トークン、$0.95	473k トークン、$0.53
削減量	トークン 59% 削減、費用 59% 削減	トークン 14% 削減、費用 21% 削減

OpenFAST（Fortran）のソースツリーを対象に、Claude Code で実施した AeroDyn 統合監査タスクです。詳細な方法。

モード	Sonnet 4.6	Haiku 4.5
MCP	472k トークン、$1.65	687k トークン、$0.72
ネイティブ	877k トークン、$2.85	2162k トークン、$2.21
削減量	トークン 46% 削減、費用 42% 削減	トークン 68% 削減、費用 68% 削減

このリポジトリ自体を対象にした、実際のエンドツーエンドのマルチエージェント実行では、リファクタリングの課題 5 件（#1578～#1582）が、1 回のオーケストレーションセッションで coder スキルによって修正されました。サブエージェントの起動は 23 回（scout 5 回、guard 1 回、build 10 回、check 7 回）、所要時間は約 1 時間 42 分、人間による介入は 3 回で、PR #1584～#1588 が作成され、すべて CI が成功した状態でマージされました。事例。

ベンチマークの主張の範囲

上記のトークン削減値は、エージェントがシェル検索の代わりに aptu-coder を使用した、単一の集中的な読解タスクに基づいています。エージェント型のコーディングループでは bash と ripgrep を使用でき、リポジトリを直接検索できます。v19 ベンチマークプログラム（N=20 の対応セッション、事前登録済みの主張判定基準）では、こうしたループで aptu-coder を測定しました。構造的なファンインタスクでは、bash + ripgrep に対する回答品質の測定可能な向上はありませんでした（プールした対応 F1 差の平均 -0.071、95% CI [-0.179, +0.038]、判定結果は NOT-SUPPORTED）。ツールが直接提示された場合、ツール自体は確実に起動しました。推奨用途は、決定論的な検証（捏造された path:line 引用に対する verify_anchors）、マルチエージェントワークフローの前提のグラウンディング、エージェントを介さない MCP 利用者（IDE アシスタント、CI ジョブ、スコアリングパイプライン）です。

概要

aptu-coder はコーディングエージェント向けの読解レイヤーです。エージェントハーネスに、コードベース、ディレクトリツリー、シンボル定義、呼び出しグラフに関する正確な構造コンテキストを提供します。これにより、エージェントが生のファイルを読み込んだり、呼び出しのたびに構造を再導出したりする必要がなくなります。その結果、結果セットをモデルのコンテキストウィンドウに収まるサイズに保ちながら、大規模または未知のコードベースでのコンテキスト不足を防ぎます。18 言語に対応し（対応言語を参照）、あらゆる MCP 互換オーケストレーターと連携します。

構造コンテキストは一度構築され、再利用されます。blake3 コンテンツハッシュをキーとするディスク上のキャッシュにより、同時書き込みがあっても結果の正確性が保たれます。この同じ構造グラフが、以下のナレッジグラフのリソースサーフェスを支えています。ディスク上のパスを持たないソーステキストを扱う利用者向けに、aptu-coder-core は公開 Rust ライブラリ API として analyze_str も提供しています（ARCHITECTURE.mdを参照）。

設計思想について詳しくは、エージェント型 SDLC ガバナンススタック、マルチエージェントの信頼性を高めるコンテキストエンジニアリング、AI エージェントのオーケストレーション：サブエージェントアーキテクチャをご覧ください。

対応言語

言語	拡張子
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

インストール

Homebrew（macOS および Linux）

brew install clouatre-labs/tap/aptu-coder

更新：brew upgrade aptu-coder

cargo-binstall（Rust 不要）

cargo binstall aptu-coder

cargo install（Rust ツールチェーンが必要）

cargo install aptu-coder

クイックスタート

ソースからビルド

cargo build --release

バイナリは target/release/aptu-coder にあります。

MCP クライアントを設定する

2 種類のトランスポートを利用できます。委任先を起動するオーケストレーター（例：goose coder）を使用する場合は、Streamable HTTP を推奨します。1 つのサーバープロセスをオーケストレーターとすべてのエージェントで共有できるため、各 stdio サブプロセスが独立したインスタンスを持つ場合に発生する拡張機能の不整合を防げます。

Streamable HTTP（マルチエージェント環境に推奨）

Homebrew を使うと、1 つのコマンドでログイン時にサーバーを起動し、実行し続けられます。

brew services start aptu-coder

Homebrew のフォーミュラは、デフォルトでポート 49200 を使ってサーバーを起動します。次に、~/.config/goose/config.yaml に拡張機能を一度追加します。

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

または、Claude Code の場合：

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

別のポートを使うには、再起動する前に APTU_CODER_PORT を設定します。

APTU_CODER_PORT=4000 brew services restart aptu-coder

brew services を使わずに直接起動するには：

aptu-coder --port 49200
# or equivalently
APTU_CODER_PORT=49200 aptu-coder

stdio（単一クライアントでの使用）

サーバーを必要とするプロセスが 1 つだけの場合に適しています。クライアントがプロセスのライフサイクルを管理し、自動的に起動します。

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

または、プロジェクトのルートにある .mcp.json に手動で追加します（バージョン管理を通じてチームと共有できます）。

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

ツール

すべてのオプションパラメーターは省略できます。analyze_directory、analyze_file、analyze_symbol で共通のオプションパラメーター：

パラメーター	型	デフォルト	説明
summary	boolean	auto	コンパクトな出力です。50K 文字を超えると自動的に有効になります
cursor	string	--	前回のレスポンスの next_cursor に含まれるページネーションカーソルです

ページサイズはサーバー側で管理されます。クライアントの page_size パラメーターはありません（指定すると INVALID_PARAMS が返されます）。

ツール	目的	言語
analyze_directory	LOC、関数数、クラス数を含むディレクトリーツリーです。.gitignore を尊重します。出力内のファイルパスは作業ディレクトリからの相対パスです	すべて
analyze_file	シグネチャと行範囲を含む関数、クラス、インポートです。未対応の拡張子では、簡易的な代替情報（行数、ファイル先頭、AST なし）を返します	すべて
analyze_module	軽量な関数とインポートのインデックスです（analyze_file より約 75% 小さい）。未対応の拡張子では、注記付きの空のインデックスを返します	すべて
analyze_symbol	ディレクトリ内の指定したシンボルの呼び出しグラフです。呼び出し元、呼び出し先、呼び出しの深さを示します	すべて
edit_overwrite	ファイルを作成または上書きします。親ディレクトリも作成します	任意のファイル
edit_replace	一意な完全一致のテキストブロック、または重複しないすべての出現箇所（replace_all=true）を置換します。一致が 0 件または複数件の場合はエラーになります。new_text が空の場合はブロックを削除します。一致判定の前に CRLF を正規化します。オプションの expected_content_hash（生バイト列の blake3 16 進数表現）を使うと、古くなった編集を拒否します。同じファイルへの同時編集はパスごとに直列化されます。置換された出現箇所数を occurrences_replaced として返します。バッチ形式では、old_text／new_text の代わりに edits[]（{old_text, new_text, replace_all} の配列）を渡すと、1 つのファイルに複数の置換をアトミックに適用します（無効な編集がある場合はインデックスごとのエラーを返して中止し、書き込みは行いません）	すべて
exec_command	シェルコマンドを実行します。stdout、stderr、終了コードを返します。出力は上限が設けられ、フィルタリングされます。リクエストがキャンセルされるとコマンドは終了します。終了後の読み取り猶予時間はサーバー側で管理されます（デフォルトは 500 ms）。heredoc は起動前に拒否されます（ファイル書き込みパターン、stdin を消費するフラグ、stdin パラメーターとの競合、または閉じ区切り文字の欠落）。structuredContent に含まれるのはメタデータのみです（終了コード、切り詰め、収集エラーのフラグ）。コマンド出力はテキストストリームに含まれます	任意
verify_anchors	ワークスペースのルートを基準に、パス:行[:シンボル] アンカーをまとめて検証します。ファイルの存在、1 始まりの行番号が範囲内かどうか、オプションの単語境界に一致するシンボルがプラスマイナス 2 行の範囲内にあるかを確認します。失敗を安全側に扱い、成功を決して捏造しません。structuredContent にはアンカーごとの判定結果（exists、in_range、symbol_found、window_line）が含まれます	すべて

ツールのパラメーター、制約、例は、MCP クライアントのツールインスペクターまたは tools/list のレスポンスで確認できます。

ナレッジグラフ

analyze_symbol は副作用として、コードベースの構造グラフを構築します。ファイル、シンボル、モジュールがノードとなり、型付きエッジ（contains、calls、imports）で接続されます。このグラフは、単一シンボルの直接的な呼び出しグラフを超えて関係をたどるための MCP リソーステンプレートとして、エージェントに公開されます。リソースは URI で指定します。利用可能なテンプレートを確認するには、resources/templates/list を使用してください。

URI テンプレート	説明
aptu-coder://graph/{repo_hash}/blast-radius/{symbol}?depth={depth}&format={format}	シンボルから外側へ、設定可能な深さ（デフォルト：3）まで BFS でたどります。呼び出し元／呼び出し先の連鎖を放射状のレイアウトで返します。
aptu-coder://graph/{repo_hash}/subgraph/{symbol}?format={format}	単一シンボルの完全なサブグラフ（呼び出し元、呼び出し先、およびそれらの接続）です。
aptu-coder://graph/{repo_hash}/blast-radius-bidirectional/{symbols}?max_nodes={max_nodes}&depth={depth}&format={format}	カンマ区切りの1つ以上のシードシンボルから、呼び出し元と呼び出し先の両方をたどる双方向 BFS です。

ページネーション： 結果はページ分割されます。次のページを取得するには、前回のレスポンスに含まれる不透明な cursor 値を渡してください。

深さパラメーター： blast-radius および blast-radius-bidirectional テンプレートでは、任意の depth クエリパラメーターを指定できます（整数、範囲は1～5、デフォルトは3）。

最大ノード数パラメーター： blast-radius-bidirectional テンプレートでは、任意の max_nodes クエリパラメーターを指定できます（整数、デフォルトは50）。これにより、走査中に訪問するノードの集合に上限を設定します。

形式パラメーター： 3種類すべてのクエリで、任意の format クエリパラメーターを指定できます（text または json、デフォルトは json）。format=text の場合、JSON のノード／エッジ構造の代わりに、render_subgraph_text が生成するプロンプト対応のプレーンテキスト形式でレスポンスが返されます。

コールドキャッシュ： まずディレクトリに対して analyze_symbol を呼び出し、グラフを構築してください。グラフが利用可能になるまでは、リソースから案内メッセージが返されます。

出力管理

大規模なコードベースでは、コンテキストのオーバーフローを防ぐために、いくつかの仕組みが用意されています。

ページネーション

analyze_file と analyze_symbol は、出力が切り詰められた場合に NEXT_CURSOR: 行を追加します。次のページを取得するには、このトークンを cursor として渡します。summary=true と cursor は同時に指定できません。両方を渡すとエラーになります。

# Response ends with:
NEXT_CURSOR: eyJvZmZzZXQiOjUwfQ==

# Fetch next page:
analyze_symbol path: /my/project symbol: my_function cursor: eyJvZmZzZXQiOjUwfQ==

exec_command の出力上限

exec_command は、コマンドの大きな出力がコンテキストにあふれるのを防ぐため、バイト単位の独立した上限を3つ適用します。

ストリーム	上限	動作
stdout	30,000 chars	末尾を保持し、最後の30k charsを残します
stderr	10,000 chars	末尾を保持し、エラーは末尾に表示されます
combined output_text	50,000 chars	インターリーブ後のセーフティーネット

stdout の30k上限は、データに基づいて設定されています。観測された exec_command 呼び出し27,981件の分析では、この上限を超えたのはわずか0.33%でした。いずれかの上限に達すると、レスポンスに output_truncated: true が設定され、JSONL メトリクスにも記録されます。

**上限に達した出力の取得：**出力が上限に達すると、レスポンスには MCP リソースリンク（aptu-overflow://slot-{seq}/stdout、/stderr、/interleaved）が含まれ、その呼び出しの完全な未加工のキャプチャを参照できます（最後の実行が優先されます）。resources/read を使って読み取ります。フィルターによって出力が切り詰められた場合は、フィルター適用前のキャプチャファイルを示すヒント行が表示されます。

サーバーが管理する終了後のドレイン時間（500 ms）では、パイプを開いたままにしているバックグラウンドサブプロセスの終了を待ちます。パイプが閉じる前にこの時間が経過した場合、exit_code は null となり、output_truncated: true が設定されます。

exec_command の出力フィルター

組み込みのフィルターテーブルは、出力がモデルに届く前に、出力の多い CLI ツールからのファイルごとのノイズを抑制します。フィルターは成功時のみ stdout、stderr、インターリーブされた出力に適用されます。失敗時には未加工の出力が常に保持されます。

コマンド	動作
git pull	diff-stat のノイズ（パイプバー、create mode、delete mode、rename、mode change の行）を除去します。出力が空の場合は ok (up-to-date) に置き換えます
git fetch	From と ref-range の行を除去し、10行に制限します。出力が空の場合は ok fetched に置き換えます
git push	remote: の進捗行と To の宛先行を除去し、10行に制限します。出力が空の場合は ok pushed に置き換えます
git log	20行に制限します
git status	20行に制限します
git show	パッチのハンク（@@ ヘッダーと +／- の差分行）を除去し、200行に制限します
git commit	GPG 署名と gitleaks フックの出力を除去し、10行に制限します。出力が空の場合は ok committed に置き換えます
git diff	ANSI エスケープシーケンスを除去し、100行に制限します。出力が空の場合は ok (working tree clean) に置き換えます
git add	gitleaks フックの出力を除去し、5行に制限します。出力が空の場合は ok staged に置き換えます
cargo build	Compiling／Checking／Downloading／Fresh の行を除去します。出力が空の場合は ok (build clean) に置き換えます
cargo test	Compiling／Checking／Fresh の行を除去します

プロジェクトローカルのルールは .aptu/filters.toml に追加できます。解析エラーが発生した場合や、認識されない schema_version 値（version != 1）が指定された場合は、警告をログに記録したうえで組み込みテーブルにフォールバックします。クラッシュは発生しません。フィルターが適用されると、structuredContent 内の filter_applied に、一致したルールが示されます。

非対話型パイプライン

シングルパスのサブエージェントセッションでは、プロンプトキャッシュは書き込まれますが、再利用されることはありません。ベンチマークでは、MCP の応答はネイティブのみのワークフローと比べてキャッシュへの書き込み量が約 2 倍となり、品質の向上がないままコストが増加することがわかりました。このオーバーヘッドを避けるには、DISABLE_PROMPT_CACHING=1（Haiku 固有のパイプラインでは DISABLE_PROMPT_CACHING_HAIKU=1）を設定してください。

サーバー独自の指示は、意図的に最小限の短い段落 1 つにしています。パッケージ／モジュールのマップには analyze_directory から始め、ファイルごとの詳細には analyze_module／analyze_file を、呼び出しグラフには analyze_symbol を使用します。また、JSONL メトリクスと jq のレシピについては docs/METRICS.md を参照するよう案内しています。サーバーの指示を表示する MCP クライアントでは、このガイダンスがエージェントに自動的に提示されます。

環境変数

キャッシュとランタイム

変数	デフォルト	説明
APTU_CODER_DIR_CACHE_CAPACITY	20	ディレクトリ分析結果の LRU キャッシュサイズです。
APTU_CODER_DISK_CACHE_DIR	$XDG_DATA_HOME/aptu-coder/analysis-cache	analyze_symbol が使用する L2 呼び出しグラフキャッシュと構造グラフキャッシュで共有されるディレクトリです。存在しない場合は自動的に作成されます。
APTU_CODER_DISK_CACHE_DISABLED	unset	1 を設定すると、L2 呼び出しグラフのディスクキャッシュを完全に無効にします。
APTU_CODER_DISK_CACHE_MAX_BYTES	536870912 (512 MiB)	構造グラフのディスクキャッシュの最大サイズ（バイト単位）です。上限を超えると、最終更新時刻に基づく LRU 方式で削除されます。
APTU_CODER_FILE_CACHE_CAPACITY	100	ファイル分析結果の LRU キャッシュサイズです。
APTU_CODER_METRICS_EXPORT_FILE	unset	シャットダウン時に 1 回限りの JSONL メトリクスを書き出す絶対パスです。
APTU_CODER_PORT	unset	ストリーム可能な HTTP モードのポートです。--port N と同等です。--port が優先されます。未設定で --port も渡されていない場合は、stdio モードが使用されます。
APTU_CODER_BEARER_TOKEN	unset	ストリーム可能な HTTP トランスポートの認証に使用するベアラートークンです。値が 32 文字未満の場合、警告がログに記録されます。
APTU_SHELL	unset	exec_command に使用するシェルです。デフォルトでは bash、次に /bin/sh を使用します。

可観測性

JSONL スキーマ、OTel の設定、スパン属性のポリシーについては、以下を参照してください。

• OBSERVABILITY.md（リポジトリのルート）
• docs/METRICS.md

ドキュメント

• AGENTS.md - コントリビューター向けリファレンス：プロジェクト構成、コマンド、rmcp の落とし穴、ツールのパラメーター制約
• ARCHITECTURE.md - 設計目標、モジュールマップ、データフロー、言語ハンドラーシステム、キャッシュ戦略
• CONTRIBUTING.md - 開発ワークフロー、コミット規約、PR チェックリスト
• DESIGN-GUIDE.md - 高性能な MCP サーバーを構築するための設計上の決定、根拠、再現ガイド
• MCP Best Practices - エージェント型ループ、オーケストレーションパターン、MCP ツール設計、メモリ管理、安全制御に関するベストプラクティス
• METRICS.md - メトリクススキーマ、JSONL 形式、保持ポリシー
• ROADMAP.md - 開発の履歴と今後の方針
• SECURITY.md - セキュリティポリシーと脆弱性の報告方法

ライセンス

Apache-2.0 です。詳細は LICENSE を参照してください。