クイックスタート
30 秒で動作確認できます。
$ npm install -g @kojihq/lens
$ koji-lens summary
$ koji-lens serve動作要件: Node.js 22+ / Claude Code のセッションログ （~/.claude/projects/） が存在する環境。
💡 koji-lens は lens という短縮 alias でも実行できます（例: lens summary）。 v0.1.0-beta.12 以降で利用可能。
コマンドリファレンス
用途別 4 グループに整理しています。各コマンドは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 行で表示します。billingMode (subscription / api) でユーザー視点を切替: **subscription mode (デフォルト、Pro/Max ユーザー想定)** = 使い込み = 元取れている (💚 sub value up) / 利用低下 = もったいない (💧 under-utilized)。**api mode (opt-in、API key ユーザー)** = コスト削減成功 (💚 saved) / コスト増 (🚨 cost up)。prompt cache 効率 (💎/🧊/💧) を 3 ブロックの絵文字で表現。subscription 出力例: 💚 ↑60% vs last month │ $30 more usage │ sub value up (元取れている) / 💧 ↓40% vs last month │ $40 less usage │ under-utilized (もったいない) / ⚪ new (3d) (月初 1-3 日)。api 出力例 (`koji-lens config set billing-mode api`): 💚 ↓40% vs last month │ $40 saved / 🚨 ↑60% vs last month │ $30 over │ cost up。audit 異常検知 signal (critical = 🛡 / warning = ⚠) も統合表示し、機密ファイル書き込み検出時は 🛡 sensitive=N (N = 件数)、新規 MCP / 高頻度 exec 検出時は ⚠ +Nmcp exec=M 形式で末尾に出ます。--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 | Provendor/user 由来の attribution 付き |
例:
$ koji-lens trend --weeks 8監査と予算
セキュリティ監査 (tool_use 履歴) と月次予算管理。Free 中心、一部 Pro 機能あり。
# koji-lens audit
tool_use 履歴を 7 category 別 (fs-read / fs-write / exec / fetch / task / mcp / other) に抽出。PII 15 種 (Email / Phone / API key / Bearer / Card / UUID / JWT / PEM Private Key / AWS Key / GCP Key / GitHub Token / Slack/Discord Webhook / IPv4 private ほか) は --raw 指定がなければ自動 redaction。statusline 統合で新規 MCP / 高頻度 exec / 機密ファイル書き込み を ⚠ / 🛡 で異常検知 (具体例: 🛡 sensitive=2 = 機密ファイル書き込み 2 件 / ⚠ +1mcp = 新規 MCP 1 件 / ⚠ exec=N = 高頻度 exec)。Free 機能 (cloud sync は Pro)。
| フラグ / 引数 | 説明 |
|---|---|
| --since <expr> | 期間指定 (例: 24h、デフォルト: 24h) |
| --category <cat> | fs-read | fs-write | exec | fetch | task | mcp | other |
| --tool <name> | 特定 tool 名フィルタ (例: Bash, Edit) |
| --format <format> | text | json (デフォルト: text) |
| --out <path> | atomic write でファイル保存 (例: ~/.koji-lens/audit.log) |
| --learn-mcp | 検出 MCP server を known set に追加 (statusline ⚠ 消去) |
| --raw | PII redaction 無効化 (debug 用、デフォルト ON で安全側) |
| --sync | Procloud sync (Phase B 6/01-6/14 で本実装、現状 stub) |
例:
$ koji-lens audit --since 7d --category exec --format json# 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 で確認できます。
Claude Code のログディレクトリパス。未設定時は ~/.claude/projects を参照します。Claude Code のインストール位置や macOS / Windows / Linux で異なる場合に明示指定してください。
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 年 7 月 1 日に提供開始予定の Pro プランでは、 クラウド同期（履歴無制限）/ 複数デバイス間同期 / CSV・JSON エクスポート / 週次・月次レポートのメール配信 等を予定しています。 Free プランの全機能はそのまま使えます。先行通知は waitlist でお受けしています。
バグや要望はどこに報告すればよいですか？
GitHub Issues か、Bluesky @kojihq.com にお気軽にどうぞ。サポート窓口は support@kojihq.com でも受け付けています。