Quickstart
Up and running in 30 seconds.
$ npm install -g @kojihq/lens
$ koji-lens summary
$ koji-lens serveRequirements: Node.js 22+ / Claude Code session logs in ~/.claude/projects/.
๐ก koji-lens has a shorter alias lens (e.g. lens summary). Available from v0.1.0-beta.12.
Command reference
Organized into 4 groups by purpose. Run koji-lens <command> --help for details on any command.
Daily check
Commands for everyday usage tracking and session inspection.
# koji-lens summary
Show cost / token / tool usage summary for a period. Ends with a TOTAL block (overall aggregation) plus a note for subscription users (cost is API-equivalent, not actual billing).
| Flag / arg | Description |
|---|---|
| --since <expr> | Period (default: "24h"). E.g. 24h / 7d / 2w / ISO date |
| --format <format> | Output format: text | json (default: text) |
| --dir <path> | Claude Code log directory (default: config.logDir or ~/.claude/projects) |
| --usd-jpy <rate> | USD โ JPY conversion rate (default: config.usdJpy or 155) |
| --no-cache | Disable SQLite cache (full scan every time) |
Example:
$ koji-lens summary --since 7d --format json# koji-lens sessions
List sessions in a period, one line per session. Pick a session ID from this list, then drill into details with the session command.
| Flag / arg | Description |
|---|---|
| --since <expr> | Period (default: "7d") |
| --limit <n> | Number of sessions (default: 20) |
| --dir <path> | Claude Code log directory |
| --no-cache | Disable SQLite cache |
Example:
$ koji-lens sessions --since 24h --limit 5# koji-lens session <id>
Show full details of one session ID. Subagent IDs (with the agent- prefix) are also accepted; that case shows the subagent under the parent session.
| Flag / arg | Description |
|---|---|
| --format <format> | Output format: text | json |
| --dir <path> | Claude Code log directory |
| --usd-jpy <rate> | USD โ JPY conversion rate |
| --no-cache | Disable SQLite cache |
Example:
$ koji-lens session 055a662d-f09c-4541-b54c-7ad4a9130f3d# koji-lens serve
Launch a local web dashboard. Next.js standalone bundle is shipped with the CLI, so no extra install is needed. Cost trend charts, session list, and tool usage distribution are available.
| Flag / arg | Description |
|---|---|
| --port <port> | Port number (default: 3210) |
Example:
$ koji-lens serve --port 3210# koji-lens statusline
One-line statusline output for Claude Code's statusLine integration. Shows month-over-month usage trend with billingMode-aware framing: **subscription mode (default, Pro/Max users)** treats higher usage as ๐ sub value up (getting your money's worth) and under-usage as ๐ง under-utilized. **api mode (opt-in, API key users)** treats cost reduction as ๐ saved and cost increase as ๐จ cost up. Plus prompt cache hit rate (๐/๐ง/๐ง). Subscription examples: ๐ โ60% vs last month โ $30 more usage โ sub value up / ๐ง โ40% vs last month โ $40 less usage โ under-utilized / โช new (3d). Api examples (`koji-lens config set billing-mode api`): ๐ โ40% vs last month โ $40 saved / ๐จ โ60% vs last month โ $30 over โ cost up. Also integrates the audit anomaly signal (critical = ๐ก / warning = โ ): ๐ก sensitive=N (N sensitive-file writes detected) for critical, or โ +Nmcp exec=M (new MCP servers / high-frequency exec) for warning, appended at the end. --buddy adds a koji mascot (Lv1-10), --buddy-speech enables sayings (e.g., ๐ยท < Your call...). See the README statusline section for setup.
| Flag / arg | Description |
|---|---|
| --mode <density> | minimal | normal | detailed (default: normal) |
| --buddy | Append the koji mascot at the tail (Lv1-10 evolves with total session count) |
| --buddy-speech | Show buddy sayings (5 states ร 10 levels = 50 lines) |
| --buddy-type <type> | Mascot type (currently `koji` only; owl / cat coming later) |
| --buddy-locale <ja|en> | Saying locale (default: ja). Persistent: KOJI_LENS_BUDDY_LOCALE env var |
| --buddy-only | Show only the buddy (suppresses spend/cache/state). Implies --buddy --buddy-speech |
| --no-state | Suppress the agent state icon (โก/๐ค/๐) |
| --no-spend | Suppress the spend trend signal (๐/๐/๐จ/โช) |
| --no-cache-rate | Suppress the cache hit rate signal (๐ X%) |
| --format <format> | Output format: text | json |
Example:
$ koji-lens statusline --mode minimal --buddy --buddy-speech# koji-lens hook <state>
Cross-platform replacement for set-state.ps1 / set-state.sh. Updates ~/.koji-lens/state.json so the statusline can show โก/๐ค/๐. Use directly inside Claude Code hooks (no shell script required).
| Flag / arg | Description |
|---|---|
| <state> | thinking | running | idle | awaiting_approval |
Example:
$ koji-lens hook runningAnalysis & comparison
Period comparison and trend analysis for tracking improvements and model-switching decisions.
# koji-lens compare --before <range> --after <range>
Compare two periods (e.g., before vs after switching from Opus to Sonnet) to surface cost / token / model distribution deltas with rule-based insights.
| Flag / arg | Description |
|---|---|
| --before <range> | Source period (e.g., 7d, 30d, ISO date range) |
| --after <range> | Target period |
| --format <format> | Output format: text | json |
Example:
$ koji-lens compare --before 30d --after 7d# koji-lens trend
Weekly trend view. Shows changes in cache efficiency, p95 response time, and other time-series metrics. --with-attribution (Pro) flags vendor- vs user-attributed regressions.
| Flag / arg | Description |
|---|---|
| --weeks <n> | Number of weeks (default: 12) |
| --with-attribution | Proappend vendor / user attribution |
Example:
$ koji-lens trend --weeks 8Audit & budget
Security audit (tool_use history) and monthly budget tracking. Mostly Free, some Pro flags.
# koji-lens audit
Extract tool_use events into 7 categories (fs-read / fs-write / exec / fetch / task / mcp / other). PII (15 types: Email / Phone / API key / Bearer / Card / UUID / JWT / PEM Private Key / AWS Key / GCP Key / GitHub Token / Slack/Discord Webhook / IPv4 private, etc.) is auto-redacted by default (use --raw to disable). Statusline integration shows โ / ๐ก for new MCP servers, high-frequency exec, or sensitive file writes (examples: ๐ก sensitive=2 = 2 sensitive file writes detected / โ +1mcp = 1 new MCP server / โ exec=N = high-frequency exec). Free feature (cloud sync is Pro).
| Flag / arg | Description |
|---|---|
| --since <expr> | Period (e.g., 24h, default: 24h) |
| --category <cat> | fs-read | fs-write | exec | fetch | task | mcp | other |
| --tool <name> | Filter by exact tool name (e.g., Bash, Edit) |
| --format <format> | text | json (default: text) |
| --out <path> | Atomic file write (e.g., ~/.koji-lens/audit.log) |
| --learn-mcp | Mark detected MCP servers as known (clears statusline โ ) |
| --raw | Disable PII redaction (debug only, default ON for safety) |
| --sync | Procloud sync (Phase B 6/01-6/14, currently stub) |
Example:
$ koji-lens audit --since 7d --category exec --format json# koji-lens budget --budget <usd>
Monthly budget tracker. Shows month-to-date cumulative cost + linear forecast + over-budget warning. Multi-project budgets and config persistence available (Pro).
| Flag / arg | Description |
|---|---|
| --budget <usd> | Monthly budget in USD (required) |
| --with-alerts | Protrigger budget alerts |
| --project <key> | Proper-project budget |
| --list | Prolist all per-project budgets |
Example:
$ koji-lens budget --budget 200Data & config
Export and configuration file operations. Fully local.
# koji-lens export
Export usage data as CSV / JSON. Stdout output or file output. Aligned with the data ownership policy (everything stays local; no external transmission).
| Flag / arg | Description |
|---|---|
| --format <format> | csv | json (default: json) |
| --since <expr> | Period (e.g., 30d) |
| --out <path> | Output file path (stdout if omitted) |
Example:
$ koji-lens export --format csv --since 30d --out usage.csv# koji-lens config <action> [key] [value]
Operate ~/.koji-lens/config.json from the CLI.
| Flag / arg | Description |
|---|---|
| <action> | One of: get | set | unset | list | path |
| [key] | Config key (logDir | usdJpy) |
| [value] | Config value (only for set) |
Example:
$ koji-lens config set usdJpy 158Config
Settings are saved to ~/.koji-lens/config.json. Check the path with koji-lens config path.
Path to Claude Code logs. Defaults to ~/.claude/projects when unset. Override this when the install path differs (macOS / Windows / Linux).
USD โ JPY conversion rate. Defaults to 155 when unset. Update manually if you want the latest rate.
List current settings: koji-lens config list / Set or update: koji-lens config set usdJpy 158
FAQ
Click each question to expand.
Does the cost display make sense for Claude Pro / Max (subscription) users?
The displayed cost is API-equivalent (token count ร Anthropic public API price). Subscription users pay a flat fee, so treat the displayed cost as a "usage indicator" and a "decision aid for choosing between Sonnet and Opus." The TOTAL block in summary output also shows a note to that effect.
When does the cache get refreshed?
The CLI checks each JSONL file's mtime and re-parses only sessions that changed. Use --no-cache to force a full scan. The cache DB is stored at ~/.koji-lens/cache.db. Cache hits are about 6ร faster in practice.
Can I see the parent / child relationship for subagents?
Yes. Subagent session IDs are identified by the agent-* prefix, and the file path follows the structure <main-session-id>/subagents/agent-<id>.jsonl. Pass an agent- ID to the session command to drill into the subagent alone.
Are prompt bodies or API keys sent anywhere?
No. Everything runs locally on your machine. The SQLite cache deliberately does not store prompt bodies (only the metadata needed for aggregation). Safe to use under "no cloud" policies.
Does it work with Cursor / Cline / Aider?
Currently Claude Code only, but the internal design is adapter-based, and Cursor / Cline / Aider support is in OSS development. Track progress via GitHub Issues.
What's added in the Pro plan?
The Pro plan, launching July 1, 2026, will add cloud sync (unlimited history) / multi-device sync / CSV / JSON export / weekly / monthly email reports, and more. All Free plan features remain available. Get notified at the waitlist.
Where do I report bugs or feature requests?
GitHub Issues or Bluesky @kojihq.com โ feel free to drop a message. The support email is also support@kojihq.com.