cheap-eyes

cheap-eyes

高価なエージェントのための、安価な目。

AI エージェントのコンテキストは高価です。大きなログや長いドキュメント、ウェブページ、コードツリー全体を読み込むと、ほとんど必要のない行にコンテキストを消費してしまいます。cheap-eyes は、読み取りを安価なモデルに任せる MCP サーバーです。その後、そのモデルの回答の各行をソースと照合するため、エージェントは信頼できる短い回答を受け取れます。

実際の表示

サーバーから取得した実際のヘッダー（抜粋）と、スタブ化したモデルの回答です。エージェントはアプリのログから 08:10 以降のすべての ERROR 行と、その後に続くトレースバックを求めました。

eyes_run result: 2026-09-26_152246-extract-889090
model: alias fast -> qwen/qwen3.6-35b-a3b (used: qwen/qwen3.6-35b-a3b)
tokens in 412 / out 96; cost $0.000080; 2 ms
check (extract): refs ok 4 / bad 1 — ok 4, ok~ 0, partial 0, not-in-input 0
  L9 [bad] text differs from the source line
--- untrusted model output ---
L3| 2026-09-20 08:14:09.031 ERROR [sync] upload failed: timeout after 30 s
L4| 2026-09-20 08:14:09.032 Traceback (most recent call last):
L6| TimeoutError: timed out
L8| 2026-09-20 08:15:31.550 ERROR [sync] upload failed: HTTP 503 from api.example.com
L9| 2026-09-20 08:16:00.000 ERROR [sync] retry 2/3 failed
--- end ---

モデルは 5 行を引用しました。実際のログでは、9 行目は INFO [sync] retry 2/3 ok なので、モデルはエラーをでっち上げています。検証では各引用をソースの行と照合し、L9 に bad のフラグを付けました。エージェントは回答を信頼する前に、そのことを確認できます。

回答を信頼できる理由

• モデルにはツールがありません。 ファイルを開いたり、ウェブを閲覧したり、何かを呼び出したりできません。cheap-eyes が選んで送信した番号付きの行だけを参照します。
• マシンの外部に送信される前に、シークレットをマスキングします。 パスワード、トークン、キーなどは、ファイル内でもタスク内でも [token]、[key] などに置き換わります。
• Zero Data Retention プロバイダーのみを使用します。 これらのプロバイダーはプロンプトを保存しません。cheap-eyes は OpenRouter のみと通信し、呼び出しごとに Zero Data Retention を指定します。
• すべての引用と行参照を、送信した行と機械的に照合します。 間違った値や、出典のない主張にはフラグが付きます。
• 検証で証明できないこと： 回答が完全か、関連性があるかどうかです。引用された内容が実在することは証明しますが、見落としがないことまでは証明しません。

要件

ランタイム	Node.js ≥ 22.17、Docker、または Home Assistant OS / Supervised
アーキテクチャ（Home Assistant アプリ）	amd64、aarch64
ネットワーク	openrouter.ai およびジョブで指定するウェブページへの送信 HTTPS 通信。claude.ai の場合は、インターネットから到達可能な TLS リバースプロキシ
ディスク	インストール後約 56 MB。そのうち 33 MB は CMap とフォントを含む pdfjs-dist です。オプションの @napi-rs/canvas を追加すると、テキスト抽出には不要な約 37 MB のネイティブバイナリが追加されます（npm install --omit=optional でスキップできます）
OpenRouter	独自の日次上限を設定した API キー

インストール

Claude Code / Claude Desktop（npx）

1. ~/.config/cheap-eyes/config.json に設定ファイルを作成するか、Windows では %APPDATA%\cheap-eyes\config.json に作成します（設定を参照）。

2. 設定を確認します（ネットワーク通信なし、シークレットの出力なし）：npx -y cheap-eyes check-config

3. サーバーを Claude Code に追加します。

   claude mcp add --env CHEAP_EYES_OPENROUTER_KEY=<OPENROUTER_KEY> --transport stdio cheap-eyes -- npx -y cheap-eyes
   

