0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@rino_yume(rino yume)

WSLでCodex CLI + context-modeを使う：MCPプラグインでAIコーディングを効率化する

0
Last updated at Posted at 2026-06-16

WSLでCodex CLI + context-modeを使う：MCPプラグインでAIコーディングを効率化する

1.はじめに

AIコーディングエージェントを使って開発していると、次のような問題が起きやすいです。

問題点

  • ソースコード全体を読ませると、コンテキストを大量に消費する
  • 長いログやビルド結果でTokenを浪費する
  • 会話が長くなると、AIが作業の前提を忘れやすい
  • PyInstaller、pytest、FastAPI、GUIアプリなどのログ解析が重い
  • 大規模プロジェクトでは「どのファイルを直していたか」が曖昧になりやすい

そこで、WSL上で Codex CLI + context-mode を組み合わせ、context-modeを MCPプラグイン として使う構成を整理します。

context-modeは「AIに全部読ませる」のをやめて、「AIに必要な情報だけ渡す」ための仕組みです。
大規模なPython GUIアプリやWeb GISアプリを何度も修正していく開発では、かなり有効な考え方だと思います。

ここでは、WSL上でCodex CLIとcontext-modeを使う場合の考え方、導入方法、処理方法、運用方法、注意点を簡潔にまとめます。

私はAIのプロではありませんので、間違った情報もあるかもしれません。
あくまでも参考資料として読んでくださいね。

2.context-modeとは

context-modeは、AIコーディングエージェント向けの コンテキスト節約用MCPサーバー／プラグイン です。

AIに巨大なログやファイルをそのまま読ませるのではなく、ローカル側で次の処理を行い、必要な情報だけをAIに渡します。

  • ファイルやディレクトリの索引化
  • ログやソースコードの検索
  • コマンド実行結果の要約
  • 大きな出力のコンテキスト流入抑制
  • セッション情報の保持補助

つまり、context-modeは次の考え方で使います。

AIに全部読ませない
↓
context-modeで索引化・検索・要約する
↓
必要な情報だけAIへ渡す

3.MCPとは

MCPは Model Context Protocol の略です。

AIエージェントから外部ツール、ファイル、データベース、検索、ローカルコマンドなどを呼び出すための共通的な仕組みです。

Codex CLIでは、MCPサーバーを設定することで、AIエージェントから外部ツールを呼び出せるようになります。

context-modeは、このMCPサーバーとして動作します。

4.なぜWSL上で使うのか

Windows + WSL環境では、PowerShell側とWSL側で実行環境が分かれます。

Codex CLIをWindows側で起動し、context-modeをWSL側に入れると、PATHやファイルパスの違いにより、うまく動かないことがあります。

そのため、この記事では次の方針にします。また、私がubuntu環境に慣れているのも一因です。

Codex CLI      → WSL側に入れる
context-mode   → WSL側に入れる
Node.js/npm    → WSL側に入れる
設定ファイル   → WSL側の ~/.codex に置く
Codexの起動    → WSLターミナルから行う

WSL上で完結させることで、パスや実行環境のズレを減らせます。

5.全体構成

Windows 11
  └─ WSL2 / Ubuntu
       ├─ Node.js / npm
       ├─ Codex CLI
       ├─ context-mode
       │    ├─ ctx_index
       │    ├─ ctx_search
       │    ├─ ctx_execute
       │    └─ ctx_stats
       │
       └─ 開発プロジェクト
            ├─ src/
            ├─ tests/
            ├─ logs/
            ├─ AGENTS.md
            └─ .codex/

6.前提環境

この記事では以下を想定します。私はanyenv環境を使っていますが、ここではWSL環境に直接環境を作ります。

Windows 11
WSL2
Ubuntu 24.04系
Codex CLI
Node.js 22系以上
context-mode

6.1. WSL側の基本パッケージを入れる

WSLのUbuntuを開き、基本パッケージを入れます。

sudo apt update
sudo apt install -y git curl build-essential

6.2. Node.jsを入れる

context-modeはNode.js系のツールです。

WSL側にNode.jsを入れます。
ここではnvmを使います。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc

Node.jsのLTS版を入れます。

nvm install --lts
nvm use --lts

確認します。

node -v
npm -v

context-modeでは新しめのNode.jsが必要になるため、Node.js 22系以上を使うのが無難です。

6.3. Codex CLIを入れる

Codex CLIをWSL側にインストールします。

公式インストーラを使う場合は以下です。

