Name: koji-lens
Author: Koji

クイックスタート

30 秒で動作確認できます。

$ npm install -g @kojihq/lens
$ koji-lens summary
$ koji-lens serve

動作要件: Node.js 22+ / Claude Code のセッションログ（~/.claude/projects/）が存在する環境。

コマンドリファレンス

主なサブコマンドを以下にまとめます。各コマンドはkoji-lens <command> --helpでも詳細を確認できます。

koji-lens summary

期間内のコスト・トークン・ツール使用量のサマリを表示します。末尾に TOTAL ブロック（全体集計）と、サブスク利用者向けの注記（API 換算コストである旨）が表示されます。

フラグ / 引数	説明
--since <expr>	期間指定 (デフォルト: "24h")。例: 24h / 7d / 2w / ISO date
--format <format>	出力フォーマット: text \| json (デフォルト: text)
--dir <path>	Claude Code ログディレクトリ (デフォルト: config.logDir または ~/.claude/projects)
--usd-jpy <rate>	USD → JPY 変換レート (デフォルト: config.usdJpy または 155)
--no-cache	SQLite cache を無効化（毎回フルスキャン）

例:

$ koji-lens summary --since 7d --format json

koji-lens sessions

期間内のセッション一覧を 1 行 1 セッションで表示します。一覧から気になるセッション ID を引いて、session コマンドで詳細を見る使い方が想定です。

フラグ / 引数	説明
--since <expr>	期間指定 (デフォルト: "7d")
--limit <n>	表示件数 (デフォルト: 20)
--dir <path>	Claude Code ログディレクトリ
--no-cache	SQLite cache を無効化

例:

$ koji-lens sessions --since 24h --limit 5

koji-lens session <id>

指定セッション ID の詳細を表示します。subagent の ID（agent- プレフィックス）も指定可能で、その場合はメインセッション配下のサブエージェントを表示します。

フラグ / 引数	説明
--format <format>	出力フォーマット: text \| json
--dir <path>	Claude Code ログディレクトリ
--usd-jpy <rate>	USD → JPY 変換レート
--no-cache	SQLite cache を無効化

例:

$ koji-lens session 055a662d-f09c-4541-b54c-7ad4a9130f3d

koji-lens serve

ローカル Web ダッシュボードを起動します。Next.js standalone bundle 同梱なので、追加インストール不要で動きます。コスト推移チャート / セッション一覧 / ツール呼び出し分布を見られます。

フラグ / 引数	説明
--port <port>	ポート番号 (デフォルト: 3210)

例:

$ koji-lens serve --port 3210

koji-lens statusline

Claude Code の statusLine 統合用に、節約状況を 1 行で表示します。先月比のコスト変動 (💚/💛/🚨/⚪) と prompt cache 効率 (💎/🧊/💧) を 3 ブロックの絵文字で表現。--buddy で麹キャラ装飾、--buddy-speech で発言を追加できます (例: 🍙· < ぽつぽつ…?)。詳しい設定例は README の statusline セクションを参照してください。

フラグ / 引数	説明
--mode <density>	minimal \| normal \| detailed (デフォルト: normal)
--buddy	🍙 麹キャラ装飾を末尾に表示 (Lv1-10、累計セッション数で進化)
--buddy-speech	麹キャラの発言を追加表示 (5 状態 × 10 Lv = 50 セリフ)
--buddy-type <type>	麹キャラ種類 (現在は koji のみ、フクロウ/猫は今後対応)
--no-state	agent state icon (⚡/💤/🛑) を非表示
--no-cache-rate	cache 効率 signal (💎/🧊/💧) を非表示
--format <format>	出力フォーマット: text \| json

例:

$ koji-lens statusline --mode minimal --buddy --buddy-speech

koji-lens compare --before <range> --after <range>

期間比較。before / after を指定して、コスト・トークン・モデル分布の差分を表示します (例: Sonnet に切り替える前後の比較)。改善追跡の中核機能で、ルールベース Insights も併せて出力します。

フラグ / 引数	説明
--before <range>	比較元期間 (例: 7d, 30d, ISO date 範囲)
--after <range>	比較先期間
--format <format>	出力フォーマット: text \| json

例:

$ koji-lens compare --before 30d --after 7d

koji-lens trend

週次トレンド表示。cache 効率や p95 レスポンスタイム等の時系列変動を可視化します。--with-attribution (Pro) で vendor/user 由来の判別も。

