Repomixでリポジトリを束ねClaude Codeに渡す方法

Repomixは、リポジトリ全体を1つのAI向けファイルにまとめるCLIです。npx repomix@latest を実行すると、カレントディレクトリに repomix-output.xml が生成されます。ただしClaude Codeは自分でファイルを検索して読めるので、すべての場面で必要になるわけではありません。向くのは、ファイルシステムに触れない相手へ渡すときと、他人のリポジトリを丸ごと読ませたいときです。

この記事では、Repomixの出力形式と絞り込みの設定、Claude Codeとの組み合わせ方、使い分けの目安を順に扱います。

Repomixとは何をするツールか

Repomixは、リポジトリのファイル群を1つのファイルへ結合するツールです。結合時に、ディレクトリ構成・各ファイルの中身・利用の説明文を1つの文書に並べます。主な特徴は次のとおりです。

• トークン数をファイルごと・リポジトリ全体で数える
• .gitignore、.ignore、.repomixignore を自動で読み込み、除外に反映する
• Secretlintで、既知の認証情報の形式に合致するファイルを出力から外す
• --compress でTree-sitterによりコードの骨格だけを残す

出力形式は4種類あります。既定はXMLです。

XMLの出力は、<file_summary>、<directory_structure>、<files>、<instruction> の4ブロックで構成されます。Anthropicのプロンプト設計ガイドは、複数の要素を含む入力ではXMLタグがClaudeによる解釈の助けになるとしています。

まず実行する

インストール不要で試せます。ほかに npm install -g repomix、yarn global add repomix、bun add -g repomix、brew install repomix でも導入できます。

cd your-project
npx repomix@latest

実行後のCLI出力には、サイズの大きいファイルの要約とセキュリティチェックの結果が出ます。要約に出す件数は --top-files-len で変えられます(既定は5件)。

出力されたファイルを渡すときのプロンプトは、次の例が参考になります。

This file contains all the files in the repository combined into one.
I want to refactor the code, so please review it first.

ほかに、ドキュメント生成・テストケース生成・品質評価向けのプロンプト例もあります。

出力を絞る: include・ignoreと設定ファイル

リポジトリ全体を渡すと、大半は問いに関係ないファイルです。絞り込みはコマンドラインか設定ファイルで行います。

# 対象を限定する
repomix --include "src/**/*.ts,**/*.md"
 
# 追加で除外する
repomix --ignore "**/*.log,tmp/"
 
# 特定ディレクトリだけをまとめる
repomix path/to/directory

対象ファイルをシェル側で選びたいときは、パスの一覧を --stdin で渡せます。git ls-files "*.ts" | repomix --stdin のように、gitやrgの結果をそのまま束ねられます。

除外パターンは複数の経路から入ります。

• .gitignore と .git/info/exclude(--no-gitignore で無効化)
• .ignore(--no-dot-ignore で無効化)
• 組み込みの除外パターン(node_modules、.git、バイナリなど。--no-default-patterns で無効化)
• .repomixignore(Repomix専用。書式は .gitignore と同じ)
• 設定ファイルの ignore.customPatterns、またはコマンドラインの -i, --ignore

優先順位は、カスタムパターンが最上位です。次に各種ignoreファイル(深い階層のものが優先)、最後に組み込みパターンが来ます。バイナリファイルは中身が含まれませんが、パスはディレクトリ構造に載ります。

設定ファイルは repomix --init で repomix.config.json を作れます。指示文を末尾に付けたいときは、output.instructionFilePath に指示ファイルを指定します。

{
  "output": {
    "instructionFilePath": "repomix-instruction.md"
  }
}

指示文は出力ファイルの末尾に入ります。長い資料を先頭に置き、質問を末尾に置くとClaudeの応答品質が上がりうるという、Anthropic公式の長文入力のヒントに沿った配置です。

--compressとoutput.patternsでトークンを減らす

--compress を付けると、Tree-sitterによる解析で関数やクラスのシグネチャ、型の定義を残し、実装本体を落とします。実験的な機能扱いです。

repomix --compress
repomix --remote yamadashy/repomix --compress

全ファイルに一律で効くのが --compress です。ファイルごとに粒度を変えたいときは、設定ファイルだけにある output.patterns を使います。

{
  "output": {
    "compress": false,
    "patterns": [
      { "pattern": "docs/**/*", "compress": true },
      { "pattern": "website/**/*", "directoryStructureOnly": true }
    ]
  }
}

粒度は「全文」「圧縮」「ディレクトリ構造のみ」の3段階です。パターンは配列の順に評価され、最初に一致したものが勝ちます。両方のフラグを付けた場合は directoryStructureOnly が優先されます。CLIフラグはないので、設定ファイルで書く必要があります。

そのほかの削減オプションとして、--remove-comments、--remove-empty-lines、--truncate-base64 があります。

量を測る: トークンツリーと上限ガード

絞る前に、どこが重いかを見ます。--token-count-tree は、ディレクトリごとのトークン数を木の形で表示します。しきい値を渡すと、その値以上のファイルだけが出ます。