curl -fsSL https://chatgpt.com/codex/install.sh | sh

npmで入れる場合は以下です。

npm install -g @openai/codex

どちらか一方で問題ありません。

インストール後、確認します。

codex --version

起動します。

codex

初回起動時は、ChatGPTアカウントまたはAPIキーで認証します。

6.4. context-modeを入れる

WSL側にcontext-modeを入れます。

npm install -g context-mode

確認します。

which context-mode
context-mode --version

context-mode が見つからない場合は、npmのグローバルパスが通っていない可能性があります。

npm root -g
npm bin -g

必要に応じて ~/.bashrc にPATHを追加します。

6.5. Codex pluginとしてcontext-modeを入れる

context-modeは、Codex CLI向けにpluginとして導入できます。

まず、Codexにcontext-modeのmarketplaceを追加します。

codex plugin marketplace add mksglu/context-mode

その後、Codexのplugin UIからcontext-modeをインストールします。

次に、Codexの設定ファイルを編集します。

mkdir -p ~/.codex
nano ~/.codex/config.toml

以下を追加します。

[features]
plugin_hooks = true
hooks = true

Codex CLIを再起動します。

codex

Codex内で確認します。

ctx stats

ctx stats が応答すれば、context-modeのMCPサーバーはCodexから見えています。

ただし、ctx stats はMCPサーバーが見えていることの確認です。
hookが実際に承認・実行されているかは別なので、Codexからhook承認を求められた場合は、内容を確認して信頼します。

6.6. 手動MCP登録する場合

plugin方式がうまく動かない場合は、手動でMCPサーバーとして登録します。

~/.codex/config.toml を開きます。

nano ~/.codex/config.toml

以下を追加します。

[features]
hooks = true

[mcp_servers.context-mode]
command = "context-mode"

[mcp_servers.context-mode.env]
CONTEXT_MODE_PLATFORM = "codex"

この設定で、Codex CLIからcontext-modeをMCPサーバーとして起動できます。

6.7. hooks.jsonを作成する

手動MCP登録の場合は、hook設定も作成します。

nano ~/.codex/hooks.json

以下を記載します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "local_shell|shell|shell_command|exec_command|Bash|Shell|apply_patch|Edit|Write|grep_files|ctx_execute|ctx_execute_file|ctx_batch_execute|ctx_fetch_and_index|ctx_search|ctx_index|mcp__",
        "hooks": [
          {
            "type": "command",
            "command": "context-mode hook codex pretooluse"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "context-mode hook codex posttooluse"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "context-mode hook codex sessionstart"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "context-mode hook codex precompact"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "context-mode hook codex userpromptsubmit"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "context-mode hook codex stop"
          }
        ]
      }
    ]
  }
}

Codex CLIを再起動し、確認します。

codex

Codex内で以下を実行します。

ctx stats

6.8. AGENTS.mdを配置する

context-modeを有効に使うには、Codexに「大きなログやファイルを直接読まず、context-modeを優先する」方針を伝えるとよいです。

context-mode付属のCodex向け AGENTS.md をプロジェクトにコピーします。

cd ~/projects/my_app

CM_ROOT="$(npm root -g)/context-mode"
cp "$CM_ROOT/configs/codex/AGENTS.md" ./AGENTS.md

全プロジェクト共通で使いたい場合は、以下のようにします。

CM_ROOT="$(npm root -g)/context-mode"
cp "$CM_ROOT/configs/codex/AGENTS.md" ~/.codex/AGENTS.md

プロジェクト個別に方針を書きたい場合は、プロジェクトルートに AGENTS.md を置くのがおすすめです。

例です。

# AGENTS.md

## 作業方針

- 巨大なログやソース全文を直接読まない
- まず context-mode の ctx_index / ctx_search を使う
- 関係するファイルだけを確認してから修正する
- 実行ログは要約して原因を整理する
- 修正前に変更方針を説明する
- 修正後はテストまたは起動確認を行う

6.9. 基本的な処理方法

作業対象のプロジェクトへ移動します。

cd ~/projects/my_app
codex

まずソースを索引化します。

ctx index src

プロジェクト全体を対象にする場合は以下です。

ctx index .

特定の処理を検索します。

ctx search "PySide6 3D表示"

ctx search "PyInstaller error"

ctx search "FastAPI DuckDB endpoint"

ログを解析したい場合は、ログフォルダを索引化します。

ctx index logs
ctx search "Traceback"

6.10. Codexへの依頼例

Codexには、最初に次のように依頼すると使いやすいです。

