tokenjuice: AI agent に返す terminal output を先に細くする

AI coding agent 周辺の tool を見ていると、繰り返しぶつかる問題があります。

context を太らせている原因は、model の推論不足ではなく、terminal output の脂肪であることが多い。

agent は git status を走らせ、rg を打ち、pnpm test や docker build を流し、必要なら --help まで読む。その中で本当に必要な signal は数行しかないのに、返ってくる transcript は巨大です。進捗行、反復 log、冗長な inventory、無関係な help 文まで context を埋めます。

今日メモしておきたい vincentkoc/tokenjuice は、まさにこの層を触る project です。コード検索でも新しい shell でもありません。発想はかなり明快です。

command はそのまま実行し、返す output だけを薄くする。

GitHub repository page、latest release、公開 commit、README を 2026-07-01 時点で確認すると、この project は 476 stars、49 forks。主言語は TypeScript、license は MIT です。repository 作成日は 2026-04-14、直近の公開コード push は 2026-06-18。最新 release は v0.8.1 で、公開日は 2026-06-18 です。

Project overview

項目	内容
Repository	vincentkoc/tokenjuice
位置づけ	terminal-heavy な AI agent workflow 向け output compaction CLI
Stars	476
Forks	49
主言語	TypeScript
Repository 作成日	2026-04-14
直近の公開コード push	2026-06-18
Latest version	v0.8.1
Release date	2026-06-18
Code license	MIT
中心の発想	command semantics を変えず、返却 output だけを deterministic に圧縮する

これは「実行」より「返送」の問題を扱っています

tokenjuice の面白さは、agent を賢く見せようとしていないことです。

README の自己定義はかなり率直で、これは deterministic output compactor です。つまり command 自体の意味や挙動は触らず、実行後の output を rule-driven reducer で圧縮します。しかも rule は inspect できる JSON で、別の LLM にふんわり要約させる方式ではありません。

この整理は実務的です。

agent workflow で token を浪費させるのは、たいてい次のような出力です。

git status の長い file list;
pnpm test や docker build の大量 log;
rg の過剰ヒット;
help 文や inventory 出力の過剰さ。

つまり問題は「command を実行できるか」ではなく、

その結果を、どれだけ細い形で context に戻せるか

にあります。

`reduce`、`wrap`、`reduce-json` の三層が分かりやすいです

コマンド面はかなり整理されています。

tokenjuice reduce [file]
tokenjuice wrap -- <command> [args...]
tokenjuice reduce-json [file]

1. `reduce`

既に手元にある text を圧縮したいときの入口です。たとえば CI log や保存済み transcript を後処理したいときに向いています。

2. `wrap`

これは日常運用で一番使いやすい表面だと思います。

tokenjuice wrap -- git status
tokenjuice wrap -- pnpm test
tokenjuice wrap -- docker build .

既存 command をそのまま包み、実行後に output を縮めて返すだけなので、今ある terminal workflow に薄く差し込めます。

3. `reduce-json`

これは host adapter 向けの machine-facing protocol です。つまり人が単独で使うだけでなく、Codex、Claude Code、Cursor、OpenCode などの host が共通インターフェース経由で compactor を呼べます。

個別 integration を量産しても、中心ロジックが 1 つに集約されている点はかなり健全です。

発想は「魔法の要約」ではなく「予測可能な規約」です

この project の好感が持てるところは、output を曖昧に“賢くまとめる”のではなく、規約として扱っている点です。

README では次の 2 点が繰り返し強調されています。

rule は inspect できる JSON であること;
raw output は明示的に取り戻せること。

rule の重なり方も実務向きです。

built-in rule;
user override: ~/.config/tokenjuice/rules;
project override: .tokenjuice/rules

後ろの層が前の層を上書きします。

これはかなり重要です。というのも、noise の出方は repository ごとに違うからです。frontend build log が太る team もあれば、monorepo inventory が邪魔な team もある。こういう差分を local / project 単位で調整できる方が、長く使える infrastructure になりやすいです。

明示的な bypass を残しているのが良いです

圧縮 tool が本当に危ないのは、「今回は raw が必要」という場面を勝手に丸めることです。

tokenjuice はその点でかなり慎重です。README には明示的な escape hatch があります。

tokenjuice wrap --raw -- pnpm --help
tokenjuice wrap --full -- git status

加えて、正確な file 内容読み出しのようなケースは、そもそも不用意に compact しない方針が見えます。最新の v0.8.1 release でも、read-only な config inspection を誤って圧縮しないための exact-read bypass 強化が入っています。

この方向性は信頼しやすいです。

agent tool で本当に困るのは、機能不足より、

勝手な近似;
いつの間にか失われる detail;
後から再現しづらい summarize

だからです。tokenjuice は少なくとも設計思想として、そこをかなり意識しています。

host integration を主戦場として見ているのも強いです

この project は reducer だけで終わっていません。README では、かなり多くの host integration が並んでいます。直接触れているものだけでも、

Codex CLI
Claude Code
Cursor
OpenCode
GitHub Copilot CLI
Gemini CLI
CodeBuddy
OpenClaw

などが含まれています。

さらに beta integration も非常に広く、hooks、rules、skills、AGENTS.md 系の入口まで含めて host へ入っていく設計です。

これは単純に「対応先が多い」というだけではありません。作者が、

output compaction は standalone utility では足りず、既存 host に薄く入り込んで初めて意味がある

と分かっていることを示しています。

`doctor`、`discover`、`stats` まであるのが運用向きです

圧縮本体だけでなく、周辺の運用コマンドも用意されています。

tokenjuice doctor
tokenjuice doctor hooks
tokenjuice discover
tokenjuice stats

これがあると、

integration が正しく入っているか;
どの wiring が生きているか;
実際にどれだけ圧縮されているか

を追いやすくなります。

agent workflow 用の効率 tool は、導入した後に「本当に効いているのか分からない」問題が起きがちです。その点で tokenjuice は、診断面まで最初から設計対象に入れているのが良いです。

これは派手な product というより、日常に入る infrastructure です

tokenjuice は新しい IDE でも orchestration platform でもありません。より近いのは、

shell と agent の間に差し込む小さな infrastructure 部品

です。

この位置は地味ですが、とても重要です。

実際の coding agent 運用では、

input が長すぎる;
重要 signal が薄い;
terminal noise が context を埋める;
host ごとに output の扱いがばらつく

という摩擦が毎回発生します。tokenjuice は、まさにその摩擦を系統的に減らそうとしている project です。

どんな人に向くか

特に相性が良さそうなのは次のような人です。

terminal で coding agent を高頻度に使っている;
test、build、search、inventory の output をよく model に渡す;
transcript のノイズを減らしたい;
deterministic で inspectable な compaction rule を好む;
複数 host で同じ output discipline を共有したい。

単発で少し command を見るだけなら不要かもしれません。でも agent workflow を本格的に回しているなら、output compaction はだんだん optional ではなくなっていきます。

まとめ

vincentkoc/tokenjuice の価値は、「たくさんの agent に対応している」ことだけではありません。

もっと重要なのは、agent workflow の無駄がしばしば

command 実行能力ではなく;
command output の肥大化にある

と見抜いていることです。

command semantics には手を入れず、返却 output だけを deterministic に圧縮し、しかも override 可能で、bypass 可能で、多数の host に薄く接続できる。この克制の仕方はかなり良い engineering だと思います。

コード検索 tool が「どこを見るか」を助けるなら、tokenjuice が助けるのは、

見たあとに、何をどれだけ context に戻すべきか

という問題です。