codexa

Codexa

コードを理解し、変更の影響を把握し、根拠を確認しましょう。

Codexa は、開発者や AI コーディングアシスタントが、より多くのコンテキストと少ない推測でリポジトリを扱えるよう支援します。コードのローカルマップを作成し、ファイルとその依存関係やテストを結び付け、提案された変更や完了した変更について、読みやすいレポートを生成します。

プロジェクトのマップと変更チェックリストとしてお考えください。人間であれ、コーディングアシスタントであれ、作業を進めるのはあくまで利用者です。Codexa は、トラックで橋を渡る前に確認しておきたい箇所を示します。

ターミナルから、Codex、Claude Code、またはほかの互換性のあるコーディングアシスタントと一緒に使えるほか、プルリクエストのレビューを支援するために GitHub Actions でも使用できます。コア機能には API キー、ホスト型アカウント、データベースは不要です。Codexa は無料で、MIT ライセンスです。AI アシスタントや任意のホスト型サービスには、それぞれ独自の要件や費用があります。

使い始める · アシスタントを接続する · 日々の使い方 · GitHub でのレビュー · トラブルシューティング · 完全なリファレンス

メンテナーからのお知らせ： Codexa は、1 人のメンテナーが空き時間に保守する、焦点を絞ったプロジェクトです。返信には数日から数週間かかる場合があります。大規模な変更を行う場合は、PR を作成する前にご相談ください。コントリビューションをご覧ください。

実際には何をするのですか？

質問	Codexa が提供するもの
「この動作はどこにありますか？」	関連するファイルや関数、正確なテキストの一致箇所と、必要に応じて関連コードを示します。
「これを変更すると、何が壊れる可能性がありますか？」	影響を受ける可能性のある、関連するコードやテストのマップを示します。
「何をテストすればよいですか？」	変更したファイルや既知の関係に基づいて、確認項目を提案します。
「作業は計画の範囲内に収まりましたか？」	保存済みの計画と実際の編集内容を比較し、予想外の変更も含めて示します。
「この引き継ぎを裏付ける根拠は何ですか？」	プルーフカードを作成します。計画、検証の根拠、残っている不足事項をまとめたものです。
「このプルリクエストでは何が変更されていますか？」	変更レシートを作成します。コミットされた変更、考えられる影響、レビューの指針をまとめたレポートです。

たとえば、ログインタイムアウトを変更すると、1 つの数値以外にも影響する可能性があります。Codexa は、設定の場所やそれを使用するコードを特定し、関連するテストを提案して、合意した範囲外の編集にフラグを立てるのに役立ちます。検出結果は、リポジトリ内で読み取り、関連付けられる情報に依存します。あらゆる実行時の動作を予測できるわけではありません。

Codexa はコンテキストとチェックを提供します。編集を行うのはエディターやアシスタントであり、動作するかどうかを確認するのはプロジェクトのテストです。良好に見えるレポートは有用な根拠ですが、あらゆる問題を防ぐものではありません。

クイックスタート

必要なのは Node.js 22 以降、npm（Node.js に同梱）、Git、そしてローカルの Git リポジトリ（調査するプロジェクトフォルダー）です。ターミナルのコマンドを使うために、Codexa 自体をクローンしたり、AI アシスタントをインストールしたりする必要はありません。

1. インストール

ターミナルで次のコマンドを実行します。

node --version
git --version
npm install -g @mirnoorata/codexa
codexa --version

2. プロジェクトで試す

/path/to/project を、リポジトリの実際のフォルダパスに置き換えてください。パスにスペースが含まれる場合は、引用符で囲んでください。以下の例では、. は「このフォルダ」を意味します。

cd /path/to/project
codexa index .
codexa repo-map .

index はリポジトリを読み込み、ローカルマップを作成します。repo-map は、ランキングされたファイルとモジュールを表示します。このターミナルだけで完結する方法では、アシスタントの設定は不要です。

