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

lean-ctx gain

私は日頃からCodexを使っています。

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

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

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

またtokenの話です🤣

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

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

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だけ、編集する時は編集に必要な内容を残す、といった使い分けをlean-ctx側でやってくれます。

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

自分の環境ではこんな感じです。

lean-ctx 3.9.18
/Users/yusukeh/.cargo/bin/lean-ctx

Codexへ組み込む

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

lean-ctx wrap codex

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

lean-ctx onboard

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

lean-ctx setup

自分はdotfilesをchezmoiで管理しているため、設定を自分でtemplate化しています。

~/.codex/config.toml

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

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

commandにはwhich lean-ctxで確認したfull pathを指定しています。

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

lean-ctx init --agent codex

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

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

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

ただ、普段自分がTerminalを操作している時までcommandの出力を圧縮されると困ります😅

そこで、通常のTerminalでは有効にせず、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'

これで普通にgit statusを実行した時はいつもの出力、Codexが実行した時はlean-ctxを通った圧縮済みの出力になります。

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

状態を確認

新しいWezTermを開いて確認します。

lean-ctx status

自分の環境ではdoctor、MCP、rulesがすべて設定済みになっています。

どのくらい減ったか

削減量はlean-ctx gainで確認できます。

lean-ctx gain

自分の環境では、この記事を書いている時点でこんな表示でした。

• tokens saved: 70.4M
• compression: 38%
• USD saved: $196.72

めちゃくちゃ減ってる🤣

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

lean-ctxを通ったtrafficの圧縮結果なので、prompt、会話履歴、回答なども含めた全体の利用料金とは分けて見た方が良いです。

rtkとの簡易比較

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

2026年8月11日時点の公式ドキュメントと、自分が両方使った印象で簡単に比較します。

主な目的

rtk：shell commandの出力を短くする lean-ctx：AI Agentへ渡すContext全体を整理する

shell

rtk：commandごとのproxyとhook lean-ctx：shell hookと多数の圧縮pattern

ファイル読取

rtk：rtk readでsmartに圧縮 lean-ctx：複数のread mode、AST、cache

検索

rtk：rtk grepなどで結果を圧縮 lean-ctx：relevanceを見ながら検索、symbolやgraphも扱う

AI Agent連携

rtk：shell commandの書き換えが中心 lean-ctx：MCP toolsとshell hook

memory

rtk：主目的ではない lean-ctx：session memory、knowledge graph

導入後の理解

rtk：比較的シンプル lean-ctx：機能が多く、最初は覚えることも多い

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で管理して、allowlistも少しずつ増やしています。

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

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

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

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