4. 試してみます：「eyes_run を使って、/home/me/notes/**/*.md にあるすべての TODO を、それぞれの行番号とともに一覧表示して。」

Claude Desktop、.mcp.json、グローバルインストールについては、 インストール方法を参照してください。

Home Assistant アプリ

Home Assistant は 2026.2 で add-ons を apps に名称変更しました。旧バージョンでは、同じメニューが Add-ons と Add-on Store と表示されます。

1. 次のリポジトリを追加します。

   

   または手動で追加します：Settings → Apps → App Store → ⋮ → Repositories → + Add を選択し、 https://github.com/st412m/cheap-eyes を貼り付けて、Add を選択します。

2. ストアで cheap-eyes を探し、Install を選択します。

3. Configuration で openrouter_key、32 文字以上の http_token（openssl rand -hex 32 で生成できます）、および read_roots を設定します。

4. Start を選択します。アプリはポート 3400 で MCP を提供します。

オプションとコネクター URL については、 アプリのドキュメントを参照してください。

Docker／HTTP

cheap-eyes serve --http は、トークンを使って同じサーバーを Streamable HTTP 経由で実行します。リポジトリの Dockerfile と compose.example.yaml がこれをラップします。インストールをご覧ください。

設定

JSON 設定ファイルです。まず設定するフィールドは次のとおりです。

フィールド	内容
read_roots	サーバーが読み取ることのできるフォルダー（または単一ファイル）です。絶対パスを指定します。
models	エイリアスです。fast のようなエイリアスは、モデル ID のリストを表す短い名前です。
defaults	呼び出しで指定がない場合に各モードが使用するエイリアスです。
daily_budget_usd	UTC 日ごとのローカル支出上限です。既定値は 1.0 です。

{
  "read_roots": ["/home/me/notes"],
  "models": { "fast": { "ids": ["qwen/qwen3.6-35b-a3b"], "params": { "reasoning": { "effort": "none" } } } },
  "defaults": { "extract": "fast", "draft": "fast", "edits": "fast" }
}

キーは環境変数 CHEAP_EYES_OPENROUTER_KEY に設定し、ファイルには記載しないでください。すべてのフィールド、環境変数、ファイルの場所については、設定をご覧ください。

claude.ai への接続

HTTP サーバー（または Home Assistant アプリ）を実行し、TLS を終端するリバースプロキシ経由で公開します。エンドポイントは次のとおりです。

https://<your-host>/private_<your-token>/mcp

claude.ai → Settings → Connectors → Add custom connector から追加します。パスが間違っていると本文のない 404 が返されます。設計上、OAuth はありません。セキュリティをご覧ください。

使い方

いつもどおりエージェントに話しかけます。ジョブに適していれば、エージェントが cheap-eyes を呼び出します。必要な結果に応じてモードを選びます。

• extract は、ログのエラー、設定値、特定項目への言及すべてなど、正確な行が必要なときに使います。捏造された行にはフラグが付けられます。
• draft は、メモや要約が必要なときに使います。すべての行に出典の行番号を付ける必要があります。該当する行にない値や、引用のない行にはフラグが付けられます。
• edits は、修正案が必要なときに使います。ファイルと照合して旧テキストを検証する JSON 編集案が返されます。cheap-eyes が編集を適用することはありません。
• schema は、フィールドを埋めたいときに使います。JSON スキーマを入力すると、各値の行参照と逐語的な引用を含む同じ JSON が返されます。値が矛盾する場合は解決せずに報告されます。
• grep は、完全一致するパターンがわかっているときに使います。一致箇所のウィンドウを返します。モデルは使わず、$0 です。

