/tokf-discover

name: tokf-discover
description: Find missed token savings in Claude Code sessions and create filters for unfiltered commands
user_invocable: true

tokf discover — Find Missed Token Savings

Use this skill to analyze Claude Code sessions and find commands that are running without tokf filtering, wasting tokens on verbose output.

Quick Start

Run `tokf discover` in the project directory to scan recent sessions:

tokf discover

Options

• `--all` — scan all projects, not just the current one
• `--since 7d` — only scan sessions from the last 7 days (also `24h`, `30m`)
• `--limit 0` — show all results (default: top 20)
• `--json` — output as JSON for programmatic use
• `--session <path>` — scan a specific session file
• `--project <path>` — scan sessions for a specific project path

Interpreting Results

The output shows:

• **COMMAND** — the shell command pattern being run without filtering
• **FILTER** — the tokf filter that would handle it
• **RUNS** — how many times it appeared in sessions
• **TOKENS** — estimated token count of unfiltered output
• **SAVINGS** — estimated tokens that filtering would save

Workflow

1. Run `tokf discover` to identify top savings opportunities 2. For commands with existing filters: run `tokf hook install` to set up automatic filtering 3. For commands without filters: use `/tokf-filter` skill to create a custom filter 4. Re-run `tokf discover` after changes to verify improvement

Creating Filters for Unfiltered Commands

If `tokf discover` shows commands with no matching filter, create one:

# See what a filter would look like
tokf which "the-command --args"

# Use the tokf-filter skill to create a proper filter
# /tokf-filter

JSON Output

Use `--json` for integration with other tools:

tokf discover --json | jq '.results[] | select(.estimated_savings > 1000)'

The JSON schema includes:

• `sessions_scanned` — number of JSONL files processed
• `total_commands` — all Bash commands found
• `already_filtered` — commands already using tokf
• `filterable_commands` — commands with available filters
• `no_filter_commands` — commands with no matching filter
• `estimated_total_savings` — total estimated token savings
• `results[]` — per-command breakdown sorted by savings