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/.
Command reference
Five subcommands. Run koji-lens <command> --help for details.
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 jsonkoji-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 5koji-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-7ad4a9130f3dkoji-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 3210koji-lens statusline
One-line statusline output for Claude Code's statusLine integration. Shows month-over-month spend trend (💚/💛/🚨/⚪) + prompt cache hit rate (💎/🧊/💧). --buddy adds a koji mascot (Lv1-10), --buddy-speech enables sayings (e.g., 🍙· < Your call...). --combined co-displays ccusage output. 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 |
| --combined | Co-display ccusage statusline before koji-lens output (cross-platform; falls back gracefully if ccusage isn't installed) |
| --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 --combined --buddy --buddy-speechkoji-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 runningkoji-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 7dkoji-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 | Pro: append vendor / user attribution |
Example:
$ koji-lens trend --weeks 8koji-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 | Pro: trigger budget alerts |
| --project <key> | Pro: per-project budget |
| --list | Pro: list all per-project budgets |
Example:
$ koji-lens budget --budget 200koji-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.csvkoji-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
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 late May 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.
More
- ・GitHub repository — source, issues, discussions
- ・README — extra info for developers
- ・Releases / CHANGELOG — per-version change history
- ・npm package — @kojihq/lens
- ・Bluesky @kojihq.com — announcements and feedback
- ・support@kojihq.com — support contact