ファイルは、テキスト、HTML、PDF（テキストレイヤー付き）、Word（DOCX、DOC）、RTF、PowerPoint（PPTX、PPT）、OpenDocument のテキストおよびプレゼンテーション（ODT、ODP）、EPUB、FB2、メール（EML、MSG。添付ファイルを含む）、またはサーバーが自ら取得する http(s) URL に対応しています。スプレッドシートとスキャンは、理由とともに拒否されます。参照には、行が属するページ、スライド、章、または添付ファイルが示されます。例：L40 (slide 3)、L12 (attachment: offer.pdf, p.2)（形式）。

入力できるプロンプトの例（ファイルは read_roots 内にある必要があります）。

• 「eyes_run を使って、今日の 08:00 以降に発生した /var/log/app/app.log の ERROR をすべて、トレースバックとともに抽出してください。」
• 「cheap-eyes に、/home/me/notes/deploy.md の要約を下書きしてもらってください。バージョン、ポート、バックアップ時刻を含めてください。」
• 「eyes_run を edits モードで使って、/home/me/notes/*.md のリンク切れを修正してください。」
• 「/home/me/docs/tender.pdf に対して eyes_run を schema モードで使い、顧客、最高価格、期限、数量付きの商品一覧を取得してください。」

各チェックで検出できること、できないことについては、チェックをご覧ください。

cheap-eyes と grep の使い分け

cheap-eyes が効果を発揮するのは、ログ、アーカイブ、長い文書、ウェブページ、「X に関するすべて」のような、大量のテキストを意味に基づいて読む場合です。正確な検索（キーの検索、X を含むブロックの特定、フィールド別の一覧、テーブル内の値の検索）や、約 30 KB 未満のファイルでは、grep、範囲を指定した読み取り、またはコードを使うほうが低コストで信頼性も高くなります。そのため、スプレッドシートは一切読み取りません。

独立した正解データを用いた 2026-09-30 のベンチマークでは、次の結果が得られました。

• 887 KB のログアーカイブで、「電力に関するすべて」というタスク：再現率 96 %、適合率 100 %、コスト $0.08。アーカイブ全体を読む場合の約 227k トークンに対し、エージェントのコンテキスト消費量は約 12k トークンでした。
• Home Assistant のオートメーションに関する構造的なタスク（「Telegram に送信するのは誰か」）：緑色のチェックが表示されていても、適合率は 41 % でした。このチェックで検出できるのは、存在しない行を作り出した場合であり、選択した行が誤っている場合ではありません。

CLAUDE.md または Claude の設定に記述するスニペット：

Reading by meaning over large text (logs, archives, long documents, web pages, "everything about X") → cheap-eyes eyes_run (extract/draft; fields → schema). Exact values, structure, small files (< ~30 KB) → grep / ranged read (no model: eyes_run mode grep). Verify any value from cheap-eyes against the source (eyes_result source) before relying on it.

独自の文書でモデルを比較するには、 cheap-eyes bench を実行してください。

ツール

• eyes_run — 処理を実行し、短い検証済みのヘッダーを返します。
• eyes_result — 保存された結果（ページ、grep、チェックレポート、モデルに渡されたソーステキスト）を読み取り、実行中のジョブをキャンセルします。
• eyes_stats — 本日と全期間の支出、お使いのキーの状態を表示します。リクエストに応じて、モデルの一覧も表示します。

入力と出力については、ツールを参照してください。

モデルとコスト

コード内で特定のモデルに固定されていません。設定でモデルにエイリアス（fast、long など）を割り当てます。モデルを切り替えるには、設定を編集して再起動します。各エイリアスには、優先順位順にモデル ID が並びます。モデルを使用できない場合は、次のモデルが試されます。例に記載されている ID は 2026-09-26 時点で有効でしたが、いずれ古くなります。新しいモデルを選ぶには：

cheap-eyes models --candidates

これは、低コストの Zero Data Retention モデルを一覧表示し、独自のジョブで各エイリアスがチェックにどの程度合格したかを示します。OpenRouter アカウントの Guardrails でモデルが許可されていない場合、cheap-eyes はそのモデルをスキップし、blocked by account と表示します。そのモデルを使用する場合は、openrouter.ai → Guardrails で許可してください。

低コストのモデルなら、ジョブの費用は 1 セント未満です。実際の上限は、OpenRouter に設定したキー独自の日次上限です。それに加えて、daily_budget_usd（デフォルトでは 1 日あたり $1）が、上限を超える前に呼び出しを停止します。詳細は、モデルと支出を参照してください。

制限事項

• チェックで証明できるのは引用が実在することであり、回答が完全であることではありません。 モデルが関連する行を見落としても、検出されません。
• OCR には対応していません。 スキャンされた PDF は理由とともに拒否されます。抽出時にレイアウトと画像は失われます。
• スプレッドシートには対応していません。 Excel と OpenDocument のスプレッドシートは拒否されます。テーブルに関する質問は正確な検索が必要であり、grep やコードなら回答できますが、テーブルをテキストとして読むモデルは誤答するためです。
• サイズ制限があります。 テキストファイル（または文書から抽出したテキスト）が 2 MB を超える場合は、切り詰めずに拒否されます。同様に、50 MB を超える文書と 10 MB を超える URL も拒否されます。フィルタリング後のジョブは 5 MB、200 ファイルが上限です。
• draft には reduce パスがありません。 複数のチャンクがある場合、各チャンクのメモはそれぞれのヘッダーの下に返されます。
• フックが対象とするのは Claude Code の Read ツールのみです。 シェルコマンドはインターセプトされません。

トラブルシューティング

• OpenRouter が 403「Access denied by security policy」を返す。 OpenRouter が一部の地域からのアクセスを拒否しています。プロキシ経由で呼び出してください。
• モデルが blocked by account と表示される。 openrouter.ai → Guardrails で許可するか、エイリアスに別の ID を指定してください。
• サーバーが起動せず、エイリアス名が表示される。 defaults の値が models で定義されていません。
• 更新後もクライアントに古いツールが表示される。 コネクターのツール一覧を更新し、新しいチャットを開始してください。

詳細は、トラブルシューティングを参照してください。

セキュリティ

• モデルにツールは渡されません。モデルが返す内容はすべて、信頼できない出力として扱われます。
• シンボリックリンクを解決したうえで、read_roots 内のファイルのみを読み取ります。.env*、キー、secrets.yaml、データベース、.git は常に拒否されます。
• マシンの外部に送信される前にシークレットがマスキングされます。モデルの呼び出し先は openrouter.ai のみで、Zero Data Retention が必須です。
• ジョブ内の URL はサーバーが取得します。プライベートアドレスとローカルアドレスは拒否され、DNS リバインディングも防止します。
• エクスポートを明示的に有効にしない限り、サーバーが自身の状態フォルダー以外に書き込むことはありません。
• HTTP モードでは、トークンはパスワードとして機能します。32 文字以上である必要があり、ログに記録されることはありません。前段に TLS を配置してください。1 MiB を超えるリクエスト本文は拒否されます。

詳細：セキュリティ。

リンク

• ドキュメント — インストール、 設定、 ツール、 チェック、 モデルと支出、 結果、 セキュリティ、 フック、 フォーマット、 ベンチマーク、 トラブルシューティング、 内部情報
• Home Assistant アプリ
• 変更履歴

先行事例

どちらも MIT ライセンスです。cheap-eyes は一から書かれています（NOTICE を参照）。

• BardyLaw/claude-worker-delegation — サーバーがパスでファイルを読み取り、短いプレビュー、使用状況ログ、日次予算、PreToolUse フックを備えています。cheap-eyes では、不足していた機能として、realpath によるパスガード、黙って切り詰めるのではなく拒否する動作、マスキング、行番号、出力チェックを追加しています。
• aashahin/claude-opencode-delegate — 非同期タスクレジストリ、簡潔なステータスヘッダー。

ライセンス

MIT — st412m による。