プロジェクトに関連する質問をしてみましょう。

codexa search . --query "login timeout"

これはクエリの例であり、組み込みのデモではありません。結果はコードによって異なります。継続して利用する場合は、生成ファイルに関するガイダンスに従い、以下からアシスタントの設定方法を選んでください。

グローバルインストールをしない場合　コマンドの先頭に npx -y @mirnoorata/codexa を付けてください。たとえば、npx -y @mirnoorata/codexa index /path/to/project のようにします。npm がパッケージをダウンロードする場合がありますが、デフォルトのインデックス作成はローカルで実行されます。

コーディングアシスタントを接続する

Codexa は MCP（Model Context Protocol） を使用します。これは、AI アシスタントが外部ツールに情報を問い合わせるための接続方法です。アシスタントがモデルを実行し、Codexa がリポジトリのコンテキストを提供します。選択したアシスタントは、別途インストールしてサインインしてください。

Codex

プロジェクトフォルダで次を実行します。

codexa init . --agents-md
codexa session-start .

これにより、インデックスが作成され、Codexa サーバーが .codex/config.toml に追加され、Codex の起動時・編集時フックがインストールされ、管理対象の小さなワークフローブロックが AGENTS.md に追加されます。エージェントの指示を自分で管理する場合は、--agents-md を省略してください。Codexa プラグインがすでに MCP 接続を提供している場合は、同じリポジトリに対してサーバーを二重に登録しないでください。

同じプロジェクトを Codex で開くか再読み込みし、プロンプトが表示されたら信頼してください。プロジェクト単位の MCP 設定は、信頼済みのプロジェクトでのみ読み込まれます。Codex CLI では、/mcp でアクティブな接続を確認できます。詳しくは公式の MCP セットアップガイドをご覧ください。

session-start のチェックが成功すると、確認可能なセットアップとインデックスの状態が確認できますが、すでに実行中のアシスタントがサーバーを読み込んでいることまでは証明できません。

Windows： Windows ネイティブで MCP のみを設定する場合は、codexa init . --agents-md --no-hooks を使用してください。生成されるシェルフックには、WSL などの POSIX 環境が必要です。macOS と Linux では、上記の標準コマンドを使用できます。

Claude Code

最も簡単に接続するには、次を実行します。

codexa init . --claude --claude-md --no-hooks
codexa session-start .

これにより、サーバーエントリーが .mcp.json に、ワークフローのガイダンスが CLAUDE.md にも書き込まれます。そのリポジトリで Claude Code を再起動し、プロンプトが表示されたらプロジェクトの MCP サーバーを承認してください。--no-hooks は Codexa の Codex フックを無効にします。この設定では Claude のツールと指示が利用できますが、Claude フックやスラッシュコマンドは利用できません。

起動時のガイダンス、レビュー用フック、/codexa-plan や /codexa-review などのコマンドが必要ですか？同梱のClaude Code プラグインを使用してください。サーバーの重複を避けるため、プラグインか、上記の .mcp.json による接続のどちらかを選んでください。

その他の MCP クライアント

クライアントの MCP 設定で、ローカルコマンドサーバーを設定します。

{
  "mcpServers": {
    "codexa": {
      "command": "codexa",
      "args": ["serve", "/path/to/project", "--auto-refresh"]
    }
  }
}

パスを置き換え、外側の設定形式をクライアントに合わせて調整してください。クライアントから codexa を見つけられ、リポジトリにアクセスできる必要があります。クライアントがサーバーを起動します。serve は対話型のチャットコマンドではありません。

新規インストールで利用できるツールは、search、change_plan、capabilities の3つです。この小さなメニューは意図的なものです。capabilities を使うと、残りの操作にもアクセスできます。クライアントで全操作を一覧に直接表示する必要がある場合は、init または serve に --tools full を指定してください。

デフォルトの接続ではローカルプロセスを使用します。オプションの HTTP トランスポートがバインドするのはローカルマシンのみです。Codexa は公開リモートサーバーを提供していません。