repomix --token-count-tree 1000

渡し先のコンテキストを超えたくないときは、--token-budget <number> が使えます。出力トークンが指定値を超えると非ゼロの終了コードで失敗します。ファイル自体は生成され、超過は終了コードだけで知らされます。CIやエージェントのワークフローで上限を見張る用途が想定されています。

アップロード上限があるツールへ渡すなら、--split-output 1mb のように分割できます。同じトップレベルディレクトリのファイルは同じ分割ファイルにまとまり、1つのファイルが複数に割れることはありません。

なお、トークン数の既定の数え方は o200k_base(GPT-4o用)です。--token-count-encoding で変えられますが、Claude自身の計測値とは限らないので、数値は目安として扱います。

Claude Codeに渡す3つの方法

標準出力をclaude -pへパイプする

Repomixは --stdout で結果を標準出力へ書けます。この出力は別のCLIへパイプできます。Claude Codeの claude -p はパイプで渡した内容を処理できるので、この2つを組み合わせた形です。

repomix --stdout --compress | claude -p "このコードベースの構成を説明して"

1回きりの質問や、スクリプトからの呼び出しに向きます。--stdout ではログが出力されません。

MCPサーバーとして登録する

Repomixは --mcp でMCPサーバーとして動き、Claude Codeには次のコマンドで登録します。

claude mcp add repomix -- npx -y repomix --mcp

登録すると、pack_codebase(ローカルディレクトリのパック)、pack_remote_repository(GitHubリポジトリのパック)、attach_packed_output(生成済みファイルの取り込み)、read_repomix_output(行範囲を指定した読み出し)、grep_repomix_output(正規表現検索)といったツールが使えます。--sandbox を付けると、ファイル読み取りツールが作業ディレクトリ配下に限定されます。

pack_codebase の compress 引数について、READMEは「grep_repomix_output で少しずつ取り出せるので、通常は不要」と書いています。つまりMCP経由では、全文をコンテキストへ流し込まず、検索して必要な部分だけを取る使い方が想定されています。MCPのツール定義がコンテキストに載る量はMCPのトークンオーバーヘッドを抑える設定で扱っています。

公式プラグインを入れる

Claude Code向けの公式プラグインもあります。

/plugin marketplace add yamadashy/repomix
/plugin install repomix-mcp@repomix
/plugin install repomix-commands@repomix
/plugin install repomix-explorer@repomix

repomix-mcp がMCPサーバー、repomix-commands がスラッシュコマンド、repomix-explorer が自然文でリポジトリを調べるスキルです。推奨の土台は repomix-mcp です。

Claude Codeが自分で読む場合との使い分け

Claude Codeは、ファイルの検索、正規表現での内容検索、ファイルの読み込みを自分のツールで行います。公式の説明では、エラー出力を読み、関連ファイルを探し、読んで理解するという流れで進みます。読ませるファイルを事前に指定する必要はありません。

一方、コンテキストウィンドウには会話履歴・ファイルの中身・コマンド出力などが入ります。パックしたリポジトリを丸ごと流し込めば、その分だけ席を取ります。何が席を取っているかは /context で確認できます。内訳の見方はコンテキストウィンドウを可視化する方法にあります。

判断の目安を表にします。

手元のリポジトリを開発する場面では、Claude Code標準の検索と読み込みで足りることが多いはずです。これは公式の記述から導いた見立てで、実測した比較ではありません。

GitHub連携が不調でリポジトリをチャットに読ませられないときに、Repomixの出力で代替する運用はGitHub連携の不具合の回避策にも出てきます。

つまずきやすい点

Secretlintが検出するのは、既知の認証情報の形式に合致するファイルです。検出されたファイルは一覧で警告されますが、独自形式のトークンがすり抜けないとは限りません。外部に渡す前に出力ファイル自体を確認する運用が安全です。--no-security-check を付けるとチェックそのものが無効になります。

リモートの設定ファイルは既定で読まれません。repomix.config.* はコードとして実行される場合があるため、--remote で取得したリポジトリの設定は既定で読み込まれません。信頼する場合は --remote-trust-config を付けます。対話端末では内容が表示され、確認を求められます。「次回以降は聞かない」を選んでも、ピン留めされるのはエントリの設定ファイルのハッシュだけです。そこからimportされる別ファイルは対象外です。

--remote と --config を併用するときは、--config に絶対パスが必要です。

ウォッチモードはローカル専用です。--watch は、--remote、--stdout、--stdin、--split-output、--skill-generate、--copy と併用できません。

ファイルの並びは変更頻度順です。既定では、gitの変更が多いファイルが前に来ます。順序を変えたくないときは --no-git-sort-by-changes を使います。

出力がコンテキストに収まらないと、受け取る側でトークン上限のエラーになります。ファイル単体が大きい場合の対処はexceeds maximum allowed tokensエラーの原因と対処法にあります。Repomix側では、先に --token-count-tree で重いディレクトリを見つけ、--ignore か output.patterns で落とす流れです。