ターミナルがダサいとモテない。lean-ctxをCodexに組み込む編。

私はCodexを使っています。

前にrtkでAI AgentのTokenを最適化する記事を書きました。

rtkはshell commandの出力を圧縮して、AI Agentへ渡すtokenを減らしてくれます。

今回はさらに広い範囲のContextを扱うlean-ctxをCodexに組み込みます。

またtokenの話です🤣

Codexを使っていると、同じファイルを何回も読んだり、大量のbuild logを受け取ったり、Repository全体を検索したりします。

Context Windowが大きくなっても、必要のない情報まで全部入れたら良いわけではないので、lean-ctxで整理してもらおうという感じです。

2026年9月9日に、この時点の最新リリースである3.10.1で再確認しました。以下の設定と実行結果は、その時点の自分の環境のものです。

lean-ctx

lean-ctxはAI Agent向けのContext Engineering Toolです。

単純に出力を短くするだけではなく、AI Agentが何を読むか、どの密度で読むかまでコントロールします。

自分が気になった特徴はこの辺です。

• ファイルの目的に合わせた複数のread mode
• tree-sitterを使ったASTベースのcode理解
• git、npm、cargoなどshell commandの出力圧縮
• 同じファイルを読み直す時のcache
• sessionを跨いで使えるmemoryとknowledge graph
• MCPを使ったCodexやClaude Codeなどとの連携
• 明示的に有効化して使うmulti-agent間のhandoffやContext共有
• pathとshell commandを制限するsecurity機能

自分の環境では、Codexが普通にファイルを読む代わりにctx_read、検索する代わりにctx_search、shellを実行する代わりにctx_shellを使います。

中身を全部読む必要がない時はsignatureだけ、編集する時は全文を残す、といった使い分けができます。

read modeを省略した時はautoで選んでくれますが、目的が決まっている時はCodex側から指定できます。

必要な内容まで省略された時は、ctx_readのraw: trueで読み直せます。shellの出力も、ctx_shellのraw: trueで圧縮せずに確認できます。

Install

公式のGetting StartedにはいくつかInstall方法があります。

Homebrew

macOSではHomebrewが推奨されています。

brew tap yvgude/lean-ctx
brew install lean-ctx

Cargo

自分はRust製のToolはCargoで管理したいので、Cargoで入れています。

cargo install lean-ctx

Installしたbinaryとpathは、次のcommandで確認できます。

lean-ctx --version
command -v lean-ctx

再確認した時点では、すでに最新の3.10.1が入っていました。