日々のワークフロー

不確実性の解消に役立つ場合は Codexa を使いましょう。 対象が分かっているファイルへの小さな修正なら、直接確認してプロジェクトの通常のテストを実行するだけでよい場合があります。カンマを変更するのに形式ばった手順は必要ありません。複数のファイルにまたがる変更では、計画とレビューがより役立ちます。

コーディングアシスタントへの依頼としては、次のようなものが有用です。

ログインのタイムアウトがどこで処理されるか調べてください。対象や影響が不明確な場合は Codexa を使ってください。大幅な編集の前に、変更計画を保存してください。変更を加え、関連するチェックを実行し、計画に照らして結果をレビューしてください。未検証の項目があれば教えてください。

このワークフローは自分で実行することもできます。この例では、リポジトリに src/auth.ts があることを前提としています。実際のファイル名とタスクに置き換えてください。

codexa change-plan . --task "Adjust the login timeout" --file src/auth.ts --task-id login-timeout --save-snapshot

計画を読み、編集を行い、プロジェクトに適したチェックを実行してください。その後、編集内容がローカルの変更として表示されている間に、コミットする前に作業をレビューします。

codexa post-edit-review . --task-id login-timeout

実際に実行したチェックは、--ran-command を使って報告してください。たとえば、npm test がプロジェクトで実際に使われているチェックで、実行した場合に限り、次のようにします。

codexa post-edit-review . --task-id login-timeout --ran-command "npm test"

このフラグは実行したという申告を記録するものであり、コマンドを実行するものではありません。Codexa は、報告されたコマンドで関連する作業を網羅できるかを確認します。npm test || true のように失敗を隠すコマンドでは、評価されません。完全に捏造された報告を Codexa が検出することはできません。

正式な引き継ぎには、codexa prove . --task-id login-timeout を使うと、保存された計画、利用可能な証拠、未解決の不足点をまとめられます。引き継ぎに必要な場合は、実際のコマンド実行報告または選択した検証成果物を添えてください。

起動時や編集時のフックを使うと手作業を減らせますが、それらによるレビューは、実際のテスト証拠を確認したうえで最後に行うレビューの代わりにはなりません。ワークフロー、前提条件、再試行の制御については、リファレンスをご覧ください。

便利なコマンド

プロジェクトのルートから、自分のファイル名と質問を使って実行してください。

コマンド	目的
codexa search . --query "password reset"	調査の出発点を見つけます。
codexa explain . --file src/auth.ts	ファイルとその関連箇所を確認します。
codexa impact . --file src/auth.ts	変更によって影響を受ける可能性がある範囲を確認します。
codexa diff-impact .	未コミットの変更による影響を確認します。
codexa test-plan . --diff	現在の編集内容に対するテストの提案を取得します。
codexa status .	インデックスを更新せずに、その最新状態とパーサーのエラーを確認します。
codexa watch .	セッション中にインデックスを最新の状態に保ちます。Ctrl+C で停止します。
codexa doctor .	ローカルのセットアップに関する問題を診断します。

ほとんどのコンテキストコマンドは、古くなったインデックスを自動的に更新します。その他のオプションについては、codexa --help、codexa <command> --help、またはコマンドリファレンスをご覧ください。

プルリクエストをレビューする

Codexa は、AI アシスタントなしで、コミット済みブランチのレポートを生成できます。origin/main がローカルで利用可能な状態で、そのブランチをクリーンなチェックアウトから実行してください。

git fetch origin
codexa review . --base origin/main --head HEAD
codexa review . --base origin/main --head HEAD --format json

リポジトリで別のベースブランチを使っている場合は、origin/main を置き換えてください。Codexa は、ブランチ間の共通祖先以降の変更を比較します。HEAD はチェックアウト済みのコミットと一致している必要があり、インデックスもそのクリーンなチェックアウトを反映している必要があります。