このプロジェクトではcontext-modeを使ってください。
巨大なログやソース全文を直接読むのではなく、
ctx_index、ctx_search、ctx_execute、ctx_execute_file を優先してください。
まず src を索引化し、関係するファイルだけを調査してください。

修正依頼の例です。

srcをctx_indexで索引化してから、
3D表示に関係する処理をctx_searchで調べてください。
その後、必要なファイルだけを確認して修正方針を提案してください。

ログ解析の例です。

logsをctx_indexして、TracebackとModuleNotFoundErrorを検索してください。
原因を整理して、修正すべきファイルと修正案を出してください。

6.11. 運用方法

作業開始時

1. WSLターミナルを開く
2. プロジェクトへ移動
3. codexを起動
4. ctx statsで確認
5. srcやlogsをctx index

調査時

全文を読ませる前にctx_searchする
ログを貼る前にlogsをctx_indexする
大きなJSONやCSVはctx_executeで集計する

修正時

関係ファイルだけを読ませる
修正後にテストを実行する
テスト結果はcontext-modeで要約する

定期的に確認するもの

ctx stats
ctx doctor

6.12. 実務での使いどころ

特に効果が出やすいのは、次のような場面です。
これは、私の開発環境と開発アプリの使い方ですので、それぞれ￥開発する物によると思います。

場面 context-modeの使い方
PySide6 GUIアプリの調査 ctx index src して関係箇所だけ検索
PyInstallerエラー解析 ctx index logs してTracebackを検索
FastAPI + DuckDB構成確認 API、DB、ルーティング関連を検索
OpenLayersの表示不具合 frontend関連ファイルを索引化して検索
pytest結果の確認 長いログを直接貼らず要約
大量JSON/CSVの確認 ctx_execute で集計して結果だけ見る

6.13. 注意点

PowerShell側から起動しない

WSLで使う場合は、PowerShellではなくWSLターミナルからCodexを起動します。

codex

PowerShell側で起動すると、Windows側のPATHや設定を使ってしまい、WSL側のcontext-modeと噛み合わないことがあります。

Node.jsのPATHに注意する

Codexから context-mode が見えない場合は、PATHを確認します。

which node
which npm
which context-mode

plugin方式でも、CodexプロセスからNode.jsが見えている必要があります。

WindowsパスとLinuxパスを混ぜない

WSLでは、なるべくLinux側のホーム配下で作業するのがおすすめです。

~/projects/my_app

Windows側のファイルを直接扱う場合は、

/mnt/c/WinPython/...

のようになります。

ただし、/mnt/c 配下はファイルI/Oが遅くなる場合があります。
開発作業は、可能であればWSL側のホーム配下に置くと安定します。

ctx statsだけではhook確認にならない

ctx stats が動けば、MCPサーバーは認識されています。

ただし、hookが有効になっているか、Codexに信頼されているかは別です。

plugin方式の場合は、Codexがcontext-modeのhook承認を求めることがあります。
内容を確認して、問題なければ信頼します。

context-modeは万能ではない

context-modeは、AIの代わりに自動で全部直してくれるツールではありません。

役割は次の通りです。

大量情報を索引化する
必要な情報を検索する
ログや出力を要約する
コンテキスト消費を減らす

最終的な設計判断、修正内容の確認、動作確認は、人間側でもチェックする必要があります。

機密情報に注意する

context-modeはローカルでファイルやログを扱います。

ログに以下のような情報が含まれている場合は注意します。

  • APIキー
  • アクセストークン
  • パスワード
  • 個人情報
  • 社外秘の設定値

必要に応じて、ログをマスクしてから扱います。

7.まとめ

WSL上で Codex CLI + context-mode を使う場合のポイントは次の通りです。

Codex CLI + context-mode を使うポイント

  • Codex CLIはWSL側に入れる
  • context-modeもWSL側に入れる
  • Node.js/npmもWSL側に入れる
  • CodexはWSLターミナルから起動する
  • 設定は ~/.codex/config.toml に書く
  • 巨大ログやソース全文は直接読ませず ctx_index / ctx_search を使う

context-modeをMCPプラグインとして使うことで、AIコーディング時のコンテキスト消費を抑えながら、大きなプロジェクトや長いログを扱いやすくなります。

特に、私の開発環境であるPySide6 GUI、FastAPI、DuckDB、OpenLayers、PyInstallerなど、複数ファイル・長いログ・何度も修正するプロジェクトでは有効です。

8.参考リンク

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?