codesight を採用する前に見るべき点: AST から AI 用コンテキストを生成する CLI

codesight が埋めるのは「毎回同じ説明をさせる」コスト

AI コーディングツールは会話のたびにプロジェクト構造を把握し直す。どのファイルにルーティングがあり、どのモデルがどのテーブルに対応し、どこを変更すると何が壊れるか。人間なら記憶しているこれらの情報を、ツールは毎セッション読み直す。codesight はこの読み直しを、リポジトリを解析して生成した markdown ファイルに置き換える。README の冒頭は「Your AI assistant wastes thousands of tokens every conversation just figuring out your project」と述べており、対象読者は Claude Code、Cursor、GitHub Copilot、OpenAI Codex、Windsurf、Cline、Aider など markdown を読むツールの利用者である。特定の AI ベンダーに閉じていない点が設計の前提になっている。

TypeScript は AST、それ以外は正規表現という二層構造

解析の仕組みは言語によって分かれる。README によれば TypeScript プロジェクトは完全な AST 精度で処理され、それ以外の言語は同じ 30 以上のフレームワーク検出器を使いつつ正規表現ベースの検出になる。対応言語として TypeScript、JavaScript、Python、Go、Ruby、Elixir、Java、Kotlin、Rust、PHP、Dart、Swift、C#、そして BrightScript/BrighterScript (Roku) が列挙されている。Roku 向け言語が入っているのは珍しく、作者の関心領域がそのまま反映された構成だ。AST を使うということは、シンボルの定義と参照、ルート定義、ORM のモデル関係を構文木から取り出せるということで、正規表現では取りこぼすネストした定義や動的な記述に対して有利になる。逆に言えば、TypeScript 以外ではこの利点は期待できない。14 の ORM パーサーが同梱されている点も、モデル定義の抽出を前提とした設計を示している。

実行は npx 一回、設定ファイルも API キーも不要

導入はプロジェクトルートで npx codesight を実行するだけだと README は説明している。設定も API キーも不要と明記されている。主要なフラグは次のとおり。npx codesight --wiki で .codesight/wiki/ に wiki ナレッジベースを生成、npx codesight --init で CLAUDE.md、.cursorrules、codex.md、AGENTS.md を生成、npx codesight --open で HTML レポートを開き、npx codesight --mcp で MCP サーバーとして 14 ツールを公開する。ファイル単位の影響範囲は npx codesight --blast src/lib/db.ts のようにパスを渡して確認する。ツール別の最適化設定は npx codesight --profile claude-code のように生成できる。トークン削減の内訳は npx codesight --benchmark で表示される。--native-ast は追加言語向けの AST プラグインを有効にするオプトインで、docs/wasm-plugins.md に説明があるとされている。ナレッジモードは npx codesight --mode knowledge で .md ファイルを走査し、npx codesight --mode knowledge ~/vault のように Obsidian の vault や ADR、議事録を対象にできる。

wiki は LLM ではなく AST から組み立てられる

v1.6.2 で入った wiki ナレッジベースは Karpathy の LLM wiki パターンに着想を得たと README は述べつつ、LLM ではなく AST からコンパイルし、API 呼び出しはゼロ、所要 200ms としている。生成物は index.md、overview.md、そして auth.md、payments.md、database.md、users.md、ui.md のようなトピック別記事、加えて操作履歴を追記する log.md で構成される。index.md は約 200 トークンのカタログで、セッション開始時にこれを読ませる。README の比較表では「How does auth work?」への回答が wiki なしで約 12K トークン、auth.md 経由で約 300 トークン、「What models exist?」が CODESIGHT.md 全体の約 5K に対し database.md で約 400 トークンとされている。ここで注意したいのは、これらの数値が README の主張であり、第三者の計測ではないことだ。自分のリポジトリで --benchmark を走らせて確認するまでは参考値として扱うべきである。wiki 用の MCP ツールは codesight_get_wiki_index、codesight_get_wiki_article、codesight_lint_wiki の3つで、lint は孤立記事、欠けた相互リンク、古くなった内容を検査する。

ナレッジモードはコードの外側を同じ形式で扱う