同じレビューを GitHub Actions に追加するには、次のようにします。

codexa init . --ci

生成された .github/workflows/codexa-review.yml を確認し、通常の PR 手順に従ってコミットしてください。このワークフローは PR の正確な head をチェックアウトし、リポジトリへの読み取り専用権限を使い、結果を Actions のサマリーと注釈に出力します。PR コメントの投稿や、プロジェクトのテストの実行は行いません。既存の CI はそのまま維持してください。

デフォルトの observe モードでは、検出事項があってもブロックせずに報告します。warn モードでは警告の注釈が追加されます。明示的な fail モードでは、ローカル計画とのずれ、要求されたローカル計画を利用できない場合、または報告されたコマンドの失敗によって処理がブロックされることがあります。提案されたテストが未実行であることだけを理由に、レビューが失敗することはありません。入力が無効な場合やセットアップエラーがある場合は、どのモードでも失敗する可能性があります。

計画の比較、信頼性の限界、CI のオプションについては、コミット済み変更レシートをご覧ください。

リポジトリに書き込まれる内容

場所	内容	通常の Git での扱い
.codex/codebase/	生成されたマップ、関係性、インデックス。	無視します。チェックアウトごとに再生成します。
.codex/cache/	保存されたプラン、セッションメモ、レビュー状態、任意のキャッシュ。	無視します。ローカルの証拠を非公開に保ちます。
.codex/static-analysis/	インポートされた、または明示的に生成されたスキャナーレポート。	無視します。
.codex/config.toml、.codex/hooks.json	init による Codex の接続設定とフック。	通常はローカルに置きます。意図的に共有します。
.mcp.json	要求された場合の Claude 接続設定。	共有する前にパスと既存のサーバーを確認します。
AGENTS.md、CLAUDE.md	対応するフラグを指定した場合のみ追加される、管理対象のワークフローブロック。	チームに役立つ場合は共有します。
.codex/policies/	証明カード用の任意の JSON ポリシー。	チームのポリシーを表す場合は共有します。
.github/workflows/codexa-review.yml	任意の GitHub Actions レビュー。	有効にするにはコミットします。

生成された以下のパスをプロジェクトの .gitignore に追加してください（Codexa は自動で追加しません）。

.codex/codebase/
.codex/cache/
.codex/static-analysis/

MCP の設定とフックが自分のマシンだけで使うものであれば、それらのファイルも無視してください。チームがポリシーやセットアップスクリプトを管理している場合は、.codex/ ディレクトリ全体を無視しないでください。接続設定をコミットする前に、生成された起動パスを確認してください。init は、すでに追跡されているファイルに対してポータブルな接続設定をサポートしています。チームメンバーごと、および新しいチェックアウトごとに、それぞれインストールとインデックス作成が必要です。

init を再実行すると、Codexa の管理対象設定が更新され、他の MCP サーバーのエントリーは保持されます。任意の指示ブロックは、Codexa のマーカー間の領域のみを置き換えます。--policy-pack は、既存のポリシーファイルを置き換えずに、ローカルの証明ポリシーを作成します。ポータビリティと管理対象ファイルの動作については、 セットアップリファレンス を参照してください。

サポート、プライバシー、制限事項

