tokf - AI コーディングエージェント向けのコマンド出力フィルター

AI コーディングエージェントのコンテキストを消費するのは、ソースコードだけではありません。むしろ cargo test、docker build、git push のようなコマンド出力が、長いログとして大量に流れ込むことがあります。人間なら進捗行や依存関係のビルド行を自然に読み飛ばしますが、エージェントはそれをそのまま入力として受け取ります。

今日紹介する mpecan/tokf は、この出力の入口でフィルタリングするための Rust 製 CLI です。コマンドの出力が AI ツールに届く前に、TOML で書かれたルールを適用し、長いログを短く明確な結果に変換します。GitHub API では現在およそ 174 stars、18 forks、主な言語は Rust、ライセンスは MIT。リポジトリは 2026 年 2 月 18 日に作成されています。

プロジェクト概要

項目	内容
リポジトリ	mpecan/tokf
Stars	約 174
Forks	18
主な言語	Rust
ライセンス	MIT
作成日	2026 年 2 月 18 日
最近の push	2026 年 5 月 21 日

問題は「ログが長い」だけではない

長いログは、人間にとっては面倒なだけです。しかし AI agent にとっては、そのまま判断材料になります。テストが成功したとき、本当に必要なのは「47 tests passed、2.31 秒」のような短い結果かもしれません。それでも元の出力には、依存 crate のコンパイル、進捗、重複したサマリが大量に含まれます。

失敗時はさらに厄介です。数百行のビルドログの中に本当のエラーが埋もれると、エージェントは不要な情報にコンテキストを使い、原因の推測を始めてしまいます。

tokf の考え方は明快です。ログがコンテキストに入ってからモデルに要約させるのではなく、コマンド実行の層で先に出力を整えます。README の例では、cargo test の出力を 61 行から 1 行のテスト結果へ、git push の出力をオブジェクト列挙や圧縮ログから ok と対象ブランチへ圧縮しています。プロジェクト説明では、一般的なコマンドで LLM コンテキスト消費を 60-90% 減らすとされています。ただしこれはプロジェクト側の説明であり、実際の効果はコマンドとフィルターの品質に依存します。

TOML フィルターという設計

tokf は、すべての出力に一つの汎用サマライザーをかけるツールではありません。コマンドに対応するフィルターを探し、元のコマンドを実行し、その出力にフィルターを適用します。フィルターのロジックは通常の TOML ファイルに置かれ、バイナリを再コンパイルする必要はありません。

この設計には二つの利点があります。

一つ目は、コマンドごとの意味に合わせられることです。git status、cargo test、npm test、kubectl get pods では、重要な情報がまったく違います。同じヒューリスティックでまとめるより、コマンド単位でフィルターを持つほうが現実的です。

二つ目は、チームがルールを上書きしたり共有したりできることです。README では tokf eject によって組み込みフィルターをプロジェクトまたはユーザー設定へコピーし、必要に応じて編集できると説明されています。社内ツールや独自のログ形式があるチームにとって、これはかなり重要です。

対応コマンドの範囲

tokf の README にある組み込みフィルターは、すでに日常的な開発コマンドを広く含んでいます。

• Git: add、commit、diff、log、push、show、status。
• Rust: cargo build、check、clippy、fmt、install、test。
• JavaScript: npm run、npm test、pnpm add、pnpm install、TypeScript compiler、Next build。
• コンテナとプラットフォーム: docker build、docker compose、docker images、docker ps、kubectl get pods。
• その他: go build、go vet、Gradle、pytest、Prisma、gh の一部 PR / issue コマンド。

つまり、これは Rust 開発だけの補助ツールではありません。AI coding session における「コマンド出力レイヤー」を扱うツールです。エージェントが shell command を頻繁に実行するなら、このレイヤーはコンテキスト品質に直接影響します。

使い方: 明示的に包むか、hook を入れるか

最も慎重な使い方は、明示的に tokf run を付ける方法です。

tokf run git push origin main
tokf run cargo test
tokf run docker build .

まずはこの形で、フィルター後の情報が十分かどうかを確認するのがよさそうです。