v1.9.3 の --mode knowledge は、コードではなく意思決定や議事録、ADR、振り返りを .codesight/KNOWLEDGE.md にまとめる。README が示す出力例では、冒頭に「47 notes · 12 decisions · 8 open questions」のような件数と期間のサマリが置かれ、その下に日付付きの決定事項が並ぶ。コード解析と同じ発想を markdown 群に適用しているわけだが、こちらは AST ではなくテキスト走査なので、抽出品質はノートの書き方に強く依存する。日付や見出しの付け方が揃っていない vault では、決定事項の抽出が不安定になる可能性がある。README はこの点に触れていない。ナレッジモードを使うなら、まず自分の vault で出力を確認し、意図した決定が拾えているかを確かめる必要がある。

TypeScript 以外のリポジトリでは精度の前提が崩れる

最も明確な限界は言語カバレッジの非対称性である。README 自身が「TypeScript projects get full AST precision. Everything else uses battle-tested regex detection」と書いている。つまり Go や Ruby、Python が主軸のリポジトリでは、ルートやモデルの抽出が正規表現の限界に従う。動的に組み立てられたルート定義、メタプログラミングで生成されるモデル、文字列連結で作られるパスなどは取りこぼしうる。もう一つの制約は Node.js 18 以上が前提である点で、これは README のバッジ行に明記されている。ゼロ依存という設計は導入のしやすさと引き換えに、解析ロジックを自前で抱えていることを意味する。新しいフレームワークや言語機能への追随は、外部パーサーの更新を待つのではなく、このプロジェクト自身のリリースに依存する。14 の MCP ツールや 30 以上のフレームワーク検出器という広さは、個々の検出器の深さを保証しない。使う前に、自分のスタックが検出対象に入っているかを生成物で確認すべきである。

repomix との違いは「圧縮」か「構造抽出」か

同種の課題に対する代表的な選択肢に repomix がある。こちらはリポジトリ全体を AI が読みやすい単一ファイルに詰め込む方向のツールで、発想は圧縮と整形にある。codesight は逆で、リポジトリを構造として解析し、ルート、モデル、ミドルウェア、影響範囲といった意味のある単位に切り出してから出力する。全ファイルを渡すのではなく、質問に応じて auth.md だけを読ませるという wiki の使い方がその延長にある。どちらが優れているかではなく、必要なものが違う。手元のコードをそのままモデルに渡したいなら repomix のほうが素直だし、フレームワークの構造を抽出してトークン消費を質問単位に抑えたいなら codesight の設計が合う。ただし構造抽出は解析精度に依存するため、TypeScript 以外では repomix との差が縮まると考えたほうがよい。

ライセンスと保守コストの見積もり

ライセンスは MIT で、リポジトリの LICENSE ファイルに対応する。MIT は商用利用を含めて寛容な条件だが、具体的な義務や同梱物の扱いは利用形態によって変わるため、判断は法務に確認してほしい。保守の観点では、リポジトリはアーカイブされておらず、最終 push は 2026-07-27、バージョンタグは v1.6.2 と v1.9.3 が README に現れる。ただし取得できたリリース情報はなく、リリースノートに基づく変更履歴の追跡はこの材料だけではできない。ゼロ依存なので依存関係の更新に追われることはないが、その分だけ解析対象のフレームワークと言語の変化に追随する責任をプロジェクトが単独で負う。CI に組み込むなら、--hook でコミットごとに wiki を再生成する運用と、生成物を git にコミットする運用のどちらを取るかを先に決めておきたい。生成物が差分ノイズになるか、それともレビュー対象になるかで、日々のコストは大きく変わる。

編集部の結論

TypeScript のモノレポや大規模な Next.js プロジェクトで、Claude Code や Cursor のセッション開始ごとに同じファイルを読み直させているチームには、npx codesight --wiki と .codesight/wiki/ の git 管理をまず試す価値がある。逆に Go や Ruby が主軸のリポジトリでは、README 自身が「TypeScript 以外は正規表現検出」と明記しているため、AST 精度を前提にした運用は避けたほうがよい。導入前に確認すべきは、自分のリポジトリで --benchmark を実行してトークン削減が実際にどこで発生しているか、そして生成された CODESIGHT.md と wiki 記事の中身が自分のアーキテクチャ記述として妥当かどうかの2点である。

公式情報源

1. Houseofmvps/codesight on GitHub
2. Issues
3. License: MIT
4. Project website
5. README