• 言語サポート： TypeScript、JavaScript、Python では、最も詳細な解析が行われます。Rust、Go、Java では、宣言と関係性の解析がより簡易になります。その他の認識対象ファイルからは、限定的な情報が取得されます。外部シンボルレポートで対象範囲を拡張できますが、すべての言語をコンパイラーレベルで完全に理解するわけではありません。
• 対象範囲： Codexa は、無視対象でない新しいファイルを含む、Git から確認できる対応ファイルを読み取ります。一般的な生成物・依存関係のディレクトリと、サイズが 2 MiB を超えるソースファイルはスキップします。影響分析でたどる関係性は最大 3 ステップです。動的な動作や大規模なリポジトリでは、追加の調査が必要になる場合があります。
• プライバシー： デフォルトでは、インデックス作成とクエリはモデルを呼び出さずにローカルで実行されます。AI アシスタントに返されるコンテキストは、そのアシスタントのデータポリシーに従って取り扱われます。任意の OpenAI 埋め込みを有効にすると、選択したソーステキストとクエリが OpenAI に送信されます。任意の TypeSafe 再ランキングを有効にすると、クエリと候補となるソースの抜粋が TypeSafe に送信されます。どちらもデフォルトでは無効です。
• 実行： MCP ツールは Codexa の生成状態を更新できますが、ソースファイルの編集や検証コマンドの実行は行いません。任意の AutoVerify を使うと、ユーザーが明示的に設定した後で、編集フックにより選択したローカルチェックを実行できます。デフォルトでは無効であり、サンドボックスではありません。
• 証拠： 直接観察された事実、推測された関係性、推測には、それぞれ異なる信頼度ラベルが付けられます。報告された検証結果と AutoVerify による実行は区別されます。証明カードには証拠と不足事項が記録されますが、コードが正しい、または安全であることを保証するものではありません。

運用が必要な Web ダッシュボードやホスト型インデックス作成サービスはありません。任意の埋め込み、TypeSafe、言語サーバーによる支援、スキャナーのインポート、セッションメモリ、AutoVerify については、 リファレンス に記載されています。

トラブルシューティング

症状	確認する内容
codexa が見つからない	ターミナルを開き直し、npm のグローバル実行ファイル用ディレクトリが PATH に含まれていることを確認するか、代わりに npx を使用してください。
ネイティブ依存関係のビルド時にインストールが失敗する	Node.js が 22 以上であることを確認してください。ビルド済みバイナリが利用できない場合、Tree-sitter の依存関係にはプラットフォーム固有のネイティブビルドツールが必要になることがあります。
アシスタントに Codexa が表示されない	codexa doctor . を実行し、リポジトリのパスを確認してから、アシスタントでそのプロジェクトを再読み込みしてください。Codex では、プロジェクトの信頼設定と /mcp を確認してください。
「Current-thread MCP: unverified」と表示される	CLI ではアシスタントのライブ接続を検査できません。アシスタントで有効なサーバーの一覧を確認してください。この表示だけでインストールに失敗したとは限りません。
インデックスがない、古い、または一致しない	実際のチェックアウトで codexa index . を実行してください。別のワークツリーのインデックスをコピーしないでください。
パーサーエラーや関係性の欠落がある	codexa status .、言語サポート、無視対象のファイル、ソースサイズの上限を確認してください。劣化した結果は、証拠として不完全です。
コミット済みのレビューを実行できない	ローカルの変更を解消し、指定された head をチェックアウトして、インデックスを再構築してください。コミット前の編集には post-edit-review を使用してください。
ネイティブ Windows でフックが失敗する	MCP のみで使用する場合は --no-hooks を付けて init を再実行するか、シェルフックには WSL を使用してください。

Codexa の更新または削除

npm install -g @mirnoorata/codexa@latest で更新し、各リポジトリで選択した init コマンドを再実行して、アシスタントの接続を再読み込みしてください。--claude や --agents-md などのオプションのフラグを再利用すると、それらの連携機能を更新できます。通常の init では既存のツールプロファイルが保持されます。切り替えるには --tools core を使用してください。

Codexa を削除するには、まずサーバー／プラグインを無効にし、Codexa が管理する 設定項目、フック、指示ブロックのみを削除してください。他のツールの設定は保持してください。 その後、npm uninstall -g @mirnoorata/codexa を実行します。生成されたインデックスは削除できます。 .codex/cache/ を削除する前に、保持したいプランや証拠をエクスポートしてください。 CI ワークフローを有効にしている場合は、それも削除してください。すべてを一括で削除する コマンドはありません。

Codex のプロジェクトワークツリーとローカルセットアップ