lean-ctx 3.10.1 (official, https://github.com/yvgude/lean-ctx)
/Users/yusukeh/.cargo/bin/lean-ctx

Codexへ組み込む

現在の公式ドキュメントでは、Codex用のsetupはこれでできます。

lean-ctx wrap codex

wrap codexはMCPだけでなく、認証方式に応じたproxyの設定も扱います。3.10.1では、API keyを使う根拠がある場合にだけ/v1のproxy経路を選び、browser loginなどの場合はCodex本来のChatGPT向け経路を使うよう修正されています。詳細は3.10.1のrelease notesにあります。

複数のAI Toolをまとめて検出して設定する場合は、こちらもあります。

lean-ctx onboard

細かく確認しながら設定したい場合はsetup wizardを使います。

lean-ctx setup

自分はdotfilesをchezmoiで管理しているため、設定を自分でtemplate化しています。今回は既存のMCP設定を確認し、wrapやsetupによる設定の上書きはしていません。proxyも無効の状態です。

~/.codex/config.toml

Codexからlean-ctxをMCP Serverとして起動します。

[mcp_servers.lean-ctx]
command = "/Users/yusukeh/.cargo/bin/lean-ctx"
args = ["mcp"]
default_tools_approval_mode = "approve"
startup_timeout_sec = 30
tool_timeout_sec = 120

commandにはcommand -v lean-ctxで確認したfull pathを指定しています。自分の現在の設定では、args = ["mcp"]でMCP Serverとしての起動を明示しています。

Codex側のcommand、argsなどの項目は、OpenAIのMCPドキュメントで確認できます。

公式の自動設定を使う場合は、Codex向けのinstructionも追加できます。

lean-ctx init --agent codex

設定した後はCodexを再起動します。

bashではCodexを起動した時だけ有効化

lean-ctxにはshell hookもあります。

3.10.1のlean-ctx init bashが出力するhookは、通常の出力を保って統計を記録するtrackが基本です。出力を圧縮するcompressと、有効化する条件は別になっています。

自分は普段のTerminal操作ではhookを有効にせず、CodexなどのAI Agentを起動した時だけ使う設定にしています。

export LEAN_CTX_SHELL_ACTIVATION=agents-only

if [[ -f "${HOME}/.config/lean-ctx/shell-hook.bash" ]]; then
  . "${HOME}/.config/lean-ctx/shell-hook.bash"
fi

alias codex='LEAN_CTX_AGENT=1 BASH_ENV="$HOME/.bashenv" codex'

ここでもう1つ必要なのが~/.bashenvです。

BASH_ENVを指定した非対話bashは、そのファイルを読み込んでからcommandを実行します。自分の.bashenvには、AI Agentの環境変数がある時だけlean-ctx -cへ渡すhookが入っています。

つまり、agents-onlyやaliasだけでCodexの出力が全部自動圧縮されるわけではなく、.bashenvまで含めた設定です。

今回の再確認では、AI Agentの環境変数を外した非対話bashと、LEAN_CTX_AGENT=1を付けた非対話bashでgit statusを実行して、この経路を確認しました。

このaliasが効くのは、そのbashから起動したCodex CLIです。Desktop AppのMCP接続とは別に確認しています。

新しくshell hookを組み込む場合は、公式ドキュメントにあるeval "$(lean-ctx init bash)"という方法もあります。Install済みbinaryからhookを生成するので、更新に追従しやすいです。

人間とAI Agentで欲しい出力は違うので、この分け方が自分には合っています。

状態を確認

Terminalで状態を確認します。

lean-ctx status

ブラウザから確認する時は、Web Dashboardも使えます。

lean-ctx dashboard

今回は3.10.1のDashboardで、上部のDoctorから診断パネルを開きました。

一方、lean-ctx statusの実行結果は、shadow_mode: active、doctor: 6/6、mcp: 13/13 configured、rules: 9/9 up-to-dateでした。

ここでのMCPとrulesの件数は、lean-ctxが検出したAI Toolの設定状況です。MCP toolの数や、すべての接続の動作確認数ではありません。

詳細な診断も実行します。

lean-ctx doctor

今回は48/48 checks passedでした。任意機能のTypeScript用LSPは未Installですが、これは診断の点数には含まれていません。

さらにCodexからctx_readでこの記事を読み、ctx_searchで検索し、ctx_shellでgit status --shortを実行できることも確認しました。設定ファイルがあるだけでなく、実際にMCP経由で使えるところまで確認しています。

どのくらい減ったか

ローカルで観測したtoken差分はlean-ctx gainで確認できます。

lean-ctx gain

DashboardにはCost savedという推定入力コストや、Net savings rateという別のledger（計測台帳）に基づく正味の割合も並びます。CLIの金額・割合と同じ指標ではないので、ここでは混ぜずに見ています。

lean-ctx gainを再実行した時点では、CLI上部のsummaryがこんな表示でした。

• token difference: 95.7M
• representation rate: 40%
• USD estimate: $266.54

めちゃくちゃ減ってる🤣

ただし、これはCodex全体の請求額が40%減ったという意味ではありません。

現在の表示にも、lean-ctxを通った処理について、元の内容と選ばれた表現のtoken数を比べたローカルな差分であり、providerの請求額やworkload全体のbenchmarkではないと書かれています。

内訳はこれで見られます。

lean-ctx gain --deep

こちらの上部には95.7M、39.6%、45,371 commands、$266.54と表示されました。40%は丸めた値です。

金額の内訳はfallback estimateで、入力100万tokenあたり$2.50、出力100万tokenあたり$10.00という代替単価を使っていました。自分の契約の請求明細を読み取った金額ではありません。

また、これは導入後の累積値です。過去のversionで記録した処理も含むので、3.10.1だけで95.7M減らしたという比較実験でもありません。

lean-ctx自身もtoolの定義やinstructionをContextに追加するため、その分のoverheadがあります。net of injectionはその調整後の指標ですが、cacheなどの前提もあるので、元の差分や実際の利用料金とは分けて見ています。

rtkとの簡易比較

以前紹介したrtkと目的は近いですが、守備範囲が違います。

2026年9月9日にrtkの公式READMEとlean-ctxの公式ドキュメントを確認し直しました。以下は機能と自分が両方使った印象の簡易比較で、同じ処理を走らせた性能benchmarkではありません。

rtkはgit statusやtest結果など、commandの出力を小さくしたい時にわかりやすいです。

lean-ctxは「どのファイルを、どう読むか」から管理するので、Repository全体を行き来する長い作業に向いている印象です。

どちらが上というより、rtkはshell output compressor、lean-ctxはContextを扱うlayerという感じです。

自分の環境ではlean-ctxを優先して、lean-ctxでうまく扱えないcommandだけrtkを明示的なfallbackとして使っています。

両方が同じcommandを自動で横取りすると何が圧縮したのかわかりにくくなるので、役割は分けた方が良いと思います。

使ってみた感想

lean-ctxはrtkよりかなり多機能です。

ファイルを読み直してもcacheが効いたり、大量のbuild logが必要なところだけになったり、Codexを長く使うほど効果を感じやすいです。

その反面、shell allowlistでcommandが止まったり、圧縮された結果からraw outputを見たくなったり、最初は「何で動かないの？」となることもあります😅

自分は設定もdotfilesで管理して、必要なcommandと操作範囲を確認しながらallowlistを管理しています。全文が必要な確認ではrawを使い、圧縮した表示だけで判断しないようにしています。

ここまでやるとtokenを減らすための設定に時間を使いすぎている気もしますが・・・🤣

ただCodexを毎日使うので、同じRepositoryを何度も読ませる無駄が減るのはかなり嬉しいです。

rtkはシンプルで好き、lean-ctxは多機能で面白い。

しばらくはlean-ctxを中心にして、rtkもfallbackとして残しながら使っていこうと思います😆

medium.com/@yusukeh - ターミナルがダサいとモテない。lean-ctxをCodexに組み込む編 の記事を転載し、2026年9月9日の再検証結果に合わせて加筆・更新しています。