Show HN: コーディングエージェント向けCapn-hook – 同じ謎を二度grepしない
Show HN: Capn-hook for coding agents – don't grep the same mystery twice (github.com)
要約
Capn-hookは、コーディングエージェントのために永続的なメモリを提供するツールです。エージェントがコードベース内の特定のファイルを見つけるのに費やした時間を節約し、次回セッションでワンコマンドでアクセスできるようにします。さらに、基盤となるファイルが変更されると、保存された回答は自動的に削除されるため、常に最新の情報が提供されます。これにより、トークン使用量が77%削減され、開発効率が向上することが実証されています。
全文翻訳
🧢🪝 cap'n hook
同じ謎を二度grepしない。
コーディングエージェントのための永続的なメモリ。エージェントがコードベース内の何かを見つけるのに10分費やした場合、capnはその質問に答えるファイルを保存します。次のセッションでは、再探索する代わりに1つのコマンドでそれらを取り戻せます。そして、基盤となるファイルが変更された瞬間に、保存された回答は自己削除されます。
繰り返し質問でトークンを77%削減
5つの本番コードベース(Dub、Polar、PostHog、Twenty、Documenso)における60件の実際の開発者からの質問全体で、capnから呼び出すエージェントは、ゼロから探索するエージェントと比較してトークン消費量が77%少なくなりました。どちらのアームでもすべての回答が正しく、60件の質問すべてで正しいチャートが呼び出され、チャートセッションは〜1.6回の呼び出しで元が取れました。
評価の実行方法、全数値、および生データはこちら → · capnは誰のためのものか → · ユースケース →
問題点
コーディングエージェントはセッション間で全てを忘れてしまいます。「支払いウェブフックはどこで処理されるか?」から「src/api/webhooks.ts、ハンドラはsrc/billing/handlers/」への経路は、実際の時間とトークンを消費し、セッションが終わると消えてしまいます。翌日のセッションでは、同じ発見を再度行うためのコストがかかります。
仕組み
capn initは、Claude CodeとCodexのためにセッション開始フックをインストールします。新しいセッションごとに、エージェントは1つの短い指示を見ます:コードベースを検索する前にcapnに尋ね、苦労して発見した後に保存する。 その指示(capn context)が統合の全てです。ラッパーやミドルウェア、強制的な動作はありません。モデルはそれを読み取り、決定します。
そこからループは3つのステップになります:
1. 検索前に尋ねる。
capn ask "where are payment webhooks handled?"
ヒットすると、質問に正確に答えるファイルを含むJSONLが返され、検索全体がスキップされます。ミスの場合、標準エラー出力に探索して発見したものをチャート化するよう促すメッセージと共に終了コード1が返されます。ミスは数秒で済みますが、再探索は数分かかります。
2. 学ぶのにコストがかかったものを保存する。 エージェントが苦労して答えを見つけた場合、オプションの詳細(行番号や注意点など)と共に、それを回答する質問とファイル(複数可)を記録します:
capn chart "where are payment webhooks handled?" \
--files src/api/webhooks.ts,src/billing/handlers/stripe.ts \
--details "Router starts near line 40; Stripe handler owns signature checks."
各バックアップファイルは、保存時にフィンガープリント(sha256)が取られます。
良いチャートは、巨大なコンテキストダンプではなく、アトミックであるべきです。分離可能な事実は別々のチャートに分割しますが、1つの焦点の合った質問に共同で答える場合は複数のファイルを含めてください。
3. 古くなった回答は自己削除される。 いずれかのバックアップファイルが変更または消失した場合、そのエントリは再度回答される前に削除されます。保存された回答は編集されることはありません。回答がまだ有効である(ファイルが変更されていない)か、価値がないかのどちらかです。だからコマンドはaddやupdateではなくchartとunchartなのです。capnはあなたのコードベースを海岸線のように扱います。エージェントは探索したものをチャート化します。海岸線が移動すると、古いチャートは捨てられ、エージェントは次に遭遇したときに再チャート化します。
最悪の場合、エントリが削除され、エージェントが再探索します。これは、capnなしでも行うことと同じです。
インストール
npm install -g capn-hook
# または
bun install -g capn-hook
cd /path/to/your/project
capn init # .capn/, capnのQMDインデックス、Claude Codeフック、およびCodexフック
capn init --git # post-commitフックもインストールしてプルーニングする
公開されているCLIはJavaScriptとして出荷され、Bunが利用可能な場合はBunで実行され、Node.jsにフォールバックします。
委任を優先しますか?コーディングエージェントにINSTALL.mdを取得してフォローするように指示してください。これはあなたが手動でコピーするためではなく、エージェントが実行するために書かれています。
| エージェント | ファイル | フック | コマンド | 効果 |
|---|---|---|---|---|
| Claude Code | .claude/settings.json | SessionStart | /usr/bin/env capn context | ask-first charting contract を注入 |
| Codex | .codex/hooks.json | SessionStart | /usr/bin/env capn context | ask-first charting contract を注入 |
リコールはQMDで実行されます。デフォルトではセマンティック(ハイブリッド)検索ですが、capn init --no-embeddingでプレーンなキーワード(BM25)検索も可能です。デフォルトパスは初回使用時に埋め込みモデルをダウンロードします(約300MB、フルハイブリッドパイプラインでは最大約2GB)。モデルが存在する場合、コールドなcapn askは数秒かかることがあります。BM25パスは何もダウンロードせず、完全に決定論的です。
既にqmdを使用していますか?capnのインデックスは.capn/内の独自のsqliteです。あなたのコレクションはそれを見ることはなく、それもあなたのコレクションを見ることはありません。
コマンド
| コマンド | 説明 |
|---|---|
| `capn init [--git] [--embedding | --no-embedding]` |
capn context | ask-first charting contract を表示する(SessionStartフックで使用) |
capn ask "<question>" | 古くなったエントリを最初にプルーニングしてから、関連するチャート化された回答のJSONLヒットを表示する |
capn chart "<question>" --files <a,b> [--details "<extra context>"] | 発見を記録し、各バックアップファイルをハッシュ化する |
capn unchart <id> | チャートエントリを1つ手動で削除する |
capn bust <path> | 1つのファイルでバックアップされたすべてのチャートエントリを削除する |
capn prune | ファイルが変更または消失したすべてのチャートエントリを削除する |
capn list | チャート化されたエントリを人間が読める形式で表示する |
チャート
.capn/entries/<id>.md — 質問ごとに1つのローカルマークダウンファイル。エントリは人間が開いて読めるプレーンテキストです。チャートは人間が閲覧可能であり、ツールだけではありません。capn initは.capn/をgitignoreするため、このメモリはワーキングコピーにローカルに保持されます。
---
capn: 1
id: 9f3a1c2e
at: 2026-07-03T18:00:00.000Z
files:
src/api/webhooks.ts: 2f4c0b9c3e0a0c7b5d5d7f8f0a6e2d1c4b8a6f1e2d3c4b5a6978877665544332
---
# Where are payment webhooks handled?
Router starts near line 40; Stripe handler owns signature checks.
.capn/map.json — ファイルパスから現在のハッシュとエントリIDへの派生逆インデックス。これが欠落または破損している場合、capnはエントリのフロントマターから再構築します。
{
"src/api/webhooks.ts": {
"hash": "2f4c0b9c3e0a0c7b5d5d7f8f0a6e2d1c4b8a6f1e2d3c4b5a6978877665544332",
"entries": ["9f3a1c2e"]
}
}
.capn/config.jsonは`{