AI コーディングツールに自動で tokf を使わせたい場合、README には hook のインストール方法もあります。

tokf hook install --global
tokf hook install --tool opencode --global
tokf hook install --tool codex --global

全局 hook は便利ですが、慎重に扱うべきです。毎回 tokf run と書かなくてもよくなる一方で、フィルターが合わないプロジェクトでは、エージェントが必要なログを見落とす可能性があります。まずは一つのプロジェクトで試し、必要なら範囲を広げるほうが安全です。

汎用の error / test / summary モード

専用フィルターがない場合でも、tokf には三つの汎用サブコマンドがあります。

tokf err cargo build
tokf test pytest
tokf summary docker build .

tokf err はエラーと警告を、tokf test はテスト失敗とサマリを、tokf summary は予算内のヒューリスティックな要約を出します。目的は、エージェントに「生ログ」ではなく「診断に近い出力」を渡すことです。

AI agent の作業では、情報が少なすぎることより、情報密度が低すぎることが問題になる場面があります。良いフィルターは、終了コード、失敗箇所、エラー概要、必要な前後関係を残し、進捗バー、重複したビルド行、成功時の定型ログを削ります。

フィルターもテスト対象になる

tokf で特に良いと感じるのは、フィルターをテスト可能なものとして扱っている点です。README には tokf verify、tokf verify --json、tokf verify --require-all、tokf verify --safety などがあり、フィルターのテスト suite、coverage、prompt injection、shell injection、hidden Unicode などを確認できます。

これは、正規表現を数本書いて終わりにするより堅実です。フィルターが失敗情報を消してしまうと、長いログより悪い状態になります。特に agent が自動でコードを変更し、自動でテストを走らせる環境では、フィルター自体の検証が必要です。

チームで独自フィルターを作るなら、最低限、成功例、失敗例、境界例の fixture を置き、終了コードと重要なエラーを消していないことを確認したいところです。

向いている場面

tokf は次のような人やチームに向いています。

• Claude Code、Codex CLI、OpenCode などの AI コーディングツールを日常的に使う人。
• Rust、Node、Docker、Kubernetes の出力が多く、agent のコンテキストがログで埋まりがちなプロジェクト。
• agent にテスト、ビルド、Git 操作を何度も実行させるチーム。
• 「エージェントに見せるコマンド出力」を統一したい内部ツール担当者。
• hooks、skills、rules、workspace constraints を整え始めている人。

たまにエラーログを AI に貼るだけなら、手動で必要部分を渡すほうが簡単です。しかし agent が毎日ローカルでコマンドを実行するなら、出力フィルタリングは小さな最適化ではなく、作業環境の一部になります。

注意点

tokf は新しいプロジェクトなので、導入前にいくつかの境界を意識したほうがよさそうです。

まず、フィルターには判断が入ります。何を重要情報とし、何をノイズとするかを決めるため、プロジェクト固有の出力には合わない場合があります。

次に、hook はエージェントが見る世界を変えます。全局 hook を有効にする前に、--no-filter のような回避手段や、元ログを確認する方法を持っておくべきです。

また、圧縮率だけを成功指標にしないほうがよいです。短ければよいわけではありません。失敗情報が完全か、成功時のサマリが十分か、例外的な出力を残せるかが重要です。

最後に、外部出力を agent に渡す以上、注入や安全性の問題は常にあります。tokf に safety verification があるのは良い点ですが、すべてのカスタムフィルターが自動的に安全になるわけではありません。

まとめ

mpecan/tokf は、AI コーディングエージェント時代のかなり現実的な問題を扱っています。エージェントは生のコマンド出力を全部読む必要はなく、安定して検証できる、十分に短いシグナルを必要とします。tokf は Rust CLI、TOML フィルター、組み込みコマンドライブラリ、hook integration でそれを実現しようとしています。

特に良いのは、フィルターを編集可能で検証可能なエンジニアリング資産として扱っている点です。AI agent のコンテキスト管理は、prompt だけでなく、このようなツール層にも置くべきです。agent に build、test、Git、container command を頻繁に実行させる開発者なら、tokf は試す価値があります。

リポジトリ：https://github.com/mpecan/tokf