Git ワークツリーは、同じリポジトリの別のチェックアウトです。各ワークツリー内で codexa init を実行し、そのコードに合った設定とインデックスを用意してください。ワークツリーを頻繁に作成する場合は、 プロジェクトのセットアップでこの手順を自動化してください。

Codexa 自体を開発する場合、このリポジトリには Codex のローカル環境とブートストラップ スクリプトが含まれており、固定された依存関係のインストール、パッケージのビルド、ワークツリーのセットアップ確認を行います。これらのスクリプトはこのリポジトリ専用です。 一般ユーザーがコピーする必要はありません。ワークツリーと復旧ガイドを参照してください。

貢献者と興味のある方へ

Codexa のエンジンは TypeScript で書かれています。主な構成は次のとおりです。

Repository → local index → relevant context and change analysis → evidence report

領域	参照先
インストールとコマンド	src/init.ts、src/cli.ts
ファイルの検出、解析、関係性	src/indexer/、src/parser/、src/resolver.ts、src/graph.ts
検索、プラン、レビュー、テストの証拠	src/query/、src/prove.ts
アシスタントツールとローカルセッションの状態	src/mcp/、src/session-memory/
ホストとの連携と CI	plugins/codexa/、integrations/claude-code/、action.yml
検証とパッケージ化	tests/、scripts/

ソースからビルドするには：

git clone https://github.com/mirnoorata/codexa.git
cd codexa
npm ci
npm run build
npm link
npm run check

npm link を実行すると、このチェックアウトの codexa コマンドをローカルで使用できるようになります。node dist/cli.js を使う場合は不要です。完全なチェックでは、パッケージのビルドと型チェック、衛生状態と公開パスの確認、テストの実行、起動時コンテキストの予算チェックを行います。貢献ガイドとアーキテクチャリファレンスを参照してください。

公開証拠

このリポジトリには、再現可能な検索評価とエージェントの A/B テスト用ハーネスが含まれています。これらは異なる点を測定します。有用なコンテキストを見つけられることだけでは、アシスタントがタスクをより速く、より適切に完了できる証明にはなりません。アーカイブされた小規模なエージェントのパイロットでは、タスク完了の改善がないまま、追加のオーバーヘッドが確認されました。これは、あらゆる状況でコストが削減されることを示す証拠ではありません。結果、日付、注意事項、再現コマンドは公開証拠に記録されています。

GitHub リリースのタイムライン

GitHub Releases は、現在のプロジェクトの可視化されたタイムラインです。メンテナーは通常、リリースの自動化を使用します。明示的に要求された手動の npm run release:github は、変更履歴形式の概要、変更領域の概要、復元手順、前の状態に戻すための PR コマンドを生成します。手動リリースのリファレンスを参照してください。

リリースの自動化

Release Please は、リポジトリの GITHUB_TOKEN を使用して、バージョンと変更履歴の PR、および GitHub Releases を準備します。main へのマージごとに npm に公開するわけではありません。通常の変更が先に取り込まれ、npm への公開はリリースの公開後に行われます。リリースの自動化と公開リリースのチェックリストを参照してください。

npm パッケージの公開

メンテナーのワークフローでは、GitHub Actions と npm の信頼された公開を通じて公開します。Release Please の明示的なディスパッチ後、または GitHub Release の手動公開時（release: published）に実行され、タグのプッシュだけでは実行されません。リリースとセキュリティのチェック後、ワークフローは次を実行します。

npm publish --registry https://registry.npmjs.org --access public --tag latest --provenance --ignore-scripts

パッケージの利用者は、上記のインストール手順だけで十分です。メンテナーは、認証と復旧の手順を公開リファレンスで確認できます。

ヘルプとライセンス

質問にはDiscussionsを、再現可能なバグにはIssuesをご利用ください。脆弱性は非公開のセキュリティアドバイザリから報告してください。SECURITY.mdを参照してください。

Codexa はMITライセンスのもとで公開されています。