{"id":48864847,"url":"https://github.com/alfredvc/claude-usage-optimization","last_synced_at":"2026-05-02T13:03:44.660Z","repository":{"id":351573668,"uuid":"1211500780","full_name":"Alfredvc/claude-usage-optimization","owner":"Alfredvc","description":"Let Claude audit its own bill and find usage optimizations. Ingest your Claude Code transcripts into a local DuckDB and run SQL-backed cost analysis via agent skills.","archived":false,"fork":false,"pushed_at":"2026-04-15T16:34:21.000Z","size":1666,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-15T18:36:43.200Z","etag":null,"topics":["claude","claude-code","cli","llm-cost","token-usage","usage"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Alfredvc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-15T13:05:20.000Z","updated_at":"2026-04-15T16:34:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Alfredvc/claude-usage-optimization","commit_stats":null,"previous_names":["alfredvc/claude-usage-optimization"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Alfredvc/claude-usage-optimization","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alfredvc%2Fclaude-usage-optimization","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alfredvc%2Fclaude-usage-optimization/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alfredvc%2Fclaude-usage-optimization/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alfredvc%2Fclaude-usage-optimization/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Alfredvc","download_url":"https://codeload.github.com/Alfredvc/claude-usage-optimization/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alfredvc%2Fclaude-usage-optimization/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32532059,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T01:12:54.858Z","status":"online","status_checked_at":"2026-05-02T02:00:05.923Z","response_time":132,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-code","cli","llm-cost","token-usage","usage"],"created_at":"2026-04-15T18:02:52.572Z","updated_at":"2026-05-02T13:03:44.654Z","avatar_url":"https://github.com/Alfredvc.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eClaude Usage Optimization\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/readme_banner.png\" alt=\"Claude Usage Optimization banner\" width=\"800\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/alfredvc/claude-usage-optimization/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/alfredvc/claude-usage-optimization/ci.yml?branch=main\u0026label=CI\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/alfredvc/claude-usage-optimization/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/alfredvc/claude-usage-optimization\" alt=\"Release\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://crates.io/crates/claude-code-transcripts-ingest\"\u003e\u003cimg src=\"https://img.shields.io/crates/v/claude-code-transcripts-ingest.svg\" alt=\"crates.io\" /\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE-MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue\" alt=\"License: MIT OR Apache-2.0\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n**Let Claude audit its own bill.** Agent skills that turn every transcript under `~/.claude/projects` into a local DuckDB, then let Claude run SQL over your own history and return a dollar-ranked optimization report. Actionable insights backed by your own usage, not generic advice.\n\nSkills pair with `claude-code-transcripts-ingest` (`cct`), the Rust binary in this repo that ingests your transcripts into DuckDB.\n\n## Install\n\n### 1. Skills\n\nInstall for Claude Code\n\n```bash\nnpx skills add alfredvc/claude-usage-optimization\n```\n\n### 2. `cct` (required)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Alfredvc/claude-usage-optimization/main/install.sh | sh\n```\n\nDownloads the latest prebuilt `cct` binary into `~/.local/bin`. Override with `CCT_INSTALL_DIR=/some/dir` or pin a version with `CCT_VERSION=v0.2.0`. Source: [`crates/claude-code-transcripts-ingest/`](crates/claude-code-transcripts-ingest/).\n\n### 3. DuckDB CLI (required)\n\nSkills query the DB via the `duckdb` CLI. Install from [duckdb.org](https://duckdb.org/install/?platform=macos\u0026environment=cli) or:\n\n```bash\ncurl https://install.duckdb.org | sh\n```\n\n## Quickstart\n\n```bash\ncct ingest\n```\n\nThen ask Claude `/optimize-usage`.\n\nThe skill runs a multi-phase investigation against your own DB: measures spend categories, inspects raw high-cost turns, disconfirms shallow leads, then ranks concrete levers by dollar impact.\n\n## Tips\nIf you have any hypothesis as to what could be consuming your usage, ask Claude, it is excellent at testing them with cct.\n\n## Available skills\n\n- **claude-usage-db** — schema and SQL recipes so Claude can query the transcripts DB efficiently.\n- **optimize-usage** — gives Claude the tools to investigate your usage and return concrete, dollar-ranked fixes to reduce it. Built on `claude-usage-db`.\n\n## Explore sessions in the viewer\n\n`cct serve` opens an embedded web viewer at `http://localhost:8766`. Pick a project → session to drill in turn-by-turn.\n\n- **Per-turn cost.** Each assistant turn shows model, timestamp, and dollar cost — with input / cache-read / cache-write / output split as colored bars against the session total.\n- **Activity at a glance.** Pills tag what the turn did: thinking (💭), text (💬), tool calls (🔧). An activity panel rolls up cost and call count per tool so the budget-eaters stand out.\n- **Subagent expansion.** Subagent calls expand inline and lazy-load their full transcript, so you can trace delegated work — and its cost — back to the parent turn that spawned it.\n- **Cumulative cost chart.** Area chart above the timeline plots spend over the whole session. Click any dot to jump to and highlight that turn.\n- **Session rollup.** Fixed header shows total cost, API call count, and token totals by type.\n- **Sort by cost or date.** Session list can sort by most recent or highest spend, so expensive sessions float to the top.\n\nThe **Dashboard** tab shows a multi-panel cost breakdown split into two sub-tabs:\n\n- **Overview** — general spend picture: daily spend by model, sessions/week, token-type cost split, model breakdown, errors.\n- **Outliers** — actionable panels: most-expensive turns, top sessions, context-size distribution, cache invalidation events, artifact leaderboards, file hotspots, and more.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/sessions.png\" alt=\"Session list: filter by cost, project, tool, subagents\" width=\"800\" /\u003e\n  \u003cbr/\u003e\n  \u003cem\u003eSession list — sortable by cost or time, filter on project, tool, model, subagents.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/transcripts.png\" alt=\"Session transcript: per-turn cost and tool timeline\" width=\"800\" /\u003e\n  \u003cbr/\u003e\n  \u003cem\u003eSession view — per-turn cost, cache/token split, tool calls and thinking inline.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/dashboard.png\" alt=\"Dashboard: spend breakdown by model and time\" width=\"800\" /\u003e\n  \u003cbr/\u003e\n  \u003cem\u003eDashboard — daily spend by model, sessions/week, outlier turns.\u003c/em\u003e\n\u003c/p\u003e\n\n## `cct` reference\n\nFull `cct` reference can be found in [`crates/claude-code-transcripts-ingest/README.md`](crates/claude-code-transcripts-ingest/README.md).\n\n## Workspace\n\n```\ncrates/claude-code-transcripts/              # typed parser library (no DuckDB)\ncrates/claude-code-transcripts-ingest/       # `cct` binary (ingest + serve)\ncrates/claude-code-transcripts-ingest/web/   # embedded React viewer (index.html)\nskills/                                      # agent skills (see above)\n```\n\nThe parser crate ([`claude-code-transcripts`](https://crates.io/crates/claude-code-transcripts)) is independently usable — strongly-typed `Entry` variants and a round-trip validator for catching schema drift.\n\n## Development\n\n- `cargo build` — build workspace\n- `cargo test` — unit + integration tests\n- `cargo clippy --all-targets --all-features`\n- `cargo fmt`\n- Pre-commit hook (`.git/hooks/pre-commit`) runs `fmt` + `clippy`\n\n## Release\n\nReleases are driven by [`cargo-release`](https://github.com/crate-ci/cargo-release) locally and the tag-triggered [`release.yml`](.github/workflows/release.yml) workflow in CI.\n\n1. On `main`, bump the shared workspace version:\n\n   ```sh\n   cargo release patch --execute    # or minor / major\n   ```\n\n   Per [`release.toml`](release.toml) this bumps `Cargo.toml`, commits `chore: release vX.Y.Z`, tags `vX.Y.Z`, and pushes both.\n\n2. Pushing the `vX.Y.Z` tag triggers [`release.yml`](.github/workflows/release.yml), which:\n   - Creates a draft GitHub release with auto-generated notes.\n   - Builds `cct` binaries for linux/macos × x86_64/aarch64 and uploads tarballs + `.sha256` files.\n   - Publishes `claude-code-transcripts`, then `claude-code-transcripts-ingest`, to crates.io.\n   - Flips the release from draft to published.\n\nRequirements: `cargo install cargo-release` locally, write access to push tags, and the `CARGO_REGISTRY_TOKEN` repo secret configured.\n\n## License\n\nDual-licensed under [MIT](LICENSE-MIT) OR [Apache-2.0](LICENSE-APACHE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falfredvc%2Fclaude-usage-optimization","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falfredvc%2Fclaude-usage-optimization","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falfredvc%2Fclaude-usage-optimization/lists"}