フラグ / 引数	説明
--weeks <n>	対象週数 (デフォルト: 12)
--with-attribution	Pro: vendor/user 由来の attribution 付き

例:

$ koji-lens trend --weeks 8

koji-lens budget --budget <usd>

月次予算管理。月初〜現在の累積コスト + 月末予測 + 予算超過警告を表示します。複数プロジェクト個別予算 (Pro) や config 永続化対応。

フラグ / 引数	説明
--budget <usd>	月次予算 (USD、必須)
--with-alerts	Pro: 予算超過アラート連動
--project <key>	Pro: プロジェクト別予算
--list	Pro: 全プロジェクトの予算一覧

例:

$ koji-lens budget --budget 200

koji-lens export

CSV / JSON 形式でデータエクスポート。stdout 出力 or ファイル保存。data ownership ポリシー整合 (すべてローカル処理、外部送信なし)。

フラグ / 引数	説明
--format <format>	csv \| json (デフォルト: json)
--since <expr>	期間指定 (例: 30d)
--out <path>	出力ファイルパス (省略時 stdout)

例:

$ koji-lens export --format csv --since 30d --out usage.csv

koji-lens config <action> [key] [value]

設定ファイル ~/.koji-lens/config.json を CLI から操作します。

フラグ / 引数	説明
<action>	get \| set \| unset \| list \| path のいずれか
[key]	設定キー (logDir \| usdJpy)
[value]	設定値 (set のみ必要)

例:

$ koji-lens config set usdJpy 158

設定ファイル

設定は ~/.koji-lens/config.json に保存されます。設定パスは koji-lens config path で確認できます。

logDirstring

Claude Code のログディレクトリパス。未設定時は ~/.claude/projects を参照します。Claude Code のインストール位置や macOS / Windows / Linux で異なる場合に明示指定してください。

usdJpynumber

USD → JPY 変換レート。未設定時は 155 を使用します。最新レートを反映したい場合は手動更新してください。

現在の設定一覧: koji-lens config list / 設定の追加・更新: koji-lens config set usdJpy 158

FAQ

Claude Pro / Max（サブスク）で使ってもコスト表示は意味がありますか？

表示されるコスト値は API 換算（トークン量 × Anthropic 公式 API 価格）です。サブスク利用者は実際の請求が定額なので、表示コストはあくまで「使用量の目安」「Sonnet と Opus の使い分け判断材料」として参考にしてください。 summary の TOTAL ブロック末尾にも同趣旨の注記を表示しています。

cache はいつ更新されますか？

JSONL ファイルの mtime（更新時刻）を見て、変更があったセッションのみ再パースします。--no-cacheフラグでフルスキャンに切り替え可能です。cache の DB は ~/.koji-lens/cache.db に保存されます。実測では cache hit で約 6 倍高速化します。

subagent の親子関係は見られますか？

はい。subagent のセッション ID は agent-* プレフィックスで識別され、ファイルパスは <main-session-id>/subagents/agent-<id>.jsonl の構造になっています。session コマンドで agent- ID を指定すれば、サブエージェント単独の詳細も取得可能です。

プロンプト本文や API キーは外部に送信されますか？

送信されません。すべての処理はローカル PC 内で完結します。 SQLite cache にもプロンプト本文は保存しない設計です（集計に必要なメタデータのみ保持）。クラウド送信 NG ポリシーの環境でもそのまま使えます。

Cursor / Cline / Aider でも使えますか？

現在は Claude Code 専用ですが、内部はアダプタ式設計のため Cursor / Cline / Aider 等への対応を OSS で開発中です。進捗は GitHub Issues で追跡できます。

Pro プランでは何が増えますか？

2026 年 5 月下旬に提供開始予定の Pro プランでは、クラウド同期（履歴無制限）/ 複数デバイス間同期 / CSV・JSON エクスポート / 週次・月次レポートのメール配信等を予定しています。 Free プランの全機能はそのまま使えます。先行通知は waitlist でお受けしています。

バグや要望はどこに報告すればよいですか？

GitHub Issues か、Bluesky @kojihq.com にお気軽にどうぞ。サポート窓口は support@kojihq.com でも受け付けています。

さらに詳しく

・GitHub リポジトリ — ソースコード、Issues、Discussions
・README — 開発者向けの追加情報
・Releases / CHANGELOG — バージョンごとの変更履歴
・npm パッケージ — @kojihq/lens
・Bluesky @kojihq.com — お知らせ・フィードバック
・support@kojihq.com — サポート窓口

ドキュメント