├── .claude
└── commands
│ ├── analyze-code.md
│ ├── lsmcp-onboarding.md
│ ├── reduce-similarities.md
│ └── refactor.md
├── .github
├── FUNDING.yaml
├── renovate.json
└── workflows
│ ├── check-pr-title.yaml
│ ├── ci.yaml
│ └── release.yaml
├── .gitignore
├── .lsmcp
├── config.json
└── memories
│ └── symbol_index_info.md
├── .mcp.json
├── .npmrc
├── CLAUDE.md
├── LICENSE
├── README.md
├── bun.lock
├── docs
├── .gitignore
├── .vitepress
│ └── config.ts
├── guide
│ ├── blocks-reports.md
│ ├── configuration.md
│ ├── cost-modes.md
│ ├── custom-paths.md
│ ├── daily-reports.md
│ ├── getting-started.md
│ ├── index.md
│ ├── installation.md
│ ├── json-output.md
│ ├── library-usage.md
│ ├── live-monitoring.md
│ ├── mcp-server.md
│ ├── monthly-reports.md
│ ├── related-projects.md
│ ├── session-reports.md
│ ├── sponsors.md
│ ├── statusline.md
│ └── weekly-reports.md
├── index.md
├── package.json
├── public
│ ├── blocks-live.png
│ ├── claude_code_protips_thumbnail_v1.png
│ ├── favicon.svg
│ ├── logo.png
│ ├── logo.svg
│ ├── mcp-claude-desktop.avif
│ └── screenshot.png
├── tsconfig.json
├── typedoc.config.mjs
├── update-api-index.ts
└── wrangler.jsonc
├── eslint.config.js
├── package.json
├── src
├── _consts.ts
├── _daily-grouping.ts
├── _jq-processor.ts
├── _json-output-types.ts
├── _live-monitor.ts
├── _live-rendering.ts
├── _macro.ts
├── _project-names.ts
├── _session-blocks.ts
├── _shared-args.ts
├── _terminal-utils.ts
├── _token-utils.ts
├── _types.ts
├── _utils.ts
├── calculate-cost.ts
├── commands
│ ├── _blocks.live.ts
│ ├── blocks.ts
│ ├── daily.ts
│ ├── index.ts
│ ├── mcp.ts
│ ├── monthly.ts
│ ├── session.ts
│ ├── statusline.ts
│ └── weekly.ts
├── data-loader.ts
├── debug.ts
├── index.ts
├── logger.ts
├── mcp.ts
└── pricing-fetcher.ts
├── test
└── statusline-test.json
├── tsconfig.json
├── tsdown.config.ts
├── typos.toml
└── vitest.config.ts
/.claude/commands/analyze-code.md:
--------------------------------------------------------------------------------
1 | # Code Analysis with LSMCP MCP
2 |
3 | This command uses the LSMCP (Language Server MCP) tools to perform rapid semantic code analysis, leveraging language server capabilities for more accurate results than traditional grep/search approaches.
4 |
5 | ## Overview
6 |
7 | LSMCP provides semantic code analysis through language server protocol, enabling:
8 |
9 | - Type-aware error detection
10 | - Symbol reference tracking
11 | - Cross-file dependency analysis
12 | - Real-time diagnostics
13 |
14 | ## Command Template
15 |
16 | ```markdown
17 | # Rapid Code Analysis Task
18 |
19 | Project Root: <PROJECT_PATH>
20 | Target Language: <LANGUAGE>
21 | Analysis Goal: <SPECIFIC_GOAL>
22 |
23 | Execute the following analysis phases:
24 |
25 | ## Phase 1: Capability Check (5 seconds)
26 |
27 | Verify available LSP features:
28 | ```
29 |
30 | mcp**lsmcp-<ADAPTER>**check_capabilities
31 |
32 | ```
33 |
34 | ## Phase 2: Project-wide Diagnostics (10 seconds)
35 | Collect all errors and warnings:
36 | ```
37 |
38 | mcp**lsmcp-<ADAPTER>**get_all_diagnostics
39 |
40 | - root: "<PROJECT_PATH>"
41 | - pattern: "\*_/_.<FILE_EXTENSION>"
42 | - severityFilter: "error" # Start with errors only
43 | - useGitignore: true
44 |
45 | ```
46 |
47 | If few errors found, repeat with severityFilter: "warning"
48 |
49 | ## Phase 3: Symbol Analysis (5 seconds per symbol)
50 | For critical functions/classes:
51 | ```
52 |
53 | mcp**lsmcp-<ADAPTER>**find_references
54 |
55 | - root: "<PROJECT_PATH>"
56 | - filePath: "<RELATIVE_FILE_PATH>"
57 | - line: <LINE_NUMBER>
58 | - symbolName: "<SYMBOL_NAME>"
59 |
60 | ```
61 |
62 | ## Phase 4: Type Verification (3 seconds per location)
63 | For suspicious code locations:
64 | ```
65 |
66 | mcp**lsmcp-<ADAPTER>**get_hover
67 |
68 | - root: "<PROJECT_PATH>"
69 | - filePath: "<RELATIVE_FILE_PATH>"
70 | - line: <LINE_NUMBER>
71 | - target: "<CODE_SNIPPET>"
72 |
73 | ```
74 |
75 | ## Phase 5: Unused Code Detection
76 | Identify symbols with zero references:
77 | ```
78 |
79 | mcp**lsmcp-<ADAPTER>**find_references
80 |
81 | - Check exported functions/classes
82 | - Flag items with 0 references
83 |
84 | ```
85 |
86 | ## Report Format
87 | 1. Executive Summary
88 | - Total errors/warnings count
89 | - Critical issues requiring immediate attention
90 |
91 | 2. Detailed Findings
92 | - Group by severity (Error > Warning > Info)
93 | - Include file:line references
94 | - Show affected symbol names
95 |
96 | 3. Impact Analysis
97 | - Number of files affected
98 | - Cross-module dependencies
99 |
100 | 4. Recommendations
101 | - Priority fixes
102 | - Refactoring suggestions
103 | - Code quality improvements
104 | ```
105 |
106 | ## Supported Language Adapters
107 |
108 | | Language | Adapter Name | File Extension | Special Notes |
109 | | --------------------- | ------------ | -------------------- | -------------------------------- |
110 | | TypeScript/JavaScript | tsgo-dev | .ts, .tsx, .js, .jsx | Limited rename/workspace symbols |
111 | | Python | python-dev | .py | Full LSP support |
112 | | Rust | rust-dev | .rs | Requires rust-analyzer |
113 | | Go | go-dev | .go | Requires gopls |
114 | | F# | fsharp-dev | .fs, .fsx | Requires fsautocomplete |
115 |
116 | ## Example Usage
117 |
118 | ### TypeScript Project Analysis
119 |
120 | ```markdown
121 | Project Root: /home/user/my-ts-project
122 | Target Language: typescript
123 | Analysis Goal: Find type errors and unused exports
124 |
125 | ## Phase 1: Capability Check
126 |
127 | mcp**lsmcp-tsgo-dev**check_capabilities
128 |
129 | ## Phase 2: Project-wide Diagnostics
130 |
131 | mcp**lsmcp-tsgo-dev**get_all_diagnostics
132 |
133 | - root: "/home/user/my-ts-project"
134 | - pattern: "src/\*_/_.ts"
135 | - severityFilter: "error"
136 | ```
137 |
138 | ### Python Code Quality Check
139 |
140 | ```markdown
141 | Project Root: /home/user/my-python-app
142 | Target Language: python
143 | Analysis Goal: Identify undefined variables and import issues
144 |
145 | ## Phase 1: Capability Check
146 |
147 | mcp**lsmcp-python-dev**check_capabilities
148 |
149 | ## Phase 2: Project-wide Diagnostics
150 |
151 | mcp**lsmcp-python-dev**get_all_diagnostics
152 |
153 | - root: "/home/user/my-python-app"
154 | - pattern: "\*_/_.py"
155 | - severityFilter: "error"
156 | ```
157 |
158 | ## Performance Expectations
159 |
160 | - **Phase 1**: Instant (<1s)
161 | - **Phase 2**: 5-30s depending on project size
162 | - **Phase 3**: 2-5s per symbol
163 | - **Phase 4**: 1-3s per hover request
164 | - **Phase 5**: 10-60s for full project scan
165 |
166 | ## Advantages over Traditional Search
167 |
168 | 1. **Semantic Accuracy**: Understands language constructs, not just text patterns
169 | 2. **Type Awareness**: Catches type mismatches and incompatibilities
170 | 3. **Cross-file Intelligence**: Tracks references across module boundaries
171 | 4. **Real-time Feedback**: Uses pre-indexed LSP data for instant results
172 |
173 | ## Limitations
174 |
175 | - Requires language server support for the target language
176 | - Some features may be limited by specific language server implementations
177 | - Initial indexing may take time for large projects
178 | - Memory usage scales with project size
179 |
180 | ## High-Level Analysis Tools
181 |
182 | LSMCP now includes high-level analysis tools that provide faster symbol search and indexing capabilities:
183 |
184 | ### Symbol Indexing Tools
185 |
186 | 1. **index_files** - Build or update the symbol index
187 |
188 | ```
189 | mcp__lsmcp-<ADAPTER>__index_files
190 | - pattern: "**/*.ts"
191 | - root: "/project/path"
192 | - concurrency: 5
193 | ```
194 |
195 | 2. **find_symbol** - Fast symbol search using the index
196 |
197 | ```
198 | mcp__lsmcp-<ADAPTER>__find_symbol
199 | - name: "MyClass" # Optional: partial matching supported
200 | - kind: ["Class", "Interface"] # Optional: filter by symbol types
201 | - file: "src/models.ts" # Optional: search within specific file
202 | - includeChildren: true # Include nested symbols
203 | ```
204 |
205 | 3. **get_file_symbols** - Get all symbols in a file from index
206 |
207 | ```
208 | mcp__lsmcp-<ADAPTER>__get_file_symbols
209 | - filePath: "src/components/Button.tsx"
210 | ```
211 |
212 | 4. **get_index_stats** - View index statistics
213 |
214 | ```
215 | mcp__lsmcp-<ADAPTER>__get_index_stats
216 | ```
217 |
218 | 5. **clear_index** - Clear the symbol index
219 | ```
220 | mcp__lsmcp-<ADAPTER>__clear_index
221 | ```
222 |
223 | ### Example: Fast Symbol Search Workflow
224 |
225 | ```markdown
226 | # Step 1: Build the index
227 |
228 | mcp**lsmcp-tsgo-dev**index_files
229 |
230 | - pattern: "src/\*_/_.ts"
231 | - concurrency: 10
232 |
233 | # Step 2: Find all classes and interfaces
234 |
235 | mcp**lsmcp-tsgo-dev**find_symbol
236 |
237 | - kind: ["Class", "Interface"]
238 |
239 | # Step 3: Search for specific symbol
240 |
241 | mcp**lsmcp-tsgo-dev**find_symbol
242 |
243 | - name: "User"
244 | - includeChildren: true
245 |
246 | # Step 4: Get detailed symbols for a file
247 |
248 | mcp**lsmcp-tsgo-dev**get_file_symbols
249 |
250 | - filePath: "src/models/User.ts"
251 | ```
252 |
253 | ### Performance Benefits
254 |
255 | - **Initial indexing**: 5-30 seconds for large projects
256 | - **Symbol queries**: <100ms (vs 1-5 seconds with LSP)
257 | - **File updates**: Automatic reindexing on changes
258 | - **Memory efficient**: Indexed data structure
259 |
260 | ## Tips for Effective Analysis
261 |
262 | 1. Start with error-level diagnostics before checking warnings
263 | 2. Focus on high-traffic symbols (frequently imported/used)
264 | 3. Use specific file patterns to narrow scope when needed
265 | 4. Combine with traditional grep for text-pattern searches
266 | 5. Run analysis after significant refactoring to catch regressions
267 | 6. Build symbol index once at the start for faster repeated queries
268 | 7. Use partial name matching for flexible symbol search
269 |
--------------------------------------------------------------------------------
/.claude/commands/lsmcp-onboarding.md:
--------------------------------------------------------------------------------
1 | start lsmcp onboarding
2 |
--------------------------------------------------------------------------------
/.claude/commands/reduce-similarities.md:
--------------------------------------------------------------------------------
1 | Run `similarity-ts .` to detect semantic code similarities. Execute this command, analyze the duplicate code patterns, and create a refactoring plan. Check `similarity-ts -h` for detailed options.
2 |
--------------------------------------------------------------------------------
/.claude/commands/refactor.md:
--------------------------------------------------------------------------------
1 | # Refactor Command
2 |
3 | When I need to refactor TypeScript code in this project, follow these steps:
4 |
5 | ## 1. Analyze Current Code Structure
6 |
7 | - Use `mcp_lsmcp__get_module_symbols` to understand module exports
8 | - Use `mcp_lsmcp__get_type_at_symbol` to analyze type information
9 | - Use `mcp_lsmcp__find_references` to find all usages before refactoring
10 |
11 | ## 2. Choose Appropriate Refactoring Tools
12 |
13 | ### For Symbol Operations
14 |
15 | - **Rename**: Use `mcp_lsmcp__rename_symbol` instead of Edit/MultiEdit
16 | - **Delete**: Use `mcp_lsmcp__delete_symbol` to remove symbols and their references
17 | - **Find usages**: Use `mcp_lsmcp__find_references` instead of grep
18 |
19 | ### For File Operations
20 |
21 | - **Move file**: Use `mcp_lsmcp__move_file` instead of bash mv
22 | - **Move directory**: Use `mcp_lsmcp__move_directory` for entire directories
23 |
24 | ### For Type Analysis
25 |
26 | - **Get type info**: Use `mcp_lsmcp__get_type_at_symbol`
27 | - **Module analysis**: Use `mcp_lsmcp__get_module_symbols`
28 | - **Scope analysis**: Use `mcp_lsmcp__get_symbols_in_scope`
29 |
30 | ## 3. Verify Changes
31 |
32 | After refactoring:
33 |
34 | 1. Run `pnpm typecheck` to ensure no TypeScript errors
35 | 2. Run `pnpm lint` to check code style
36 | 3. Run `pnpm test` to verify functionality
37 | 4. Use `mcp_lsmcp__get_diagnostics` to check for issues
38 |
39 | ## 4. Common Refactoring Patterns
40 |
41 | ### Extract Interface/Type
42 |
43 | 1. Identify the type structure using `get_type_at_symbol`
44 | 2. Create new type definition file
45 | 3. Use `rename_symbol` to update references
46 |
47 | ### Move Module
48 |
49 | 1. Use `move_file` or `move_directory`
50 | 2. Tool automatically updates all imports
51 | 3. Verify with `get_diagnostics`
52 |
53 | ### Rename Across Project
54 |
55 | 1. Use `find_references` to see impact
56 | 2. Use `rename_symbol` for safe renaming
57 | 3. Check affected files with `git status`
58 |
59 | ## 5. Best Practices
60 |
61 | - Always use TypeScript MCP tools for semantic operations
62 | - Never use text-based Edit/MultiEdit for refactoring
63 | - Check references before deleting or moving
64 | - Run tests after each refactoring step
65 | - Commit frequently with descriptive messages
66 |
67 | ## Example Commands
68 |
69 | ```bash
70 | # Rename a function across the project
71 | > Use mcp_lsmcp__rename_symbol to rename processData to transformData in src/utils.ts
72 |
73 | # Move a module to a new location
74 | > Use mcp_lsmcp__move_file to move src/helpers/parser.ts to src/core/parser.ts
75 |
76 | # Find all usages before refactoring
77 | > Use mcp_lsmcp__find_references for the Parser class in src/parser.ts
78 | ```
79 |
--------------------------------------------------------------------------------
/.github/FUNDING.yaml:
--------------------------------------------------------------------------------
1 | github: ryoppippi
2 |
--------------------------------------------------------------------------------
/.github/renovate.json:
--------------------------------------------------------------------------------
1 | {
2 | "$schema": "https://docs.renovatebot.com/renovate-schema.json",
3 | "vulnerabilityAlerts": {
4 | "labels": ["security"]
5 | },
6 | "labels": ["dependencies", "renovate"],
7 | "rangeStrategy": "bump",
8 | "lockFileMaintenance": {
9 | "enabled": true
10 | },
11 | "platformAutomerge": true,
12 | "dependencyDashboard": false,
13 | "automerge": true,
14 | "branchConcurrentLimit": 0,
15 | "stabilityDays": 3
16 | }
17 |
--------------------------------------------------------------------------------
/.github/workflows/check-pr-title.yaml:
--------------------------------------------------------------------------------
1 | name: Check PR title
2 |
3 | on:
4 | pull_request:
5 | types:
6 | - opened
7 | - reopened
8 | - edited
9 | - synchronize
10 |
11 | permissions:
12 | pull-requests: read
13 |
14 | jobs:
15 | main:
16 | name: Validate PR title
17 | runs-on: ubuntu-latest
18 | steps:
19 | - uses: amannn/action-semantic-pull-request@0723387faaf9b38adef4775cd42cfd5155ed6017 # v5.5.3
20 | env:
21 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
22 | with:
23 | ignoreLabels: |
24 | autorelease: pending
25 | dependencies
26 |
--------------------------------------------------------------------------------
/.github/workflows/ci.yaml:
--------------------------------------------------------------------------------
1 | name: CI
2 |
3 | on:
4 | push:
5 | pull_request:
6 |
7 | jobs:
8 | lint-check:
9 | runs-on: ubuntu-latest
10 |
11 | steps:
12 | - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
13 | - uses: oven-sh/setup-bun@735343b667d3e6f658f44d0eca948eb6282f2b76 # v2.0.2
14 | with:
15 | bun-version: latest
16 | - run: bun install --frozen-lockfile
17 | - run: bun lint
18 | - run: bun typecheck
19 |
20 | test:
21 | runs-on: ubuntu-latest
22 |
23 | steps:
24 | - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
25 | - uses: oven-sh/setup-bun@735343b667d3e6f658f44d0eca948eb6282f2b76 # v2.0.2
26 | with:
27 | bun-version: latest
28 | - run: bun install --frozen-lockfile
29 | - name: Check jq is available
30 | run: which jq && jq --version
31 | - name: Create default Claude directories for tests
32 | run: |
33 | mkdir -p $HOME/.claude/projects
34 | mkdir -p $HOME/.config/claude/projects
35 | - run: bun run test
36 |
37 | npm-publish-dry-run-and-upload-pkg-pr-now:
38 | runs-on: ubuntu-latest
39 |
40 | steps:
41 | - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
42 | - uses: oven-sh/setup-bun@735343b667d3e6f658f44d0eca948eb6282f2b76 # v2.0.2
43 | with:
44 | bun-version: latest
45 | - run: bun install --frozen-lockfile
46 | - run: bunx pkg-pr-new publish
47 |
48 | spell-check:
49 | runs-on: ubuntu-latest
50 | steps:
51 | - name: Checkout Actions Repository
52 | uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
53 |
54 | - uses: crate-ci/typos@master
55 | with:
56 | config: ./typos.toml
57 |
--------------------------------------------------------------------------------
/.github/workflows/release.yaml:
--------------------------------------------------------------------------------
1 | name: npm publish
2 |
3 | on:
4 | push:
5 | tags:
6 | - '*'
7 |
8 | jobs:
9 | npm:
10 | runs-on: ubuntu-latest
11 | timeout-minutes: 10
12 | permissions:
13 | contents: read
14 | id-token: write
15 | steps:
16 | - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
17 | with:
18 | fetch-depth: 0
19 | - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
20 | with:
21 | registry-url: 'https://registry.npmjs.org'
22 | node-version: ${{env.NODE_VERSION}}
23 | - uses: oven-sh/setup-bun@735343b667d3e6f658f44d0eca948eb6282f2b76 # v2.0.2
24 | - run: bun install --frozen-lockfile
25 | - run: npm publish --provenance --no-git-checks --access public
26 | env:
27 | NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
28 | NPM_CONFIG_PROVENANCE: true
29 | working-directory: ${{env.PACKAGE_DIR}}
30 |
31 | release:
32 | needs:
33 | - npm
34 | runs-on: ubuntu-latest
35 | permissions:
36 | contents: write
37 | steps:
38 | - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
39 | with:
40 | fetch-depth: 0
41 | - uses: oven-sh/setup-bun@735343b667d3e6f658f44d0eca948eb6282f2b76 # v2.0.2
42 | with:
43 | bun-version: latest
44 | - run: bun x changelogithub
45 | env:
46 | GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
47 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | # dependencies (bun install)
2 | node_modules
3 |
4 | # output
5 | out
6 | dist
7 | *.tgz
8 |
9 | # code coverage
10 | coverage
11 | *.lcov
12 |
13 | # logs
14 | logs
15 | _.log
16 | report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
17 |
18 | # dotenv environment variable files
19 | .env
20 | .env.development.local
21 | .env.test.local
22 | .env.production.local
23 | .env.local
24 |
25 | # caches
26 | .eslintcache
27 | .cache
28 | *.tsbuildinfo
29 |
30 | # IntelliJ based IDEs
31 | .idea
32 |
33 | # Finder (MacOS) folder config
34 | .DS_Store
35 |
36 | .eslintcache
37 |
38 | # lsmcp cache
39 | .lsmcp/cache
40 |
--------------------------------------------------------------------------------
/.lsmcp/config.json:
--------------------------------------------------------------------------------
1 | {
2 | "preset": "tsgo"
3 | }
4 |
--------------------------------------------------------------------------------
/.lsmcp/memories/symbol_index_info.md:
--------------------------------------------------------------------------------
1 | ---
2 | created: 2025-08-10T20:53:29.066Z
3 | updated: 2025-08-10T20:53:29.066Z
4 | ---
5 |
6 | # ccusage Symbol Index Configuration
7 |
8 | ## Project Information
9 |
10 | - **Language**: TypeScript
11 | - **Root Directory**: /Users/ryoppippi/ghq/github.com/ryoppippi/ccusage
12 | - **Indexing Date**: 2025-08-10
13 |
14 | ## Index Configuration
15 |
16 | - **Pattern Used**: `**/*.ts`
17 | - **Files Indexed**: 32
18 | - **Total Symbols**: 197
19 | - **Average Indexing Time**: 243ms per file
20 |
21 | ## Project Structure
22 |
23 | - Main source code: `src/` directory
24 | - Test files: `test/` directory
25 | - Documentation: `docs/` directory
26 | - Configuration files: Root directory (tsconfig.json, vitest.config.ts, etc.)
27 |
28 | ## Key Observations
29 |
30 | - Project is a CLI tool for analyzing Claude Code usage
31 | - Uses TypeScript with strict mode
32 | - Built with gunshi CLI framework
33 | - Has MCP server integration
34 | - Includes comprehensive test coverage with in-source testing
35 |
36 | ## Symbol Search Examples
37 |
38 | - Search by name: `search_symbol_from_index { "name": "main", "root": "/Users/ryoppippi/ghq/github.com/ryoppippi/ccusage" }`
39 | - Search by kind: `search_symbol_from_index { "kind": "Function", "root": "/Users/ryoppippi/ghq/github.com/ryoppippi/ccusage" }`
40 | - Get file symbols: `get_document_symbols { "filePath": "src/data-loader.ts", "root": "/Users/ryoppippi/ghq/github.com/ryoppippi/ccusage" }`
41 |
42 | ## Notes
43 |
44 | - LSP server successfully recognizes TypeScript files
45 | - Index updates automatically with file changes
46 | - Use incremental updates for better performance on subsequent runs
47 |
--------------------------------------------------------------------------------
/.mcp.json:
--------------------------------------------------------------------------------
1 | {
2 | "mcpServers": {
3 | "context7": {
4 | "type": "sse",
5 | "url": "https://mcp.context7.com/sse"
6 | },
7 | "gunshi-doc": {
8 | "command": "bun",
9 | "args": [
10 | "x",
11 | "sitemcp",
12 | "https://gunshi.dev/",
13 | "--concurrency 10",
14 | "--no-cache"
15 | ]
16 | },
17 | "eslint-mcp": {
18 | "type": "stdio",
19 | "command": "bun",
20 | "args": [
21 | "x",
22 | "@eslint/mcp@latest"
23 | ],
24 | "env": {}
25 | },
26 | "@praha/byethrow": {
27 | "type": "stdio",
28 | "command": "bun",
29 | "args": [
30 | "byethrow-mcp"
31 | ],
32 | "env": {}
33 | },
34 | "lsmcp": {
35 | "command": "bun",
36 | "args": [
37 | "lsmcp",
38 | "-p",
39 | "tsgo"
40 | ]
41 | }
42 | }
43 | }
44 |
--------------------------------------------------------------------------------
/.npmrc:
--------------------------------------------------------------------------------
1 | @jsr:registry=https://npm.jsr.io
2 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2025 ryoppippi
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | <div align="center">
2 | <img src="https://cdn.jsdelivr.net/gh/ryoppippi/ccusage@main/docs/public/logo.svg" alt="ccusage logo" width="256" height="256">
3 | <h1>ccusage</h1>
4 | </div>
5 |
6 | <p align="center">
7 | <a href="https://npmjs.com/package/ccusage"><img src="https://img.shields.io/npm/v/ccusage?color=yellow" alt="npm version" /></a>
8 | <a href="https://tanstack.com/stats/npm?packageGroups=%5B%7B%22packages%22:%5B%7B%22name%22:%22ccusage%22%7D%5D%7D%5D&range=30-days&transform=none&binType=daily&showDataMode=all&height=400"><img src="https://img.shields.io/npm/dy/ccusage" alt="NPM Downloads" /></a>
9 | <a href="https://packagephobia.com/result?p=ccusage"><img src="https://packagephobia.com/badge?p=ccusage" alt="install size" /></a>
10 | <a href="https://deepwiki.com/ryoppippi/ccusage"><img src="https://img.shields.io/badge/DeepWiki-ryoppippi%2Fccusage-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==" alt="DeepWiki"></a>
11 | <!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ -->
12 | <a href="https://claudelog.com/"><img src="https://claudelog.com/img/claude_log_badge.svg" alt="ClaudeLog - A comprehensive knowledge base for Claude." /></a>
13 | <a href="https://github.com/hesreallyhim/awesome-claude-code"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code" /></a>
14 | </p>
15 |
16 | <div align="center">
17 | <img src="https://cdn.jsdelivr.net/gh/ryoppippi/ccusage@main/docs/public/screenshot.png">
18 | </div>
19 |
20 | > Analyze your Claude Code token usage and costs from local JSONL files — incredibly fast and informative!
21 |
22 | ## Installation
23 |
24 | ### Quick Start (Recommended)
25 |
26 | Thanks to ccusage's incredibly small bundle size ([](https://packagephobia.com/result?p=ccusage)), you can run it directly without installation:
27 |
28 | ```bash
29 | # Using bunx (recommended for speed)
30 | bunx ccusage
31 |
32 | # Using npx
33 | npx ccusage@latest
34 |
35 | # Using deno (with security flags)
36 | deno run -E -R=$HOME/.claude/projects/ -S=homedir -N='raw.githubusercontent.com:443' npm:ccusage@latest
37 | ```
38 |
39 | > 💡 **Tip**: We recommend using `bunx` instead of `npx` for a massive speed improvement!
40 |
41 | ### Local Installation (Optional)
42 |
43 | Since ccusage has such a small bundle size, installation is entirely optional:
44 |
45 | ```bash
46 | npm install -g ccusage
47 | ```
48 |
49 | ## Usage
50 |
51 | ```bash
52 | # Basic usage
53 | ccusage # Show daily report (default)
54 | ccusage daily # Daily token usage and costs
55 | ccusage monthly # Monthly aggregated report
56 | ccusage session # Usage by conversation session
57 | ccusage blocks # 5-hour billing windows
58 | ccusage statusline # Compact status line for hooks (Beta)
59 |
60 | # Live monitoring
61 | ccusage blocks --live # Real-time usage dashboard
62 |
63 | # Filters and options
64 | ccusage daily --since 20250525 --until 20250530
65 | ccusage daily --json # JSON output
66 | ccusage daily --breakdown # Per-model cost breakdown
67 | ccusage daily --timezone UTC # Use UTC timezone
68 | ccusage daily --locale ja-JP # Use Japanese locale for date/time formatting
69 |
70 | # Project analysis
71 | ccusage daily --instances # Group by project/instance
72 | ccusage daily --project myproject # Filter to specific project
73 | ccusage daily --instances --project myproject --json # Combined usage
74 | ```
75 |
76 | ## Features
77 |
78 | - 📊 **Daily Report**: View token usage and costs aggregated by date
79 | - 📅 **Monthly Report**: View token usage and costs aggregated by month
80 | - 💬 **Session Report**: View usage grouped by conversation sessions
81 | - ⏰ **5-Hour Blocks Report**: Track usage within Claude's billing windows with active block monitoring
82 | - 📈 **Live Monitoring**: Real-time dashboard showing active session progress, token burn rate, and cost projections with `blocks --live`
83 | - 🚀 **Statusline Integration**: Compact usage display for Claude Code status bar hooks (Beta)
84 | - 🤖 **Model Tracking**: See which Claude models you're using (Opus, Sonnet, etc.)
85 | - 📊 **Model Breakdown**: View per-model cost breakdown with `--breakdown` flag
86 | - 📅 **Date Filtering**: Filter reports by date range using `--since` and `--until`
87 | - 📁 **Custom Path**: Support for custom Claude data directory locations
88 | - 🎨 **Beautiful Output**: Colorful table-formatted display with automatic responsive layout
89 | - 📱 **Smart Tables**: Automatic compact mode for narrow terminals (< 100 characters) with essential columns
90 | - 📋 **Enhanced Model Display**: Model names shown as bulleted lists for better readability
91 | - 📄 **JSON Output**: Export data in structured JSON format with `--json`
92 | - 💰 **Cost Tracking**: Shows costs in USD for each day/month/session
93 | - 🔄 **Cache Token Support**: Tracks and displays cache creation and cache read tokens separately
94 | - 🌐 **Offline Mode**: Use pre-cached pricing data without network connectivity with `--offline` (Claude models only)
95 | - 🔌 **MCP Integration**: Built-in Model Context Protocol server for integration with other tools
96 | - 🏗️ **Multi-Instance Support**: Group usage by project with `--instances` flag and filter by specific projects
97 | - 🌍 **Timezone Support**: Configure timezone for date grouping with `--timezone` option
98 | - 🌐 **Locale Support**: Customize date/time formatting with `--locale` option (e.g., en-US, ja-JP, de-DE)
99 | - 🚀 **Ultra-Small Bundle**: Unlike other CLI tools, we pay extreme attention to bundle size - incredibly small even without minification!
100 |
101 | ## Documentation
102 |
103 | Full documentation is available at **[ccusage.com](https://ccusage.com/)**
104 |
105 | ## Sponsors
106 |
107 | ### Featured Sponsor
108 |
109 | Check out these [47 Claude Code ProTips from Greg Baugues.](https://www.youtube.com/watch?v=TiNpzxoBPz0&lc=UgyVgQyOhfJJlheVMcB4AaABAg)
110 |
111 | <p align="center">
112 | <a href="https://www.youtube.com/watch?v=TiNpzxoBPz0&lc=UgyVgQyOhfJJlheVMcB4AaABAg">
113 | <img src="https://cdn.jsdelivr.net/gh/ryoppippi/ccusage@main/docs/public/claude_code_protips_thumbnail_v1.png" alt="47 Claude Code ProTips from Greg Baugues" width="600">
114 | </a>
115 | </p>
116 |
117 | <p align="center">
118 | <a href="https://github.com/sponsors/ryoppippi">
119 | <img src="https://cdn.jsdelivr.net/gh/ryoppippi/sponsors@main/sponsors.svg">
120 | </a>
121 | </p>
122 |
123 | ## Claude Code Resources
124 |
125 | [`ClaudeLog`](https://claudelog.com) by [InventorBlack](https://www.reddit.com/user/inventor_black/)
126 | A comprehensive knowledge base with detailed breakdowns of advanced topics, including:
127 |
128 | - Advanced [mechanics](https://claudelog.com/mechanics/you-are-the-main-thread/) and [CLAUDE.md best practices](https://claudelog.com/mechanics/claude-md-supremacy).
129 | - Practical technique guides for [plan mode](https://claudelog.com/mechanics/plan-mode), [ultrathink](https://claudelog.com/faqs/what-is-ultrathink/), and [sub-agents](https://claudelog.com/mechanics/task-agent-tools/).
130 | - Concepts like [agent-first design](https://claudelog.com/mechanics/agent-first-design/), [agent engineering](https://claudelog.com/mechanics/agent-engineering/), and [humanizing agents](https://claudelog.com/mechanics/humanising-agents/).
131 | - [Configuration guides](https://claudelog.com/configuration).
132 |
133 | ## Star History
134 |
135 | <a href="https://www.star-history.com/#ryoppippi/ccusage&Date">
136 | <picture>
137 | <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=ryoppippi/ccusage&type=Date&theme=dark" />
138 | <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=ryoppippi/ccusage&type=Date" />
139 | <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=ryoppippi/ccusage&type=Date" />
140 | </picture>
141 | </a>
142 |
143 | ## License
144 |
145 | [MIT](LICENSE) © [@ryoppippi](https://github.com/ryoppippi)
146 |
--------------------------------------------------------------------------------
/docs/.gitignore:
--------------------------------------------------------------------------------
1 | # VitePress build output
2 | .vitepress/dist/
3 | .vitepress/cache/
4 |
5 | # Generated documentation
6 | api/
7 |
8 | # Dependencies
9 | node_modules/
10 |
11 | # Temporary files
12 | .temp/
13 | .cache/
14 |
15 | # OS files
16 | .DS_Store
17 | Thumbs.db
18 |
19 | public/_redirects
20 |
--------------------------------------------------------------------------------
/docs/.vitepress/config.ts:
--------------------------------------------------------------------------------
1 | import { defineConfig } from 'vitepress';
2 | import * as path from 'node:path';
3 | import { groupIconMdPlugin, groupIconVitePlugin } from 'vitepress-plugin-group-icons';
4 | import llmstxt from 'vitepress-plugin-llms';
5 | import { withMermaid } from 'vitepress-plugin-mermaid';
6 | import typedocSidebar from '../api/typedoc-sidebar.json';
7 | import { cloudflareRedirect } from '@ryoppippi/vite-plugin-cloudflare-redirect'
8 |
9 | export default withMermaid(defineConfig({
10 | title: 'ccusage',
11 | description: 'Usage analysis tool for Claude Code',
12 | base: '/',
13 | cleanUrls: true,
14 | ignoreDeadLinks: true,
15 |
16 | head: [
17 | ['link', { rel: 'icon', href: '/favicon.svg' }],
18 | ['meta', { name: 'theme-color', content: '#646cff' }],
19 | ['meta', { property: 'og:type', content: 'website' }],
20 | ['meta', { property: 'og:locale', content: 'en' }],
21 | ['meta', { property: 'og:title', content: 'ccusage | Claude Code Usage Analysis' }],
22 | ['meta', { property: 'og:site_name', content: 'ccusage' }],
23 | ['meta', { property: 'og:image', content: 'https://cdn.jsdelivr.net/gh/ryoppippi/ccusage@main/docs/public/logo.png' }],
24 | ['meta', { property: 'og:url', content: 'https://github.com/ryoppippi/ccusage' }],
25 | ],
26 |
27 | themeConfig: {
28 | logo: '/logo.svg',
29 |
30 | nav: [
31 | { text: 'Guide', link: '/guide/' },
32 | { text: 'API Reference', link: '/api/' },
33 | {
34 | text: 'Links',
35 | items: [
36 | { text: 'GitHub', link: 'https://github.com/ryoppippi/ccusage' },
37 | { text: 'npm', link: 'https://www.npmjs.com/package/ccusage' },
38 | { text: 'Changelog', link: 'https://github.com/ryoppippi/ccusage/releases' },
39 | { text: 'DeepWiki', link: 'https://deepwiki.com/ryoppippi/ccusage' },
40 | { text: 'Package Stats', link: 'https://tanstack.com/ccusage?npmPackage=ccusage' },
41 | ],
42 | },
43 | ],
44 |
45 | sidebar: {
46 | '/guide/': [
47 | {
48 | text: 'Introduction',
49 | items: [
50 | { text: 'Introduction', link: '/guide/' },
51 | { text: 'Getting Started', link: '/guide/getting-started' },
52 | { text: 'Installation', link: '/guide/installation' },
53 | ],
54 | },
55 | {
56 | text: 'Usage',
57 | items: [
58 | { text: 'Daily Reports', link: '/guide/daily-reports' },
59 | { text: 'Weekly Reports', link: '/guide/weekly-reports' },
60 | { text: 'Monthly Reports', link: '/guide/monthly-reports' },
61 | { text: 'Session Reports', link: '/guide/session-reports' },
62 | { text: 'Blocks Reports', link: '/guide/blocks-reports' },
63 | { text: 'Live Monitoring', link: '/guide/live-monitoring' },
64 | ],
65 | },
66 | {
67 | text: 'Configuration',
68 | items: [
69 | { text: 'Environment Variables', link: '/guide/configuration' },
70 | { text: 'Custom Paths', link: '/guide/custom-paths' },
71 | { text: 'Cost Calculation Modes', link: '/guide/cost-modes' },
72 | ],
73 | },
74 | {
75 | text: 'Integration',
76 | items: [
77 | { text: 'Library Usage', link: '/guide/library-usage' },
78 | { text: 'MCP Server', link: '/guide/mcp-server' },
79 | { text: 'JSON Output', link: '/guide/json-output' },
80 | ],
81 | },
82 | {
83 | text: 'Community',
84 | items: [
85 | { text: 'Related Projects', link: '/guide/related-projects' },
86 | { text: 'Sponsors', link: '/guide/sponsors' },
87 | ],
88 | },
89 | ],
90 | '/api/': [
91 | {
92 | text: 'API Reference',
93 | items: [
94 | { text: 'Overview', link: '/api/' },
95 | ...typedocSidebar,
96 | ],
97 | },
98 | ],
99 | },
100 |
101 | socialLinks: [
102 | { icon: 'github', link: 'https://github.com/ryoppippi/ccusage' },
103 | { icon: 'npm', link: 'https://www.npmjs.com/package/ccusage' },
104 | ],
105 |
106 | footer: {
107 | message: 'Released under the MIT License.',
108 | copyright: 'Copyright © 2024 ryoppippi',
109 | },
110 |
111 | search: {
112 | provider: 'local',
113 | },
114 |
115 | editLink: {
116 | pattern: 'https://github.com/ryoppippi/ccusage/edit/main/docs/:path',
117 | text: 'Edit this page on GitHub',
118 | },
119 |
120 | lastUpdated: {
121 | text: 'Updated at',
122 | formatOptions: {
123 | year: 'numeric',
124 | month: '2-digit',
125 | day: '2-digit',
126 | hour: '2-digit',
127 | minute: '2-digit',
128 | hour12: false,
129 | timeZone: 'UTC',
130 | },
131 | },
132 | },
133 |
134 | vite: {
135 | plugins: [
136 | cloudflareRedirect({
137 | mode: "generate",
138 | entries: [
139 | { from: '/raycast', to: 'https://www.raycast.com/nyatinte/ccusage', status: 302 },
140 | { from: '/gh', to: 'https://github.com/ryoppippi/ccusage', status: 302 },
141 | { from: '/npm', to: 'https://www.npmjs.com/package/ccusage', status: 302 },
142 | { from: '/deepwiki', to: 'https://deepwiki.com/ryoppippi/ccusage', status: 302 },
143 | ]
144 | }),
145 | groupIconVitePlugin(),
146 | ...llmstxt(),
147 | ],
148 | },
149 |
150 | markdown: {
151 | config(md) {
152 | md.use(groupIconMdPlugin);
153 | },
154 | },
155 | mermaid: {
156 | // Optional mermaid configuration
157 | },
158 | }));
159 |
--------------------------------------------------------------------------------
/docs/guide/daily-reports.md:
--------------------------------------------------------------------------------
1 | # Daily Reports
2 |
3 | 
4 |
5 | Daily reports show token usage and costs aggregated by calendar date, giving you a clear view of your Claude Code usage patterns over time.
6 |
7 | ## Basic Usage
8 |
9 | Show all daily usage:
10 |
11 | ```bash
12 | ccusage daily
13 | # or simply:
14 | ccusage
15 | ```
16 |
17 | The daily command is the default, so you can omit it when running ccusage.
18 |
19 | ## Example Output
20 |
21 | 
22 |
23 | ## Understanding the Columns
24 |
25 | ### Basic Columns
26 |
27 | - **Date**: Calendar date in YYYY-MM-DD format
28 | - **Models**: Claude models used that day (shown as bulleted list)
29 | - **Input**: Total input tokens sent to Claude
30 | - **Output**: Total output tokens received from Claude
31 | - **Cost (USD)**: Estimated cost for that day
32 |
33 | ### Cache Columns
34 |
35 | - **Cache Create**: Tokens used to create cache entries
36 | - **Cache Read**: Tokens read from cache (typically cheaper)
37 |
38 | ### Responsive Display
39 |
40 | ccusage automatically adapts to your terminal width:
41 |
42 | - **Wide terminals (≥100 chars)**: Shows all columns
43 | - **Narrow terminals (<100 chars)**: Compact mode with essential columns only
44 |
45 | ## Command Options
46 |
47 | ### Date Filtering
48 |
49 | Filter reports by date range:
50 |
51 | ```bash
52 | # Show usage from December 2024
53 | ccusage daily --since 20241201 --until 20241231
54 |
55 | # Show last week
56 | ccusage daily --since 20241215 --until 20241222
57 |
58 | # Show usage since a specific date
59 | ccusage daily --since 20241201
60 | ```
61 |
62 | ### Sort Order
63 |
64 | Control the order of dates:
65 |
66 | ```bash
67 | # Newest dates first (default)
68 | ccusage daily --order desc
69 |
70 | # Oldest dates first
71 | ccusage daily --order asc
72 | ```
73 |
74 | ### Cost Calculation Modes
75 |
76 | Control how costs are calculated:
77 |
78 | ```bash
79 | # Use pre-calculated costs when available (default)
80 | ccusage daily --mode auto
81 |
82 | # Always calculate costs from tokens
83 | ccusage daily --mode calculate
84 |
85 | # Only show pre-calculated costs
86 | ccusage daily --mode display
87 | ```
88 |
89 | ### Model Breakdown
90 |
91 | See per-model cost breakdown:
92 |
93 | ```bash
94 | ccusage daily --breakdown
95 | ```
96 |
97 | This shows costs split by individual models:
98 |
99 | ```
100 | ┌──────────────┬──────────────────┬────────┬─────────┬────────────┐
101 | │ Date │ Models │ Input │ Output │ Cost (USD) │
102 | ├──────────────┼──────────────────┼────────┼─────────┼────────────┤
103 | │ 2025-06-21 │ opus-4, sonnet-4 │ 277 │ 31,456 │ $17.58 │
104 | ├──────────────┼──────────────────┼────────┼─────────┼────────────┤
105 | │ └─ opus-4 │ │ 100 │ 15,000 │ $10.25 │
106 | ├──────────────┼──────────────────┼────────┼─────────┼────────────┤
107 | │ └─ sonnet-4│ │ 177 │ 16,456 │ $7.33 │
108 | └──────────────┴──────────────────┴────────┴─────────┴────────────┘
109 | ```
110 |
111 | ### JSON Output
112 |
113 | Export data as JSON for further analysis:
114 |
115 | ```bash
116 | ccusage daily --json
117 | ```
118 |
119 | ```json
120 | {
121 | "type": "daily",
122 | "data": [
123 | {
124 | "date": "2025-06-21",
125 | "models": ["claude-opus-4-20250514", "claude-sonnet-4-20250514"],
126 | "inputTokens": 277,
127 | "outputTokens": 31456,
128 | "cacheCreationTokens": 512,
129 | "cacheReadTokens": 1024,
130 | "totalTokens": 33269,
131 | "costUSD": 17.58
132 | }
133 | ],
134 | "summary": {
135 | "totalInputTokens": 277,
136 | "totalOutputTokens": 31456,
137 | "totalCacheCreationTokens": 512,
138 | "totalCacheReadTokens": 1024,
139 | "totalTokens": 33269,
140 | "totalCostUSD": 17.58
141 | }
142 | }
143 | ```
144 |
145 | ### Offline Mode
146 |
147 | Use cached pricing data without network access:
148 |
149 | ```bash
150 | ccusage daily --offline
151 | # or short form:
152 | ccusage daily -O
153 | ```
154 |
155 | ### Project Analysis
156 |
157 | Group usage by project instead of aggregating across all projects:
158 |
159 | ```bash
160 | # Group daily usage by project
161 | ccusage daily --instances
162 | ccusage daily -i
163 | ```
164 |
165 | When using `--instances`, the report shows usage for each project separately:
166 |
167 | ```
168 | ┌──────────────┬────────────────────────────────────────────────────────────────────────────────────────────┐
169 | │ Project: my-project │
170 | ├──────────────┬──────────────────┬────────┬─────────┬────────────┬────────────┬─────────────┬──────────┤
171 | │ Date │ Models │ Input │ Output │ Cache Create│ Cache Read │ Total Tokens│ Cost (USD)│
172 | ├──────────────┼──────────────────┼────────┼─────────┼────────────┼────────────┼─────────────┼──────────┤
173 | │ 2025-06-21 │ • sonnet-4 │ 277 │ 31,456 │ 512│ 1,024 │ 33,269 │ $7.33│
174 | └──────────────┴──────────────────┴────────┴─────────┴────────────┴────────────┴─────────────┴──────────┘
175 |
176 | ┌──────────────┬────────────────────────────────────────────────────────────────────────────────────────────┐
177 | │ Project: other-project │
178 | ├──────────────┬──────────────────┬────────┬─────────┬────────────┬────────────┬─────────────┬──────────┤
179 | │ Date │ Models │ Input │ Output │ Cache Create│ Cache Read │ Total Tokens│ Cost (USD)│
180 | ├──────────────┼──────────────────┼────────┼─────────┼────────────┼────────────┼─────────────┼──────────┤
181 | │ 2025-06-21 │ • opus-4 │ 100 │ 15,000 │ 256│ 512 │ 15,868 │ $10.25│
182 | └──────────────┴──────────────────┴────────┴─────────┴────────────┴────────────┴─────────────┴──────────┘
183 | ```
184 |
185 | Filter to a specific project:
186 |
187 | ```bash
188 | # Show only usage from "my-project"
189 | ccusage daily --project my-project
190 | ccusage daily -p my-project
191 |
192 | # Combine with instances flag
193 | ccusage daily --instances --project my-project
194 | ```
195 |
196 | ## Common Use Cases
197 |
198 | ### Track Monthly Spending
199 |
200 | ```bash
201 | # See December 2024 usage
202 | ccusage daily --since 20241201 --until 20241231
203 | ```
204 |
205 | ### Find Expensive Days
206 |
207 | ```bash
208 | # Sort by cost (highest first)
209 | ccusage daily --order desc
210 | ```
211 |
212 | ### Export for Spreadsheet Analysis
213 |
214 | ```bash
215 | ccusage daily --json > december-usage.json
216 | ```
217 |
218 | ### Compare Model Usage
219 |
220 | ```bash
221 | # See which models you use most
222 | ccusage daily --breakdown
223 | ```
224 |
225 | ### Check Recent Activity
226 |
227 | ```bash
228 | # Last 7 days
229 | ccusage daily --since $(date -d '7 days ago' +%Y%m%d)
230 | ```
231 |
232 | ### Analyze Project Usage
233 |
234 | ```bash
235 | # See usage breakdown by project
236 | ccusage daily --instances
237 |
238 | # Track specific project costs
239 | ccusage daily --project my-important-project --since 20250601
240 |
241 | # Compare project usage with JSON export
242 | ccusage daily --instances --json > project-analysis.json
243 | ```
244 |
245 | ### Team Usage Analysis
246 |
247 | ```bash
248 | # Set custom project names for better reporting
249 | export CCUSAGE_PROJECT_ALIASES="uuid-project=Frontend App,long-name=Backend API"
250 |
251 | # Generate team report with readable project names
252 | ccusage daily --instances --since 20250601
253 | ```
254 |
255 | ## Tips
256 |
257 | 1. **Compact Mode**: If your terminal is narrow, expand it to see all columns
258 | 2. **Date Format**: Use YYYYMMDD format for date filters (e.g., 20241225)
259 | 3. **Regular Monitoring**: Run daily reports regularly to track usage patterns
260 | 4. **JSON Export**: Use `--json` for creating charts or additional analysis
261 |
262 | ## Related Commands
263 |
264 | - [Monthly Reports](/guide/monthly-reports) - Aggregate by month
265 | - [Session Reports](/guide/session-reports) - Per-conversation analysis
266 | - [Blocks Reports](/guide/blocks-reports) - 5-hour billing windows
267 | - [Live Monitoring](/guide/live-monitoring) - Real-time tracking
268 |
--------------------------------------------------------------------------------
/docs/guide/getting-started.md:
--------------------------------------------------------------------------------
1 | # Getting Started
2 |
3 | Welcome to ccusage! This guide will help you get up and running with analyzing your Claude Code usage data.
4 |
5 | ## Prerequisites
6 |
7 | - Claude Code installed and used (generates JSONL files)
8 | - Node.js 20+ or Bun runtime
9 |
10 | ## Quick Start
11 |
12 | The fastest way to try ccusage is to run it directly without installation:
13 |
14 | ::: code-group
15 |
16 | ```bash [npx]
17 | npx ccusage@latest
18 | ```
19 |
20 | ```bash [bunx]
21 | bunx ccusage
22 | ```
23 |
24 | ```bash [pnpm]
25 | pnpm dlx ccusage
26 | ```
27 |
28 | :::
29 |
30 | This will show your daily usage report by default.
31 |
32 | ## Your First Report
33 |
34 | When you run ccusage for the first time, you'll see a table showing your Claude Code usage by date:
35 |
36 | ```
37 | ╭──────────────────────────────────────────╮
38 | │ │
39 | │ Claude Code Token Usage Report - Daily │
40 | │ │
41 | ╰──────────────────────────────────────────╯
42 |
43 | ┌──────────────┬──────────────────┬────────┬─────────┬────────────┐
44 | │ Date │ Models │ Input │ Output │ Cost (USD) │
45 | ├──────────────┼──────────────────┼────────┼─────────┼────────────┤
46 | │ 2025-06-21 │ • sonnet-4 │ 1,234 │ 15,678 │ $12.34 │
47 | │ 2025-06-20 │ • opus-4 │ 890 │ 12,345 │ $18.92 │
48 | └──────────────┴──────────────────┴────────┴─────────┴────────────┘
49 | ```
50 |
51 | ## Understanding the Output
52 |
53 | ### Columns Explained
54 |
55 | - **Date**: The date when Claude Code was used
56 | - **Models**: Which Claude models were used (Sonnet, Opus, etc.)
57 | - **Input**: Number of input tokens sent to Claude
58 | - **Output**: Number of output tokens received from Claude
59 | - **Cost (USD)**: Estimated cost based on model pricing
60 |
61 | ### Cache Tokens
62 |
63 | If you have a wide terminal, you'll also see cache token columns:
64 |
65 | - **Cache Create**: Tokens used to create cache entries
66 | - **Cache Read**: Tokens read from cache (typically cheaper)
67 |
68 | ## Next Steps
69 |
70 | Now that you have your first report, explore these features:
71 |
72 | 1. **[Weekly Reports](/guide/weekly-reports)** - Track usage patterns by week
73 | 2. **[Monthly Reports](/guide/monthly-reports)** - See usage aggregated by month
74 | 3. **[Session Reports](/guide/session-reports)** - Analyze individual conversations
75 | 4. **[Live Monitoring](/guide/live-monitoring)** - Real-time usage tracking
76 | 5. **[Configuration](/guide/configuration)** - Customize ccusage behavior
77 |
78 | ## Common Use Cases
79 |
80 | ### Monitor Daily Usage
81 |
82 | ```bash
83 | ccusage daily --since 20241201 --until 20241231
84 | ```
85 |
86 | ### Find Expensive Sessions
87 |
88 | ```bash
89 | ccusage session --order desc
90 | ```
91 |
92 | ### Export for Analysis
93 |
94 | ```bash
95 | ccusage monthly --json > usage-data.json
96 | ```
97 |
98 | ### Live Session Monitoring
99 |
100 | ```bash
101 | ccusage blocks --live
102 | ```
103 |
104 | ## Colors
105 |
106 | ccusage automatically colors the output based on the terminal's capabilities. If you want to disable colors, you can use the `--no-color` flag. Or you can use the `--color` flag to force colors on.
107 |
108 | ## Troubleshooting
109 |
110 | ### No Data Found
111 |
112 | If ccusage shows no data, check:
113 |
114 | 1. **Claude Code is installed and used** - ccusage reads from Claude Code's data files
115 | 2. **Data directory exists** - Default locations:
116 | - `~/.config/claude/projects/` (new default)
117 | - `~/.claude/projects/` (legacy)
118 |
119 | ### Custom Data Directory
120 |
121 | If your Claude data is in a custom location:
122 |
123 | ```bash
124 | export CLAUDE_CONFIG_DIR="/path/to/your/claude/data"
125 | ccusage daily
126 | ```
127 |
128 | ## Getting Help
129 |
130 | - Use `ccusage --help` for command options
131 | - Visit our [GitHub repository](https://github.com/ryoppippi/ccusage) for issues
132 | - Check the [API Reference](/api/) for programmatic usage
133 |
--------------------------------------------------------------------------------
/docs/guide/index.md:
--------------------------------------------------------------------------------
1 | # Introduction
2 |
3 | 
4 |
5 | **ccusage** (claude-code-usage) is a powerful CLI tool that analyzes your Claude Code usage from local JSONL files to help you understand your token consumption patterns and estimated costs.
6 |
7 | ## The Problem
8 |
9 | Claude Code's Max plan offers unlimited usage, which is fantastic! But many users are curious:
10 |
11 | - How much am I actually using Claude Code?
12 | - Which conversations are the most expensive?
13 | - What would I be paying on a pay-per-use plan?
14 | - Am I getting good value from my subscription?
15 |
16 | ## The Solution
17 |
18 | ccusage analyzes the local JSONL files that Claude Code automatically generates and provides:
19 |
20 | - **Detailed Usage Reports** - Daily, monthly, and session-based breakdowns
21 | - **Cost Analysis** - Estimated costs based on token usage and model pricing
22 | - **Live Monitoring** - Real-time tracking of active sessions
23 | - **Multiple Formats** - Beautiful tables or JSON for further analysis
24 |
25 | ## How It Works
26 |
27 | ```mermaid
28 | graph LR
29 | A[Claude Code] --> B[Local JSONL Files]
30 | B --> C[ccusage]
31 | C --> D[Usage Reports]
32 | C --> E[Cost Analysis]
33 | C --> F[Live Monitoring]
34 | ```
35 |
36 | 1. **Claude Code generates JSONL files** containing usage data
37 | 2. **ccusage reads these files** from your local machine
38 | 3. **Analyzes and aggregates** the data by date, session, or time blocks
39 | 4. **Calculates estimated costs** using model pricing information
40 | 5. **Presents results** in beautiful tables or JSON format
41 |
42 | ## Key Features
43 |
44 | ### 🚀 Ultra-Small Bundle Size
45 |
46 | Unlike other CLI tools, we pay extreme attention to bundle size. ccusage achieves an incredibly small footprint even without minification, which means you can run it directly without installation using `bunx ccusage` for instant access.
47 |
48 | ### 📊 Multiple Report Types
49 |
50 | - **Daily Reports** - Usage aggregated by calendar date
51 | - **Weekly Reports** - Usage aggregated by week with configurable start day
52 | - **Monthly Reports** - Monthly summaries with trends
53 | - **Session Reports** - Per-conversation analysis
54 | - **Blocks Reports** - 5-hour billing window tracking
55 |
56 | ### 💰 Cost Analysis
57 |
58 | - Estimated costs based on token counts and model pricing
59 | - Support for different cost calculation modes
60 | - Model-specific pricing (Opus vs Sonnet vs other models)
61 | - Cache token cost calculation
62 |
63 | ### 📈 Live Monitoring
64 |
65 | - Real-time dashboard for active sessions
66 | - Progress bars and burn rate calculations
67 | - Token limit warnings and projections
68 | - Automatic refresh with configurable intervals
69 |
70 | ### 🔧 Flexible Configuration
71 |
72 | - Multiple Claude data directory support
73 | - Environment variable configuration
74 | - Custom date filtering and sorting
75 | - Offline mode with cached pricing data
76 |
77 | ## Data Sources
78 |
79 | ccusage reads from Claude Code's local data directories:
80 |
81 | - **New location**: `~/.config/claude/projects/` (Claude Code v1.0.30+)
82 | - **Legacy location**: `~/.claude/projects/` (pre-v1.0.30)
83 |
84 | The tool automatically detects and aggregates data from both locations for compatibility.
85 |
86 | ## Privacy & Security
87 |
88 | - **100% Local** - All analysis happens on your machine
89 | - **No Data Transmission** - Your usage data never leaves your computer
90 | - **Read-Only** - ccusage only reads files, never modifies them
91 | - **Open Source** - Full transparency in how your data is processed
92 |
93 | ## Limitations
94 |
95 | ::: warning Important Limitations
96 |
97 | - **Local Files Only** - Only analyzes data from your current machine
98 | - **Language Model Tokens** - API calls for tools like Web Search are not included
99 | - **Estimate Accuracy** - Costs are estimates and may not reflect actual billing
100 | :::
101 |
102 | ## Acknowledgments
103 |
104 | Thanks to [@milliondev](https://note.com/milliondev) for the [original concept and approach](https://note.com/milliondev/n/n1d018da2d769) to Claude Code usage analysis.
105 |
106 | ## Getting Started
107 |
108 | Ready to analyze your Claude Code usage? Check out our [Getting Started Guide](/guide/getting-started) to begin exploring your data!
109 |
--------------------------------------------------------------------------------
/docs/guide/installation.md:
--------------------------------------------------------------------------------
1 | # Installation
2 |
3 | ccusage can be installed and used in several ways depending on your preferences and use case.
4 |
5 | ## Why No Installation Needed?
6 |
7 | Thanks to ccusage's incredibly small bundle size, you don't need to install it globally. Unlike other CLI tools, we pay extreme attention to bundle size optimization, achieving an impressively small footprint even without minification. This means:
8 |
9 | - ✅ Near-instant startup times
10 | - ✅ Minimal download overhead
11 | - ✅ Always use the latest version
12 | - ✅ No global pollution of your system
13 |
14 | ## Quick Start (Recommended)
15 |
16 | The fastest way to use ccusage is to run it directly:
17 |
18 | ::: code-group
19 |
20 | ```bash [bunx (Recommended)]
21 | bunx ccusage
22 | ```
23 |
24 | ```bash [npx]
25 | npx ccusage@latest
26 | ```
27 |
28 | ```bash [pnpm]
29 | pnpm dlx ccusage
30 | ```
31 |
32 | ```bash [deno]
33 | deno run -E -R=$HOME/.claude/projects/ -S=homedir -N='raw.githubusercontent.com:443' npm:ccusage@latest
34 | ```
35 |
36 | :::
37 |
38 | ::: tip Speed Recommendation
39 | We strongly recommend using `bunx` instead of `npx` due to the massive speed difference. Bunx caches packages more efficiently, resulting in near-instant startup times after the first run.
40 | :::
41 |
42 | ::: info Deno Security
43 | Consider using `deno run` if you want additional security controls. Deno allows you to specify exact permissions, making it safer to run tools you haven't audited.
44 | :::
45 |
46 | ### Performance Comparison
47 |
48 | Here's why runtime choice matters:
49 |
50 | | Runtime | First Run | Subsequent Runs | Notes |
51 | |---------|-----------|-----------------|-------|
52 | | bunx | Fast | **Instant** | Best overall choice |
53 | | npx | Slow | Moderate | Widely available |
54 | | pnpm dlx | Fast | Fast | Good alternative |
55 | | deno | Moderate | Fast | Best for security |
56 |
57 | ## Global Installation (Optional)
58 |
59 | While not necessary due to our small bundle size, you can still install ccusage globally if you prefer:
60 |
61 | ::: code-group
62 |
63 | ```bash [npm]
64 | npm install -g ccusage
65 | ```
66 |
67 | ```bash [bun]
68 | bun install -g ccusage
69 | ```
70 |
71 | ```bash [yarn]
72 | yarn global add ccusage
73 | ```
74 |
75 | ```bash [pnpm]
76 | pnpm add -g ccusage
77 | ```
78 |
79 | :::
80 |
81 | After global installation, run commands directly:
82 |
83 | ```bash
84 | ccusage daily
85 | ccusage monthly --breakdown
86 | ccusage blocks --live
87 | ```
88 |
89 | ## Development Installation
90 |
91 | For development or contributing to ccusage:
92 |
93 | ```bash
94 | # Clone the repository
95 | git clone https://github.com/ryoppippi/ccusage.git
96 | cd ccusage
97 |
98 | # Install dependencies
99 | bun install
100 |
101 | # Run directly from source
102 | bun run start daily
103 | bun run start monthly --json
104 | ```
105 |
106 | ### Development Scripts
107 |
108 | ```bash
109 | # Run tests
110 | bun run test
111 |
112 | # Type checking
113 | bun typecheck
114 |
115 | # Build distribution
116 | bun run build
117 |
118 | # Lint and format
119 | bun run format
120 | ```
121 |
122 | ## Runtime Requirements
123 |
124 | ### Node.js
125 |
126 | - **Minimum**: Node.js 20.x
127 | - **Recommended**: Node.js 20.x or later
128 | - **LTS versions** are fully supported
129 |
130 | ### Bun (Alternative)
131 |
132 | - **Minimum**: Bun 1.2+
133 | - **Recommended**: Latest stable release
134 | - Often faster than Node.js for ccusage
135 |
136 | ### Deno
137 |
138 | Deno 2.0+ is fully supported with proper permissions:
139 |
140 | ```bash
141 | deno run \
142 | -E \
143 | -R=$HOME/.claude/projects/ \
144 | -S=homedir \
145 | -N='raw.githubusercontent.com:443' \
146 | npm:ccusage@latest
147 | ```
148 |
149 | Also you can use `offline` mode to run ccusage without network access:
150 |
151 | ```bash
152 | deno run \
153 | -E \
154 | -R=$HOME/.claude/projects/ \
155 | -S=homedir \
156 | npm:ccusage@latest --offline
157 | ```
158 |
159 | ## Verification
160 |
161 | After installation, verify ccusage is working:
162 |
163 | ```bash
164 | # Check version
165 | ccusage --version
166 |
167 | # Run help command
168 | ccusage --help
169 |
170 | # Test with daily report
171 | ccusage daily
172 | ```
173 |
174 | ## Updating
175 |
176 | ### Direct Execution (npx/bunx)
177 |
178 | Always gets the latest version automatically.
179 |
180 | ### Global Installation
181 |
182 | ```bash
183 | # Update with npm
184 | npm update -g ccusage
185 |
186 | # Update with bun
187 | bun update -g ccusage
188 | ```
189 |
190 | ### Check Current Version
191 |
192 | ```bash
193 | ccusage --version
194 | ```
195 |
196 | ## Uninstalling
197 |
198 | ### Global Installation
199 |
200 | ::: code-group
201 |
202 | ```bash [npm]
203 | npm uninstall -g ccusage
204 | ```
205 |
206 | ```bash [bun]
207 | bun remove -g ccusage
208 | ```
209 |
210 | ```bash [yarn]
211 | yarn global remove ccusage
212 | ```
213 |
214 | ```bash [pnpm]
215 | pnpm remove -g ccusage
216 | ```
217 |
218 | :::
219 |
220 | ### Development Installation
221 |
222 | ```bash
223 | # Remove cloned repository
224 | rm -rf ccusage/
225 | ```
226 |
227 | ## Troubleshooting Installation
228 |
229 | ### Permission Errors
230 |
231 | If you get permission errors during global installation:
232 |
233 | ::: code-group
234 |
235 | ```bash [npm]
236 | # Use npx instead of global install
237 | npx ccusage@latest
238 |
239 | # Or configure npm to use a different directory
240 | npm config set prefix ~/.npm-global
241 | export PATH=~/.npm-global/bin:$PATH
242 | ```
243 |
244 | ```bash [Node Version Managers]
245 | # Use nvm (recommended)
246 | nvm install node
247 | npm install -g ccusage
248 |
249 | # Or use fnm
250 | fnm install node
251 | npm install -g ccusage
252 | ```
253 |
254 | :::
255 |
256 | ### Network Issues
257 |
258 | If installation fails due to network issues:
259 |
260 | ```bash
261 | # Try with different registry
262 | npm install -g ccusage --registry https://registry.npmjs.org
263 |
264 | # Or use bunx for offline-capable runs
265 | bunx ccusage
266 | ```
267 |
268 | ### Version Conflicts
269 |
270 | If you have multiple versions installed:
271 |
272 | ```bash
273 | # Check which version is being used
274 | which ccusage
275 | ccusage --version
276 |
277 | # Uninstall and reinstall
278 | npm uninstall -g ccusage
279 | npm install -g ccusage@latest
280 | ```
281 |
282 | ## Next Steps
283 |
284 | After installation, check out:
285 |
286 | - [Getting Started Guide](/guide/getting-started) - Your first usage report
287 | - [Configuration](/guide/configuration) - Customize ccusage behavior
288 | - [Daily Reports](/guide/daily-reports) - Understand daily usage patterns
289 |
--------------------------------------------------------------------------------
/docs/guide/library-usage.md:
--------------------------------------------------------------------------------
1 | # Library Usage
2 |
3 | While **ccusage** is primarily known as a CLI tool, it can also be used as a library in your JavaScript/TypeScript projects. This allows you to integrate Claude Code usage analysis directly into your applications.
4 |
5 | ## Installation
6 |
7 | ```bash
8 | npm install ccusage
9 | # or
10 | yarn add ccusage
11 | # or
12 | pnpm add ccusage
13 | # or
14 | bun add ccusage
15 | ```
16 |
17 | ## Basic Usage
18 |
19 | The library provides functions to load and analyze Claude Code usage data:
20 |
21 | ```typescript
22 | import { loadDailyUsageData, loadMonthlyUsageData, loadSessionData } from 'ccusage/data-loader';
23 |
24 | // Load daily usage data
25 | const dailyData = await loadDailyUsageData();
26 | console.log(dailyData);
27 |
28 | // Load monthly usage data
29 | const monthlyData = await loadMonthlyUsageData();
30 | console.log(monthlyData);
31 |
32 | // Load session data
33 | const sessionData = await loadSessionData();
34 | console.log(sessionData);
35 | ```
36 |
37 | ## Cost Calculation
38 |
39 | Use the cost calculation utilities to work with token costs:
40 |
41 | ```typescript
42 | import { calculateTotals, getTotalTokens } from 'ccusage/calculate-cost';
43 |
44 | // Assume 'usageEntries' is an array of usage data objects
45 | const totals = calculateTotals(usageEntries);
46 |
47 | // Get total tokens from the same entries
48 | const totalTokens = getTotalTokens(usageEntries);
49 | ```
50 |
51 | ## Advanced Configuration
52 |
53 | You can customize the data loading behavior:
54 |
55 | ```typescript
56 | import { loadDailyUsageData } from 'ccusage/data-loader';
57 |
58 | // Load data with custom options
59 | const data = await loadDailyUsageData({
60 | mode: 'calculate', // Force cost calculation
61 | claudePaths: ['/custom/path/to/claude'], // Custom Claude data paths
62 | });
63 | ```
64 |
65 | ## TypeScript Support
66 |
67 | The library is fully typed with TypeScript definitions:
68 |
69 | ```typescript
70 | import type { DailyUsage, ModelBreakdown, MonthlyUsage, SessionUsage, UsageData } from 'ccusage/data-loader';
71 |
72 | // Use the types in your application
73 | function processUsageData(data: UsageData[]): void {
74 | // Your processing logic here
75 | }
76 | ```
77 |
78 | ## MCP Server Integration
79 |
80 | You can also create your own MCP server using the library:
81 |
82 | ```typescript
83 | import { createMcpServer } from 'ccusage/mcp';
84 |
85 | // Create an MCP server instance
86 | const server = createMcpServer();
87 |
88 | // Start the server
89 | server.start();
90 | ```
91 |
92 | ## API Reference
93 |
94 | For detailed information about all available functions, types, and options, see the [API Reference](/api/) section.
95 |
96 | ## Examples
97 |
98 | Here are some common use cases:
99 |
100 | ### Building a Web Dashboard
101 |
102 | ```typescript
103 | import { loadDailyUsageData } from 'ccusage/data-loader';
104 |
105 | export async function GET() {
106 | const data = await loadDailyUsageData();
107 | return Response.json(data);
108 | }
109 | ```
110 |
111 | ### Creating Custom Reports
112 |
113 | ```typescript
114 | import { calculateTotals, loadSessionData } from 'ccusage';
115 |
116 | async function generateCustomReport() {
117 | const sessions = await loadSessionData();
118 |
119 | const report = sessions.map(session => ({
120 | project: session.project,
121 | session: session.session,
122 | totalCost: calculateTotals(session.usage).costUSD,
123 | }));
124 |
125 | return report;
126 | }
127 | ```
128 |
129 | ### Monitoring Usage Programmatically
130 |
131 | ```typescript
132 | import { loadDailyUsageData } from 'ccusage/data-loader';
133 |
134 | async function checkUsageAlert() {
135 | const dailyData = await loadDailyUsageData();
136 | const today = dailyData[0]; // Most recent day
137 |
138 | if (today.totalCostUSD > 10) {
139 | console.warn(`High usage detected: ${today.totalCostUSD}`);
140 | }
141 | }
142 | ```
143 |
144 | ## Next Steps
145 |
146 | - Explore the [API Reference](/api/) for complete documentation
147 | - Check out the [MCP Server guide](/guide/mcp-server) for integration examples
148 | - See [JSON Output](/guide/json-output) for data format details
149 |
--------------------------------------------------------------------------------
/docs/guide/live-monitoring.md:
--------------------------------------------------------------------------------
1 | # Live Monitoring
2 |
3 | 
4 |
5 | Live monitoring provides a real-time dashboard that updates as you use Claude Code, showing progress bars, burn rates, and cost projections for your active session.
6 |
7 | ## Quick Start
8 |
9 | ```bash
10 | ccusage blocks --live
11 | ```
12 |
13 | This starts live monitoring with automatic token limit detection based on your usage history.
14 |
15 | ## Features
16 |
17 | ### Real-time Updates
18 |
19 | The dashboard refreshes every second, showing:
20 |
21 | - **Current session progress** with visual progress bar
22 | - **Token burn rate** (tokens per minute)
23 | - **Time remaining** in current 5-hour block
24 | - **Cost projections** based on current usage patterns
25 | - **Quota warnings** with color-coded alerts
26 |
27 | ### Visual Example
28 |
29 | 
30 |
31 | ## Command Options
32 |
33 | ### Token Limits
34 |
35 | Set custom token limits for quota warnings:
36 |
37 | ```bash
38 | # Use specific token limit
39 | ccusage blocks --live -t 500000
40 |
41 | # Use highest previous session as limit (default)
42 | ccusage blocks --live -t max
43 |
44 | # Explicitly set max (same as default)
45 | ccusage blocks --live -t max
46 | ```
47 |
48 | ### Refresh Interval
49 |
50 | Control update frequency:
51 |
52 | ```bash
53 | # Update every 5 seconds
54 | ccusage blocks --live --refresh-interval 5
55 |
56 | # Update every 10 seconds (lighter on CPU)
57 | ccusage blocks --live --refresh-interval 10
58 |
59 | # Fast updates (every 0.5 seconds)
60 | ccusage blocks --live --refresh-interval 0.5
61 | ```
62 |
63 | ::: tip Refresh Rate
64 |
65 | - **1 second (default)**: Good balance of responsiveness and performance
66 | - **0.5-2 seconds**: For active monitoring during heavy usage
67 | - **5-10 seconds**: For casual monitoring or slower systems
68 | :::
69 |
70 | ### Combined Options
71 |
72 | ```bash
73 | # Custom limit with slower refresh
74 | ccusage blocks --live -t 750000 --refresh-interval 3
75 |
76 | # Maximum responsiveness
77 | ccusage blocks --live -t max --refresh-interval 0.5
78 | ```
79 |
80 | ## Understanding the Display
81 |
82 | ### Progress Bar
83 |
84 | The progress bar shows token usage within the current 5-hour block:
85 |
86 | - **Green**: Normal usage (0-60% of limit)
87 | - **Yellow**: Moderate usage (60-80% of limit)
88 | - **Red**: High usage (80-100% of limit)
89 |
90 | ### Metrics Explained
91 |
92 | #### Current Session
93 |
94 | - **Tokens used** in the current 5-hour block
95 | - **Percentage** of token limit consumed
96 |
97 | #### Time Remaining
98 |
99 | - **Hours and minutes** left in current block
100 | - Resets every 5 hours from first message
101 |
102 | #### Burn Rate
103 |
104 | - **Tokens per minute** based on recent activity
105 | - Calculated from last 10 minutes of usage
106 | - Used for projections
107 |
108 | #### Cost Tracking
109 |
110 | - **Current Cost**: Actual cost so far in this block
111 | - **Projected Cost**: Estimated total cost if current rate continues
112 |
113 | ### Warning System
114 |
115 | ccusage shows color-coded warnings based on usage:
116 |
117 | - 🟢 **< 60%**: Normal usage
118 | - 🟡 **60-80%**: Moderate usage warning
119 | - 🔴 **80-100%**: High usage warning
120 | - ⚠️ **> 100%**: Over limit warning
121 |
122 | ## Use Cases
123 |
124 | ### Active Development
125 |
126 | Monitor usage during intensive coding sessions:
127 |
128 | ```bash
129 | # Monitor with reasonable limit
130 | ccusage blocks --live -t 500000
131 | ```
132 |
133 | Perfect for:
134 |
135 | - Large refactoring projects
136 | - Documentation generation
137 | - Code review sessions
138 |
139 | ### Team Collaboration
140 |
141 | Track usage during pair programming:
142 |
143 | ```bash
144 | # Higher limit for team sessions
145 | ccusage blocks --live -t 1000000
146 | ```
147 |
148 | ### Budget Management
149 |
150 | Set strict limits for cost control:
151 |
152 | ```bash
153 | # Conservative monitoring
154 | ccusage blocks --live -t 200000
155 | ```
156 |
157 | ### Learning Sessions
158 |
159 | Monitor while learning new technologies:
160 |
161 | ```bash
162 | # Moderate limit with frequent updates
163 | ccusage blocks --live -t 300000 --refresh-interval 2
164 | ```
165 |
166 | ## Tips for Effective Monitoring
167 |
168 | ### 1. Set Appropriate Limits
169 |
170 | Choose token limits based on your needs:
171 |
172 | - **Conservative (100k-300k)**: Light usage, cost-conscious
173 | - **Moderate (300k-700k)**: Regular development work
174 | - **High (700k-1M+)**: Intensive projects, team sessions
175 |
176 | ### 2. Monitor Burn Rate
177 |
178 | Watch for sudden increases in burn rate:
179 |
180 | - **Steady rate**: Normal conversation flow
181 | - **Spikes**: Complex queries or large code generation
182 | - **High sustained rate**: Consider taking breaks
183 |
184 | ### 3. Use Projections Wisely
185 |
186 | Projections help estimate session costs:
187 |
188 | - **Early session**: Projections may be inaccurate
189 | - **Mid-session**: More reliable estimates
190 | - **Late session**: Highly accurate projections
191 |
192 | ### 4. Plan Around Blocks
193 |
194 | Remember that 5-hour blocks reset:
195 |
196 | - **Block boundary**: Good time for breaks
197 | - **New block**: Fresh token allowance
198 | - **Block overlap**: Previous usage doesn't carry over
199 |
200 | ## Keyboard Controls
201 |
202 | While live monitoring is active:
203 |
204 | - **Ctrl+C**: Exit monitoring gracefully
205 | - **Terminal resize**: Automatically adjusts display
206 |
207 | ## Performance Notes
208 |
209 | ### CPU Usage
210 |
211 | Live monitoring uses minimal resources:
212 |
213 | - **1-second refresh**: ~0.1% CPU usage
214 | - **0.5-second refresh**: ~0.2% CPU usage
215 | - **File watching**: Efficient incremental updates
216 |
217 | ### Network Usage
218 |
219 | - **Offline mode**: Zero network usage
220 | - **Online mode**: Minimal API calls for pricing
221 | - **Local analysis**: All processing happens locally
222 |
223 | ## Troubleshooting
224 |
225 | ### No Active Session
226 |
227 | If no active session is detected:
228 |
229 | ```
230 | No active session found. Start using Claude Code to begin monitoring.
231 | ```
232 |
233 | **Solutions**:
234 |
235 | 1. Send a message in Claude Code
236 | 2. Wait a few seconds for data to be written
237 | 3. Check that Claude Code is running
238 |
239 | ### Incorrect Token Limits
240 |
241 | If automatic limit detection fails:
242 |
243 | ```bash
244 | # Manually set a reasonable limit
245 | ccusage blocks --live -t 500000
246 | ```
247 |
248 | ### Performance Issues
249 |
250 | If monitoring feels slow:
251 |
252 | ```bash
253 | # Reduce refresh frequency
254 | ccusage blocks --live --refresh-interval 5
255 | ```
256 |
257 | ## Related Commands
258 |
259 | - [Blocks Reports](/guide/blocks-reports) - Static 5-hour block analysis
260 | - [Session Reports](/guide/session-reports) - Historical session data
261 | - [Daily Reports](/guide/daily-reports) - Day-by-day usage patterns
262 |
263 | ## Advanced Usage
264 |
265 | Combine live monitoring with other tools:
266 |
267 | ```bash
268 | # Monitor in background, export data periodically
269 | ccusage blocks --live &
270 | ccusage session --json > session-backup.json
271 | ```
272 |
--------------------------------------------------------------------------------
/docs/guide/mcp-server.md:
--------------------------------------------------------------------------------
1 | # MCP Server
2 |
3 | ccusage includes a built-in Model Context Protocol (MCP) server that exposes usage data through standardized tools. This allows integration with other applications that support MCP.
4 |
5 | ## Starting the MCP Server
6 |
7 | ### stdio transport (default)
8 |
9 | ```bash
10 | ccusage mcp
11 | # or explicitly (--type stdio is optional):
12 | ccusage mcp --type stdio
13 | ```
14 |
15 | The stdio transport is ideal for local integration where the client directly spawns the process.
16 |
17 | ### HTTP Stream Transport
18 |
19 | ```bash
20 | ccusage mcp --type http --port 8080
21 | ```
22 |
23 | The HTTP stream transport is best for remote access when you need to call the server from another machine or network location.
24 |
25 | ### Cost Calculation Mode
26 |
27 | You can control how costs are calculated:
28 |
29 | ```bash
30 | # Use pre-calculated costs when available, calculate from tokens otherwise (default)
31 | ccusage mcp --mode auto
32 |
33 | # Always calculate costs from tokens using model pricing
34 | ccusage mcp --mode calculate
35 |
36 | # Always use pre-calculated costUSD values only
37 | ccusage mcp --mode display
38 | ```
39 |
40 | ## Available MCP Tools
41 |
42 | The MCP server provides four main tools for analyzing Claude Code usage:
43 |
44 | ### daily
45 |
46 | Returns daily usage reports with aggregated token usage and costs by date.
47 |
48 | **Parameters:**
49 |
50 | - `since` (optional): Filter from date (YYYYMMDD format)
51 | - `until` (optional): Filter until date (YYYYMMDD format)
52 | - `mode` (optional): Cost calculation mode (`auto`, `calculate`, or `display`)
53 |
54 | ### monthly
55 |
56 | Returns monthly usage reports with aggregated token usage and costs by month.
57 |
58 | **Parameters:**
59 |
60 | - `since` (optional): Filter from date (YYYYMMDD format)
61 | - `until` (optional): Filter until date (YYYYMMDD format)
62 | - `mode` (optional): Cost calculation mode (`auto`, `calculate`, or `display`)
63 |
64 | ### session
65 |
66 | Returns session-based usage reports grouped by conversation sessions.
67 |
68 | **Parameters:**
69 |
70 | - `since` (optional): Filter from date (YYYYMMDD format)
71 | - `until` (optional): Filter until date (YYYYMMDD format)
72 | - `mode` (optional): Cost calculation mode (`auto`, `calculate`, or `display`)
73 |
74 | ### blocks
75 |
76 | Returns 5-hour billing blocks usage reports showing usage within Claude's billing windows.
77 |
78 | **Parameters:**
79 |
80 | - `since` (optional): Filter from date (YYYYMMDD format)
81 | - `until` (optional): Filter until date (YYYYMMDD format)
82 | - `mode` (optional): Cost calculation mode (`auto`, `calculate`, or `display`)
83 |
84 | ## Testing the MCP Server
85 |
86 | ### Interactive Testing with MCP Inspector
87 |
88 | You can test the MCP server using the MCP Inspector for interactive debugging:
89 |
90 | ```bash
91 | # Test with web UI (if you have the dev environment set up)
92 | bun run mcp
93 |
94 | # Test with the official MCP Inspector
95 | bunx @modelcontextprotocol/inspector bunx ccusage mcp
96 | ```
97 |
98 | The MCP Inspector provides a web-based interface to:
99 |
100 | - Test individual MCP tools (daily, monthly, session, blocks)
101 | - Inspect tool schemas and parameters
102 | - Debug server responses
103 | - Export server configurations
104 |
105 | ### Manual Testing
106 |
107 | You can also manually test the server by running it and sending JSON-RPC messages:
108 |
109 | ```bash
110 | # Start the server
111 | ccusage mcp
112 |
113 | # The server will wait for JSON-RPC messages on stdin
114 | # Example: List available tools
115 | {"jsonrpc": "2.0", "id": 1, "method": "tools/list"}
116 | ```
117 |
118 | ## Integration Examples
119 |
120 | ### With Claude Desktop
121 |
122 | 
123 |
124 | To use ccusage MCP with Claude Desktop, add this to your Claude Desktop configuration file:
125 |
126 | **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
127 | **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
128 |
129 | #### Using npx (Recommended)
130 |
131 | ```json
132 | {
133 | "mcpServers": {
134 | "ccusage": {
135 | "command": "npx",
136 | "args": ["ccusage@latest", "mcp"],
137 | "env": {}
138 | }
139 | }
140 | }
141 | ```
142 |
143 | #### Using Global Installation
144 |
145 | If you have ccusage installed globally:
146 |
147 | ```json
148 | {
149 | "mcpServers": {
150 | "ccusage": {
151 | "command": "ccusage",
152 | "args": ["mcp"],
153 | "env": {}
154 | }
155 | }
156 | }
157 | ```
158 |
159 | #### Custom Configuration
160 |
161 | You can specify custom Claude data directories and cost calculation modes:
162 |
163 | ```json
164 | {
165 | "mcpServers": {
166 | "ccusage": {
167 | "command": "npx",
168 | "args": ["ccusage@latest", "mcp", "--mode", "calculate"],
169 | "env": {
170 | "CLAUDE_CONFIG_DIR": "/path/to/your/claude/data"
171 | }
172 | }
173 | }
174 | }
175 | ```
176 |
177 | After adding this configuration, restart Claude Desktop. You'll then be able to use the ccusage tools within Claude to analyze your usage data.
178 |
179 | #### Available Commands in Claude Desktop
180 |
181 | Once configured, you can ask Claude to:
182 |
183 | - "Show me my Claude Code usage for today"
184 | - "Generate a monthly usage report"
185 | - "Which sessions used the most tokens?"
186 | - "Show me my current billing block usage"
187 | - "Analyze my 5-hour block patterns"
188 |
189 | #### Troubleshooting Claude Desktop Integration
190 |
191 | **Configuration Not Working:**
192 |
193 | 1. Verify the config file is in the correct location for your OS
194 | 2. Check JSON syntax with a validator
195 | 3. Restart Claude Desktop completely
196 | 4. Ensure ccusage is installed and accessible
197 |
198 | **Common Issues:**
199 |
200 | - "Command not found": Install ccusage globally or use the npx configuration
201 | - "No usage data found": Verify your Claude Code data directory exists
202 | - Performance issues: Consider using `--mode display` or `--offline` flag
203 |
204 | ### With Other MCP Clients
205 |
206 | Any application that supports the Model Context Protocol can integrate with ccusage's MCP server. The server follows the MCP specification for tool discovery and execution.
207 |
208 | ## Environment Variables
209 |
210 | The MCP server respects the same environment variables as the CLI:
211 |
212 | - `CLAUDE_CONFIG_DIR`: Specify custom Claude data directory paths
213 | ```bash
214 | export CLAUDE_CONFIG_DIR="/path/to/claude"
215 | ccusage mcp
216 | ```
217 |
218 | ## Error Handling
219 |
220 | The MCP server handles errors gracefully:
221 |
222 | - Invalid date formats in parameters return descriptive error messages
223 | - Missing Claude data directories are handled with appropriate warnings
224 | - Malformed JSONL files are skipped during data loading
225 | - Network errors (when fetching pricing data) fall back to cached data when using `auto` mode
226 |
--------------------------------------------------------------------------------
/docs/guide/monthly-reports.md:
--------------------------------------------------------------------------------
1 | # Monthly Reports
2 |
3 | Monthly reports aggregate your Claude Code usage by calendar month, providing a high-level view of your usage patterns and costs over longer time periods.
4 |
5 | ## Basic Usage
6 |
7 | ```bash
8 | ccusage monthly
9 | ```
10 |
11 | ## Example Output
12 |
13 | ```
14 | ╭─────────────────────────────────────────────╮
15 | │ │
16 | │ Claude Code Token Usage Report - Monthly │
17 | │ │
18 | ╰─────────────────────────────────────────────╯
19 |
20 | ┌─────────┬──────────────────┬─────────┬──────────┬──────────────┬────────────┬──────────────┬────────────┐
21 | │ Month │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │
22 | ├─────────┼──────────────────┼─────────┼──────────┼──────────────┼────────────┼──────────────┼────────────┤
23 | │ 2025-06 │ • opus-4 │ 45,231 │ 892,456 │ 2,048 │ 4,096 │ 943,831 │ $1,247.92│
24 | │ │ • sonnet-4 │ │ │ │ │ │ │
25 | │ 2025-05 │ • sonnet-4 │ 38,917 │ 756,234 │ 1,536 │ 3,072 │ 799,759 │ $892.15│
26 | │ 2025-04 │ • opus-4 │ 22,458 │ 534,789 │ 1,024 │ 2,048 │ 560,319 │ $678.43│
27 | ├─────────┼──────────────────┼─────────┼──────────┼──────────────┼────────────┼──────────────┼────────────┤
28 | │ Total │ │ 106,606 │2,183,479 │ 4,608 │ 9,216 │ 2,303,909 │ $2,818.50│
29 | └─────────┴──────────────────┴─────────┴──────────┴──────────────┴────────────┴──────────────┴────────────┘
30 | ```
31 |
32 | ## Understanding Monthly Data
33 |
34 | ### Month Format
35 |
36 | Months are displayed in YYYY-MM format:
37 |
38 | - `2025-06` = June 2025
39 | - `2025-05` = May 2025
40 |
41 | ### Aggregation Logic
42 |
43 | All usage within a calendar month is aggregated:
44 |
45 | - Input/output tokens summed across all days
46 | - Costs calculated from total token usage
47 | - Models listed if used at any point in the month
48 |
49 | ## Command Options
50 |
51 | ### Date Filtering
52 |
53 | Filter by month range:
54 |
55 | ```bash
56 | # Show specific months
57 | ccusage monthly --since 20250101 --until 20250630
58 |
59 | # Show usage from 2024
60 | ccusage monthly --since 20240101 --until 20241231
61 |
62 | # Show last 6 months
63 | ccusage monthly --since $(date -d '6 months ago' +%Y%m%d)
64 | ```
65 |
66 | ::: tip Date Filtering
67 | Even though you specify full dates (YYYYMMDD), monthly reports group by month. The filters determine which months to include.
68 | :::
69 |
70 | ### Sort Order
71 |
72 | ```bash
73 | # Newest months first (default)
74 | ccusage monthly --order desc
75 |
76 | # Oldest months first
77 | ccusage monthly --order asc
78 | ```
79 |
80 | ### Cost Calculation Modes
81 |
82 | ```bash
83 | # Use pre-calculated costs when available (default)
84 | ccusage monthly --mode auto
85 |
86 | # Always calculate costs from tokens
87 | ccusage monthly --mode calculate
88 |
89 | # Only show pre-calculated costs
90 | ccusage monthly --mode display
91 | ```
92 |
93 | ### Model Breakdown
94 |
95 | See costs broken down by model:
96 |
97 | ```bash
98 | ccusage monthly --breakdown
99 | ```
100 |
101 | Example with breakdown:
102 |
103 | ```
104 | ┌─────────┬──────────────────┬─────────┬──────────┬────────────┐
105 | │ Month │ Models │ Input │ Output │ Cost (USD) │
106 | ├─────────┼──────────────────┼─────────┼──────────┼────────────┤
107 | │ 2025-06 │ opus-4, sonnet-4 │ 45,231 │ 892,456 │ $1,247.92 │
108 | ├─────────┼──────────────────┼─────────┼──────────┼────────────┤
109 | │ └─ opus-4 │ 20,000 │ 400,000 │ $750.50 │
110 | ├─────────┼──────────────────┼─────────┼──────────┼────────────┤
111 | │ └─ sonnet-4 │ 25,231 │ 492,456 │ $497.42 │
112 | └─────────┴──────────────────┴─────────┴──────────┴────────────┘
113 | ```
114 |
115 | ### JSON Output
116 |
117 | ```bash
118 | ccusage monthly --json
119 | ```
120 |
121 | ```json
122 | [
123 | {
124 | "month": "2025-06",
125 | "models": ["opus-4", "sonnet-4"],
126 | "inputTokens": 45231,
127 | "outputTokens": 892456,
128 | "cacheCreationTokens": 2048,
129 | "cacheReadTokens": 4096,
130 | "totalTokens": 943831,
131 | "totalCost": 1247.92
132 | }
133 | ]
134 | ```
135 |
136 | ### Offline Mode
137 |
138 | ```bash
139 | ccusage monthly --offline
140 | ```
141 |
142 | ## Analysis Use Cases
143 |
144 | ### Budget Planning
145 |
146 | Monthly reports help with subscription planning:
147 |
148 | ```bash
149 | # Check last year's usage
150 | ccusage monthly --since 20240101 --until 20241231
151 | ```
152 |
153 | Look at the total cost to understand what you'd pay on usage-based pricing.
154 |
155 | ### Usage Trends
156 |
157 | Track how your usage changes over time:
158 |
159 | ```bash
160 | # Compare year over year
161 | ccusage monthly --since 20230101 --until 20231231 # 2023
162 | ccusage monthly --since 20240101 --until 20241231 # 2024
163 | ```
164 |
165 | ### Model Migration Analysis
166 |
167 | See how your model usage evolves:
168 |
169 | ```bash
170 | ccusage monthly --breakdown
171 | ```
172 |
173 | This helps track transitions between Opus, Sonnet, and other models.
174 |
175 | ### Seasonal Patterns
176 |
177 | Identify busy/slow periods:
178 |
179 | ```bash
180 | # Academic year analysis
181 | ccusage monthly --since 20240901 --until 20250630
182 | ```
183 |
184 | ### Export for Business Analysis
185 |
186 | ```bash
187 | # Create quarterly reports
188 | ccusage monthly --since 20241001 --until 20241231 --json > q4-2024.json
189 | ```
190 |
191 | ## Tips for Monthly Analysis
192 |
193 | ### 1. Cost Context
194 |
195 | Monthly totals show:
196 |
197 | - **Subscription Value**: How much you'd pay with usage-based billing
198 | - **Usage Intensity**: Months with heavy Claude usage
199 | - **Model Preferences**: Which models you favor over time
200 |
201 | ### 2. Trend Analysis
202 |
203 | Look for patterns:
204 |
205 | - Increasing usage over time
206 | - Seasonal variations
207 | - Model adoption curves
208 |
209 | ### 3. Business Planning
210 |
211 | Use monthly data for:
212 |
213 | - Team budget planning
214 | - Usage forecasting
215 | - Subscription optimization
216 |
217 | ### 4. Comparative Analysis
218 |
219 | Compare monthly reports with:
220 |
221 | - Team productivity metrics
222 | - Project timelines
223 | - Business outcomes
224 |
225 | ## Related Commands
226 |
227 | - [Daily Reports](/guide/daily-reports) - Day-by-day breakdown
228 | - [Session Reports](/guide/session-reports) - Individual conversations
229 | - [Blocks Reports](/guide/blocks-reports) - 5-hour billing periods
230 |
231 | ## Next Steps
232 |
233 | After analyzing monthly trends, consider:
234 |
235 | 1. [Session Reports](/guide/session-reports) to identify high-cost conversations
236 | 2. [Live Monitoring](/guide/live-monitoring) to track real-time usage
237 | 3. [Library Usage](/guide/library-usage) for programmatic analysis
238 |
--------------------------------------------------------------------------------
/docs/guide/related-projects.md:
--------------------------------------------------------------------------------
1 | # Related Projects
2 |
3 | Projects that use ccusage internally or extend its functionality:
4 |
5 | ## Desktop Applications
6 |
7 | - [claude-usage-tracker-for-mac](https://github.com/penicillin0/claude-usage-tracker-for-mac) - macOS menu bar app for tracking Claude usage
8 | - [ClaudeCode_Dashboard](https://github.com/m-sigepon/ClaudeCode_Dashboard) - Web dashboard with charts and visualizations
9 | - [Ccusage App](https://github.com/EthanBarlo/ccusage-app) - Native application to display ccusage data in graphs and visualizations
10 | - [CCOwl](https://github.com/sivchari/ccowl) - A cross-platform status bar application that monitors Claude Code usage in real-time.
11 |
12 | ## Extensions & Integrations
13 |
14 | - [ccusage Raycast Extension](https://www.raycast.com/nyatinte/ccusage) - Raycast integration for quick usage checks
15 | - [ccusage.nvim](https://github.com/S1M0N38/ccusage.nvim) - Track Claude Code usage in Neovim
16 |
17 | ## Contributing
18 |
19 | If you've built something that uses ccusage, please feel free to open a pull request to add it to this list!
20 |
--------------------------------------------------------------------------------
/docs/guide/session-reports.md:
--------------------------------------------------------------------------------
1 | # Session Reports
2 |
3 | Session reports show your Claude Code usage grouped by individual conversation sessions, making it easy to identify which conversations consumed the most tokens and cost the most.
4 |
5 | ## Basic Usage
6 |
7 | ```bash
8 | ccusage session
9 | ```
10 |
11 | ## Example Output
12 |
13 | ```
14 | ╭───────────────────────────────────────────────╮
15 | │ │
16 | │ Claude Code Token Usage Report - By Session │
17 | │ │
18 | ╰───────────────────────────────────────────────╯
19 |
20 | ┌────────────┬──────────────────┬────────┬─────────┬──────────────┬────────────┬──────────────┬────────────┬───────────────┐
21 | │ Session │ Models │ Input │ Output │ Cache Create │ Cache Read │ Total Tokens │ Cost (USD) │ Last Activity │
22 | ├────────────┼──────────────────┼────────┼─────────┼──────────────┼────────────┼──────────────┼────────────┼───────────────┤
23 | │ abc123-def │ • opus-4 │ 4,512 │ 350,846 │ 512 │ 1,024 │ 356,894 │ $156.40 │ 2025-06-21 │
24 | │ │ • sonnet-4 │ │ │ │ │ │ │ │
25 | │ ghi456-jkl │ • sonnet-4 │ 2,775 │ 186,645 │ 256 │ 768 │ 190,444 │ $98.45 │ 2025-06-20 │
26 | │ mno789-pqr │ • opus-4 │ 1,887 │ 183,055 │ 128 │ 512 │ 185,582 │ $81.73 │ 2025-06-19 │
27 | ├────────────┼──────────────────┼────────┼─────────┼──────────────┼────────────┼──────────────┼────────────┼───────────────┤
28 | │ Total │ │ 9,174 │ 720,546 │ 896 │ 2,304 │ 732,920 │ $336.58 │ │
29 | └────────────┴──────────────────┴────────┴─────────┴──────────────┴────────────┴──────────────┴────────────┴───────────────┘
30 | ```
31 |
32 | ## Understanding Session Data
33 |
34 | ### Session Identification
35 |
36 | Sessions are displayed using the last two segments of their full identifier:
37 |
38 | - Full session ID: `project-20250621-session-abc123-def456`
39 | - Displayed as: `abc123-def`
40 |
41 | ### Session Metrics
42 |
43 | - **Input/Output Tokens**: Total tokens exchanged in the conversation
44 | - **Cache Tokens**: Cache creation and read tokens for context efficiency
45 | - **Cost**: Estimated USD cost for the entire conversation
46 | - **Last Activity**: Date of the most recent message in the session
47 |
48 | ### Sorting
49 |
50 | Sessions are sorted by cost (highest first) by default, making it easy to identify your most expensive conversations.
51 |
52 | ## Command Options
53 |
54 | ### Date Filtering
55 |
56 | Filter sessions by their last activity date:
57 |
58 | ```bash
59 | # Show sessions active since May 25th
60 | ccusage session --since 20250525
61 |
62 | # Show sessions active in a specific date range
63 | ccusage session --since 20250520 --until 20250530
64 |
65 | # Show only recent sessions (last week)
66 | ccusage session --since $(date -d '7 days ago' +%Y%m%d)
67 | ```
68 |
69 | ### Sort Order
70 |
71 | ```bash
72 | # Show most expensive sessions first (default)
73 | ccusage session --order desc
74 |
75 | # Show least expensive sessions first
76 | ccusage session --order asc
77 | ```
78 |
79 | ### Cost Calculation Modes
80 |
81 | ```bash
82 | # Use pre-calculated costs when available (default)
83 | ccusage session --mode auto
84 |
85 | # Always calculate costs from tokens
86 | ccusage session --mode calculate
87 |
88 | # Only show pre-calculated costs
89 | ccusage session --mode display
90 | ```
91 |
92 | ### Model Breakdown
93 |
94 | See per-model cost breakdown within each session:
95 |
96 | ```bash
97 | ccusage session --breakdown
98 | ```
99 |
100 | Example with breakdown:
101 |
102 | ```
103 | ┌────────────┬──────────────────┬────────┬─────────┬────────────┬───────────────┐
104 | │ Session │ Models │ Input │ Output │ Cost (USD) │ Last Activity │
105 | ├────────────┼──────────────────┼────────┼─────────┼────────────┼───────────────┤
106 | │ abc123-def │ opus-4, sonnet-4 │ 4,512 │ 350,846 │ $156.40 │ 2025-06-21 │
107 | ├────────────┼──────────────────┼────────┼─────────┼────────────┼───────────────┤
108 | │ └─ opus-4│ │ 2,000 │ 200,000 │ $95.50 │ │
109 | ├────────────┼──────────────────┼────────┼─────────┼────────────┼───────────────┤
110 | │ └─ sonnet-4 │ 2,512 │ 150,846 │ $60.90 │ │
111 | └────────────┴──────────────────┴────────┴─────────┴────────────┴───────────────┘
112 | ```
113 |
114 | ### JSON Output
115 |
116 | Export session data as JSON for further analysis:
117 |
118 | ```bash
119 | ccusage session --json
120 | ```
121 |
122 | ```json
123 | {
124 | "sessions": [
125 | {
126 | "sessionId": "abc123-def",
127 | "inputTokens": 4512,
128 | "outputTokens": 350846,
129 | "cacheCreationTokens": 512,
130 | "cacheReadTokens": 1024,
131 | "totalTokens": 356894,
132 | "totalCost": 156.40,
133 | "lastActivity": "2025-06-21",
134 | "modelsUsed": ["opus-4", "sonnet-4"],
135 | "modelBreakdowns": [
136 | {
137 | "model": "opus-4",
138 | "inputTokens": 2000,
139 | "outputTokens": 200000,
140 | "totalCost": 95.50
141 | }
142 | ]
143 | }
144 | ],
145 | "totals": {
146 | "inputTokens": 9174,
147 | "outputTokens": 720546,
148 | "totalCost": 336.58
149 | }
150 | }
151 | ```
152 |
153 | ### Offline Mode
154 |
155 | Use cached pricing data without network access:
156 |
157 | ```bash
158 | ccusage session --offline
159 | # or short form:
160 | ccusage session -O
161 | ```
162 |
163 | ## Analysis Use Cases
164 |
165 | ### Identify Expensive Conversations
166 |
167 | Session reports help you understand which conversations are most costly:
168 |
169 | ```bash
170 | # Find your most expensive sessions
171 | ccusage session --order desc
172 | ```
173 |
174 | Look at the top sessions to understand:
175 |
176 | - Which types of conversations cost the most
177 | - Whether long coding sessions or research tasks are more expensive
178 | - How model choice (Opus vs Sonnet) affects costs
179 |
180 | ### Track Conversation Patterns
181 |
182 | ```bash
183 | # See recent conversation activity
184 | ccusage session --since 20250615
185 |
186 | # Compare different time periods
187 | ccusage session --since 20250601 --until 20250615 # First half of month
188 | ccusage session --since 20250616 --until 20250630 # Second half of month
189 | ```
190 |
191 | ### Model Usage Analysis
192 |
193 | ```bash
194 | # See which models you use in different conversations
195 | ccusage session --breakdown
196 | ```
197 |
198 | This helps understand:
199 |
200 | - Whether you prefer Opus for complex tasks
201 | - If Sonnet is sufficient for routine work
202 | - How model mixing affects total costs
203 |
204 | ### Budget Optimization
205 |
206 | ```bash
207 | # Export data for spreadsheet analysis
208 | ccusage session --json > sessions.json
209 |
210 | # Find sessions above a certain cost threshold
211 | ccusage session --json | jq '.sessions[] | select(.totalCost > 50)'
212 | ```
213 |
214 | ## Tips for Session Analysis
215 |
216 | ### 1. Cost Context Understanding
217 |
218 | Session costs help you understand:
219 |
220 | - **Conversation Value**: High-cost sessions should provide proportional value
221 | - **Efficiency Patterns**: Some conversation styles may be more token-efficient
222 | - **Model Selection**: Whether your model choices align with task complexity
223 |
224 | ### 2. Usage Optimization
225 |
226 | Use session data to:
227 |
228 | - **Identify expensive patterns**: What makes some conversations cost more?
229 | - **Optimize conversation flow**: Break long sessions into smaller focused chats
230 | - **Choose appropriate models**: Use Sonnet for simpler tasks, Opus for complex ones
231 |
232 | ### 3. Budget Planning
233 |
234 | Session analysis helps with:
235 |
236 | - **Conversation budgeting**: Understanding typical session costs
237 | - **Usage forecasting**: Predicting monthly costs based on session patterns
238 | - **Value assessment**: Ensuring expensive sessions provide good value
239 |
240 | ### 4. Comparative Analysis
241 |
242 | Compare sessions to understand:
243 |
244 | - **Task types**: Coding vs writing vs research costs
245 | - **Model effectiveness**: Whether Opus provides value over Sonnet
246 | - **Time patterns**: Whether longer sessions are more or less efficient
247 |
248 | ## Responsive Display
249 |
250 | Session reports adapt to your terminal width:
251 |
252 | - **Wide terminals (≥100 chars)**: Shows all columns including cache metrics
253 | - **Narrow terminals (<100 chars)**: Compact mode with essential columns (Session, Models, Input, Output, Cost, Last Activity)
254 |
255 | When in compact mode, ccusage displays a message explaining how to see the full data.
256 |
257 | ## Related Commands
258 |
259 | - [Daily Reports](/guide/daily-reports) - Usage aggregated by date
260 | - [Monthly Reports](/guide/monthly-reports) - Monthly summaries
261 | - [Blocks Reports](/guide/blocks-reports) - 5-hour billing windows
262 | - [Live Monitoring](/guide/live-monitoring) - Real-time session tracking
263 |
264 | ## Next Steps
265 |
266 | After analyzing session patterns, consider:
267 |
268 | 1. [Blocks Reports](/guide/blocks-reports) to understand timing within 5-hour windows
269 | 2. [Live Monitoring](/guide/live-monitoring) to track active conversations in real-time
270 | 3. [Daily Reports](/guide/daily-reports) to see how session patterns vary by day
271 |
--------------------------------------------------------------------------------
/docs/guide/sponsors.md:
--------------------------------------------------------------------------------
1 | # Sponsors
2 |
3 | Support ccusage development by becoming a sponsor! Your contribution helps maintain and improve this tool.
4 |
5 | ## Featured Sponsor
6 |
7 | Check out these [47 Claude Code ProTips from Greg Baugues.](https://www.youtube.com/watch?v=TiNpzxoBPz0&lc=UgyVgQyOhfJJlheVMcB4AaABAg)
8 |
9 | <p align="center">
10 | <a href="https://www.youtube.com/watch?v=TiNpzxoBPz0&lc=UgyVgQyOhfJJlheVMcB4AaABAg">
11 | <img src="/claude_code_protips_thumbnail_v1.png" alt="47 Claude Code ProTips from Greg Baugues" width="600">
12 | </a>
13 | </p>
14 |
15 | <p align="center">
16 | <a href="https://github.com/sponsors/ryoppippi">
17 | <img src="https://cdn.jsdelivr.net/gh/ryoppippi/sponsors@main/sponsors.svg">
18 | </a>
19 | </p>
20 |
21 | ## How to Sponsor
22 |
23 | Visit [GitHub Sponsors - @ryoppippi](https://github.com/sponsors/ryoppippi) to support the development of ccusage and other open source projects.
24 |
25 | ## Star History
26 |
27 | <a href="https://www.star-history.com/#ryoppippi/ccusage&Date">
28 | <picture>
29 | <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=ryoppippi/ccusage&type=Date&theme=dark" />
30 | <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=ryoppippi/ccusage&type=Date" />
31 | <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=ryoppippi/ccusage&type=Date" />
32 | </picture>
33 | </a>
34 |
--------------------------------------------------------------------------------
/docs/guide/statusline.md:
--------------------------------------------------------------------------------
1 | # Statusline Integration (Beta) 🚀
2 |
3 | Display real-time usage statistics in your Claude Code status line.
4 |
5 | ## Overview
6 |
7 | The `statusline` command provides a compact, real-time view of your Claude Code usage, designed to integrate with Claude Code's status line hooks. It shows:
8 |
9 | - 💬 **Current session cost** - Cost for your active conversation session
10 | - 💰 **Today's total cost** - Your cumulative spending for the current day
11 | - 🚀 **Current session block** - Cost and time remaining in your active 5-hour billing block
12 | - 🔥 **Burn rate** - Token consumption rate with visual indicators
13 | - 🤖 **Active model** - The Claude model you're currently using
14 |
15 | ## Setup
16 |
17 | ### Configure settings.json
18 |
19 | Add this to your `~/.claude/settings.json` or `~/.config/claude/settings.json`:
20 |
21 | ```json
22 | {
23 | "statusLine": {
24 | "type": "command",
25 | "command": "bun x ccusage statusline", // Use "npx -y ccusage statusline" if you prefer npm
26 | "padding": 0 // Optional: set to 0 to let status line go to edge
27 | }
28 | }
29 | ```
30 |
31 | By default, statusline uses **offline mode** with cached pricing data for optimal performance.
32 |
33 | ### Online Mode (Optional)
34 |
35 | If you need the latest pricing data from LiteLLM API, you can explicitly enable online mode:
36 |
37 | ```json
38 | {
39 | "statusLine": {
40 | "type": "command",
41 | "command": "bun x ccusage statusline --no-offline", // Fetches latest pricing from API
42 | "padding": 0
43 | }
44 | }
45 | ```
46 |
47 | ## Output Format
48 |
49 | The statusline displays a compact, single-line summary:
50 |
51 | ```
52 | 🤖 Opus | 💰 $0.23 session / $1.23 today / $0.45 block (2h 45m left) | 🔥 $0.12/hr
53 | ```
54 |
55 | ### Components Explained
56 |
57 | - **Model** (`🤖 Opus`): Currently active Claude model
58 | - **Session Cost** (`💰 $0.23 session`): Cost for the current conversation session
59 | - **Today's Cost** (`$1.23 today`): Total cost for the current day across all sessions
60 | - **Session Block** (`$0.45 block (2h 45m left)`): Current 5-hour block cost with remaining time
61 | - **Burn Rate** (`🔥 $0.12/hr`): Cost burn rate per hour with color-coded indicators:
62 | - Green text: Normal (< 2,000 tokens/min)
63 | - Yellow text: Moderate (2,000-5,000 tokens/min)
64 | - Red text: High (> 5,000 tokens/min)
65 |
66 | When no active block exists:
67 | ```
68 | 🤖 Opus | 💰 $0.00 session / $0.00 today / No active block
69 | ```
70 |
71 | ## Technical Details
72 |
73 | The statusline command:
74 | - Reads session information from stdin (provided by Claude Code hooks)
75 | - Identifies the active 5-hour billing block
76 | - Calculates real-time burn rates and projections
77 | - Outputs a single line suitable for status bar display
78 | - **Uses offline mode by default** for instant response times without network dependencies
79 | - Can be configured to use online mode with `--no-offline` for latest pricing data
80 |
81 | ## Beta Notice
82 |
83 | ⚠️ This feature is currently in **beta**. More customization options and features are coming soon:
84 |
85 | - Custom format templates
86 | - Configurable burn rate thresholds
87 | - Additional metrics display options
88 | - Session-specific cost tracking
89 |
90 | ## Troubleshooting
91 |
92 | ### No Output Displayed
93 |
94 | If the statusline doesn't show:
95 | 1. Verify `ccusage` is in your PATH
96 | 2. Check Claude Code logs for any errors
97 | 3. Ensure you have valid usage data in your Claude data directory
98 |
99 | ### Incorrect Costs
100 |
101 | If costs seem incorrect:
102 | - The command uses the same cost calculation as other ccusage commands
103 | - Verify with `ccusage daily` or `ccusage blocks` for detailed breakdowns
104 |
105 | ## Related Commands
106 |
107 | - [`blocks`](./blocks-reports.md) - Detailed 5-hour billing block analysis
108 | - [`daily`](./daily-reports.md) - Daily usage reports
109 | - [`session`](./session-reports.md) - Session-based usage analysis
110 |
--------------------------------------------------------------------------------
/docs/guide/weekly-reports.md:
--------------------------------------------------------------------------------
1 | # Weekly Reports
2 |
3 | Weekly reports aggregate your Claude Code usage by week, providing a mid-range view between daily and monthly reports. This helps identify weekly patterns and trends in your usage.
4 |
5 | ## Basic Usage
6 |
7 | Show all weekly usage:
8 |
9 | ```bash
10 | ccusage weekly
11 | ```
12 |
13 | ## Example Output
14 |
15 | ```
16 | ┌────────────────┬──────────────────┬────────┬─────────┬─────────────┬────────────┬──────────────┬────────────┐
17 | │ Week │ Models │ Input │ Output │ Cache Create│ Cache Read │ Total Tokens │ Cost (USD) │
18 | ├────────────────┼──────────────────┼────────┼─────────┼─────────────┼────────────┼──────────────┼────────────┤
19 | │ 2025-06-16 │ • opus-4 │ 1,234 │ 156,789 │ 2,048 │ 4,096 │ 164,167 │ $87.56 │
20 | │ │ • sonnet-4 │ │ │ │ │ │ │
21 | ├────────────────┼──────────────────┼────────┼─────────┼─────────────┼────────────┼──────────────┼────────────┤
22 | │ 2025-06-23 │ • sonnet-4 │ 2,456 │ 234,567 │ 3,072 │ 6,144 │ 246,239 │ $104.33 │
23 | ├────────────────┼──────────────────┼────────┼─────────┼─────────────┼────────────┼──────────────┼────────────┤
24 | │ 2025-06-30 │ • opus-4 │ 3,789 │ 345,678 │ 4,096 │ 8,192 │ 361,755 │ $156.78 │
25 | │ │ • sonnet-4 │ │ │ │ │ │ │
26 | └────────────────┴──────────────────┴────────┴─────────┴─────────────┴────────────┴──────────────┴────────────┘
27 | ```
28 |
29 | ## Understanding the Columns
30 |
31 | The columns are identical to daily reports but aggregated by week:
32 |
33 | - **Week**: Start date of the week (configurable)
34 | - **Models**: All Claude models used during the week
35 | - **Input/Output**: Total tokens for the week
36 | - **Cache Create/Read**: Cache token usage
37 | - **Total Tokens**: Sum of all token types
38 | - **Cost (USD)**: Estimated cost for the week
39 |
40 | ## Command Options
41 |
42 | ### Week Start Day
43 |
44 | Configure which day starts the week:
45 |
46 | ```bash
47 | # Start week on Sunday (default)
48 | ccusage weekly --start-of-week sunday
49 |
50 | # Start week on Monday
51 | ccusage weekly --start-of-week monday
52 | ccusage weekly -w monday
53 |
54 | # Other options: tuesday, wednesday, thursday, friday, saturday
55 | ```
56 |
57 | ### Date Filtering
58 |
59 | Filter by date range:
60 |
61 | ```bash
62 | # Show specific period
63 | ccusage weekly --since 20250601 --until 20250630
64 |
65 | # Show last 4 weeks
66 | ccusage weekly --since 20250501
67 | ```
68 |
69 | ### Sort Order
70 |
71 | Control the order of weeks:
72 |
73 | ```bash
74 | # Newest weeks first (default)
75 | ccusage weekly --order desc
76 |
77 | # Oldest weeks first
78 | ccusage weekly --order asc
79 | ```
80 |
81 | ### Model Breakdown
82 |
83 | See per-model weekly costs:
84 |
85 | ```bash
86 | ccusage weekly --breakdown
87 | ```
88 |
89 | ```
90 | ┌────────────────┬──────────────────┬────────┬─────────┬────────────┐
91 | │ Week │ Models │ Input │ Output │ Cost (USD) │
92 | ├────────────────┼──────────────────┼────────┼─────────┼────────────┤
93 | │ 2025-06-16 │ opus-4, sonnet-4 │ 1,234 │ 156,789 │ $87.56 │
94 | ├────────────────┼──────────────────┼────────┼─────────┼────────────┤
95 | │ └─ opus-4 │ │ 800 │ 80,000 │ $54.80 │
96 | ├────────────────┼──────────────────┼────────┼─────────┼────────────┤
97 | │ └─ sonnet-4 │ │ 434 │ 76,789 │ $32.76 │
98 | └────────────────┴──────────────────┴────────┴─────────┴────────────┘
99 | ```
100 |
101 | ### JSON Output
102 |
103 | Export weekly data as JSON:
104 |
105 | ```bash
106 | ccusage weekly --json
107 | ```
108 |
109 | ```json
110 | {
111 | "weekly": [
112 | {
113 | "week": "2025-06-16",
114 | "inputTokens": 1234,
115 | "outputTokens": 156789,
116 | "cacheCreationTokens": 2048,
117 | "cacheReadTokens": 4096,
118 | "totalTokens": 164167,
119 | "totalCost": 87.56,
120 | "modelsUsed": ["claude-opus-4-20250514", "claude-sonnet-4-20250514"],
121 | "modelBreakdowns": {
122 | "claude-opus-4-20250514": {
123 | "inputTokens": 800,
124 | "outputTokens": 80000,
125 | "totalCost": 54.80
126 | },
127 | "claude-sonnet-4-20250514": {
128 | "inputTokens": 434,
129 | "outputTokens": 76789,
130 | "totalCost": 32.76
131 | }
132 | }
133 | }
134 | ],
135 | "totals": {
136 | "inputTokens": 7479,
137 | "outputTokens": 737034,
138 | "cacheCreationTokens": 9216,
139 | "cacheReadTokens": 18432,
140 | "totalTokens": 772161,
141 | "totalCost": 348.67
142 | }
143 | }
144 | ```
145 |
146 | ### Project Analysis
147 |
148 | Group weekly usage by project:
149 |
150 | ```bash
151 | # Show weekly usage per project
152 | ccusage weekly --instances
153 |
154 | # Filter to specific project
155 | ccusage weekly --project my-project
156 | ```
157 |
158 | ### Cost Calculation Modes
159 |
160 | Control cost calculation:
161 |
162 | ```bash
163 | # Auto mode (default)
164 | ccusage weekly --mode auto
165 |
166 | # Always calculate from tokens
167 | ccusage weekly --mode calculate
168 |
169 | # Only use pre-calculated costs
170 | ccusage weekly --mode display
171 | ```
172 |
173 | ### Offline Mode
174 |
175 | Use cached pricing data:
176 |
177 | ```bash
178 | ccusage weekly --offline
179 | ```
180 |
181 | ## Common Use Cases
182 |
183 | ### Weekly Trends
184 |
185 | ```bash
186 | # See usage trends over past months
187 | ccusage weekly --since 20250401
188 | ```
189 |
190 | ### Sprint Analysis
191 |
192 | ```bash
193 | # Track usage during 2-week sprints (Monday start)
194 | ccusage weekly --start-of-week monday --since 20250601
195 | ```
196 |
197 | ### Budget Planning
198 |
199 | ```bash
200 | # Export for weekly budget tracking
201 | ccusage weekly --json > weekly-budget.json
202 | ```
203 |
204 | ### Compare Workweeks
205 |
206 | ```bash
207 | # Monday-Friday work pattern analysis
208 | ccusage weekly --start-of-week monday --breakdown
209 | ```
210 |
211 | ### Team Reporting
212 |
213 | ```bash
214 | # Weekly team usage report
215 | ccusage weekly --instances --start-of-week monday
216 | ```
217 |
218 | ## Tips
219 |
220 | 1. **Week Start**: Choose a start day that aligns with your work schedule
221 | 2. **Breakdown View**: Use `--breakdown` to identify which models drive costs
222 | 3. **JSON Export**: Weekly JSON data is perfect for creating trend charts
223 | 4. **Project Tracking**: Use `--instances` to track project-specific weekly usage
224 |
225 | ## Related Commands
226 |
227 | - [Daily Reports](/guide/daily-reports) - Day-by-day analysis
228 | - [Monthly Reports](/guide/monthly-reports) - Monthly aggregates
229 | - [Session Reports](/guide/session-reports) - Per-conversation analysis
230 | - [Blocks Reports](/guide/blocks-reports) - 5-hour billing windows
--------------------------------------------------------------------------------
/docs/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: home
3 |
4 | hero:
5 | name: ccusage
6 | text: Claude Code Usage Analysis
7 | tagline: A powerful CLI tool for analyzing Claude Code usage from local JSONL files
8 | image:
9 | src: /logo.svg
10 | alt: ccusage logo
11 | actions:
12 | - theme: brand
13 | text: Get Started
14 | link: /guide/
15 | - theme: alt
16 | text: View on GitHub
17 | link: https://github.com/ryoppippi/ccusage
18 |
19 | features:
20 | - icon: 📊
21 | title: Daily Reports
22 | details: View token usage and costs aggregated by date with detailed breakdowns
23 | link: /guide/daily-reports
24 | - icon: 📆
25 | title: Weekly Reports
26 | details: Track usage patterns by week with configurable start day
27 | link: /guide/weekly-reports
28 | - icon: 📅
29 | title: Monthly Reports
30 | details: Analyze usage patterns over monthly periods with cost tracking
31 | link: /guide/monthly-reports
32 | - icon: 💬
33 | title: Session Reports
34 | details: Group usage by conversation sessions for detailed analysis
35 | link: /guide/session-reports
36 | - icon: ⏰
37 | title: 5-Hour Blocks
38 | details: Track usage within Claude's billing windows with active monitoring
39 | link: /guide/blocks-reports
40 | - icon: 📈
41 | title: Live Monitoring
42 | details: Real-time dashboard with progress bars and cost projections
43 | link: /guide/live-monitoring
44 | - icon: 🤖
45 | title: Model Tracking
46 | details: See which Claude models you're using (Opus, Sonnet, etc.)
47 | - icon: 📋
48 | title: Enhanced Display
49 | details: Beautiful tables with responsive layout and smart formatting
50 | - icon: 📄
51 | title: JSON Output
52 | details: Export data in structured JSON format for programmatic use
53 | link: /guide/json-output
54 | - icon: 💰
55 | title: Cost Analysis
56 | details: Shows estimated costs in USD for each day/month/session
57 | - icon: 🔄
58 | title: Cache Support
59 | details: Tracks cache creation and cache read tokens separately
60 | - icon: 🌐
61 | title: Offline Mode
62 | details: Use pre-cached pricing data without network connectivity
63 | - icon: 🔌
64 | title: MCP Integration
65 | details: Built-in Model Context Protocol server for tool integration
66 | link: /guide/mcp-server
67 | ---
68 |
69 | <div style="text-align: center; margin: 2rem 0;">
70 | <h2 style="margin-bottom: 1rem;">Support ccusage</h2>
71 | <p style="margin-bottom: 1.5rem;">If you find ccusage helpful, please consider sponsoring the development!</p>
72 |
73 | <h3 style="margin-bottom: 1rem;">Featured Sponsor</h3>
74 | <p style="margin-bottom: 1rem;">Check out these <a href="https://www.youtube.com/watch?v=TiNpzxoBPz0&lc=UgyVgQyOhfJJlheVMcB4AaABAg" target="_blank">47 Claude Code ProTips from Greg Baugues.</a></p>
75 | <a href="https://www.youtube.com/watch?v=TiNpzxoBPz0&lc=UgyVgQyOhfJJlheVMcB4AaABAg" target="_blank">
76 | <img src="/claude_code_protips_thumbnail_v1.png" alt="47 Claude Code ProTips from Greg Baugues" style="max-width: 600px; height: auto;">
77 | </a>
78 |
79 | <div style="margin-top: 2rem;">
80 | <a href="https://github.com/sponsors/ryoppippi" target="_blank">
81 | <img src="https://cdn.jsdelivr.net/gh/ryoppippi/sponsors@main/sponsors.svg" alt="Sponsors" style="max-width: 100%; height: auto;">
82 | </a>
83 | </div>
84 | </div>
85 |
--------------------------------------------------------------------------------
/docs/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "@ccusage/docs",
3 | "version": "15.0.0",
4 | "private": true,
5 | "description": "Documentation for ccusage",
6 | "type": "module",
7 | "scripts": {
8 | "build": "bun run docs:api && ROLLDOWN_OPTIONS_VALIDATION=loose vitepress build",
9 | "deploy": "wrangler deploy",
10 | "dev": "bun run docs:api && ROLLDOWN_OPTIONS_VALIDATION=loose vitepress dev",
11 | "docs:api": "./update-api-index.ts",
12 | "preview": "vitepress preview"
13 | },
14 | "overrides": {
15 | "vite": "npm:rolldown-vite@latest"
16 | },
17 | "devDependencies": {
18 | "@ryoppippi/vite-plugin-cloudflare-redirect": "npm:@jsr/ryoppippi__vite-plugin-cloudflare-redirect",
19 | "@types/bun": "^1.2.19",
20 | "tinyglobby": "^0.2.14",
21 | "typedoc": "^0.28.9",
22 | "typedoc-plugin-markdown": "^4.8.0",
23 | "typedoc-vitepress-theme": "^1.1.2",
24 | "vitepress": "^1.6.4",
25 | "vitepress-plugin-group-icons": "^1.6.1",
26 | "vitepress-plugin-llms": "^1.7.2",
27 | "vitepress-plugin-mermaid": "^2.0.17",
28 | "wrangler": "^4.28.1"
29 | }
30 | }
31 |
--------------------------------------------------------------------------------
/docs/public/blocks-live.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ryoppippi/ccusage/451e8e97ea30a114675a6d83ca6456a7797bd5fc/docs/public/blocks-live.png
--------------------------------------------------------------------------------
/docs/public/claude_code_protips_thumbnail_v1.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ryoppippi/ccusage/451e8e97ea30a114675a6d83ca6456a7797bd5fc/docs/public/claude_code_protips_thumbnail_v1.png
--------------------------------------------------------------------------------
/docs/public/favicon.svg:
--------------------------------------------------------------------------------
1 | <svg width="512" height="512" viewBox="0 0 512 512" fill="none" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" class=""><rect id="«r3g»" width="512" height="512" x="0" y="0" rx="128" fill="#F3E9D7" stroke="#FFFFFF" stroke-width="0" stroke-opacity="100%" paint-order="stroke"></rect><clipPath id="clip"><use xlink:href="#«r3g»"></use></clipPath><defs><linearGradient id="«r3h»" gradientUnits="userSpaceOnUse" gradientTransform="rotate(90)" style="transform-origin: center center;"><stop stop-color="#F3E9D7"></stop><stop offset="1" stop-color="#3F2B96"></stop></linearGradient><radialGradient id="«r3i»" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(256) rotate(90) scale(512)"><stop stop-color="white"></stop><stop offset="1" stop-color="white" stop-opacity="0"></stop></radialGradient></defs><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 16 16" width="400" height="400" x="56" y="56" alignment-baseline="middle" style="color: rgb(217, 119, 87);"><path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M1.75 9v3c0 1.243 1.903 2.25 4.25 2.25s4.25-1.007 4.25-2.25V9m-8.5 0c0 1.243 1.903 2.25 4.25 2.25s4.25-1.007 4.25-2.25m-8.5 0c0-1.243 1.903-2.25 4.25-2.25S10.25 7.757 10.25 9m-4.5-5c0-1.243 1.903-2.25 4.25-2.25S14.25 2.757 14.25 4m0 0c0 .86-.911 1.607-2.25 1.986M14.25 4v3c0 .623-.728 1.343-1.5 1.75"></path></svg></svg>
--------------------------------------------------------------------------------
/docs/public/logo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ryoppippi/ccusage/451e8e97ea30a114675a6d83ca6456a7797bd5fc/docs/public/logo.png
--------------------------------------------------------------------------------
/docs/public/logo.svg:
--------------------------------------------------------------------------------
1 | <svg width="512" height="512" viewBox="0 0 512 512" fill="none" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" class=""><rect id="«r3g»" width="512" height="512" x="0" y="0" rx="128" fill="#F3E9D7" stroke="#FFFFFF" stroke-width="0" stroke-opacity="100%" paint-order="stroke"></rect><clipPath id="clip"><use xlink:href="#«r3g»"></use></clipPath><defs><linearGradient id="«r3h»" gradientUnits="userSpaceOnUse" gradientTransform="rotate(90)" style="transform-origin: center center;"><stop stop-color="#F3E9D7"></stop><stop offset="1" stop-color="#3F2B96"></stop></linearGradient><radialGradient id="«r3i»" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(256) rotate(90) scale(512)"><stop stop-color="white"></stop><stop offset="1" stop-color="white" stop-opacity="0"></stop></radialGradient></defs><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 16 16" width="400" height="400" x="56" y="56" alignment-baseline="middle" style="color: rgb(217, 119, 87);"><path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M1.75 9v3c0 1.243 1.903 2.25 4.25 2.25s4.25-1.007 4.25-2.25V9m-8.5 0c0 1.243 1.903 2.25 4.25 2.25s4.25-1.007 4.25-2.25m-8.5 0c0-1.243 1.903-2.25 4.25-2.25S10.25 7.757 10.25 9m-4.5-5c0-1.243 1.903-2.25 4.25-2.25S14.25 2.757 14.25 4m0 0c0 .86-.911 1.607-2.25 1.986M14.25 4v3c0 .623-.728 1.343-1.5 1.75"></path></svg></svg>
--------------------------------------------------------------------------------
/docs/public/mcp-claude-desktop.avif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ryoppippi/ccusage/451e8e97ea30a114675a6d83ca6456a7797bd5fc/docs/public/mcp-claude-desktop.avif
--------------------------------------------------------------------------------
/docs/public/screenshot.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ryoppippi/ccusage/451e8e97ea30a114675a6d83ca6456a7797bd5fc/docs/public/screenshot.png
--------------------------------------------------------------------------------
/docs/tsconfig.json:
--------------------------------------------------------------------------------
1 | {
2 | "extends": "../tsconfig.json",
3 | "compilerOptions": {
4 | "allowImportingTsExtensions": false,
5 | "allowJs": true,
6 | "noEmit": true,
7 | "skipLibCheck": true
8 | },
9 | "include": [
10 | ".vitepress/**/*",
11 | "**/*.ts",
12 | "**/*.md"
13 | ]
14 | }
15 |
--------------------------------------------------------------------------------
/docs/typedoc.config.mjs:
--------------------------------------------------------------------------------
1 | // @ts-check
2 | import { globSync } from 'tinyglobby'
3 |
4 | const entryPoints = [
5 | ...globSync([
6 | '../src/*.ts',
7 | '!../src/**/*.test.ts', // Exclude test files
8 | '!../src/_*.ts', // Exclude internal files with underscore prefix
9 | ], {
10 | absolute: false,
11 | onlyFiles: true,
12 | }),
13 | '../src/_consts.ts', // Include constants for documentation
14 | ];
15 |
16 | /** @type {import('typedoc').TypeDocOptions & import('typedoc-plugin-markdown').PluginOptions & { docsRoot?: string } } */
17 | export default {
18 | // typedoc options
19 | // ref: https://typedoc.org/documents/Options.html
20 | entryPoints,
21 | tsconfig: '../tsconfig.json',
22 | out: 'api',
23 | plugin: ['typedoc-plugin-markdown', 'typedoc-vitepress-theme'],
24 | readme: 'none',
25 | excludeInternal: true,
26 | groupOrder: ['Variables', 'Functions', 'Class'],
27 | categoryOrder: ['*', 'Other'],
28 | sort: ['source-order'],
29 |
30 | // typedoc-plugin-markdown options
31 | // ref: https://typedoc-plugin-markdown.org/docs/options
32 | entryFileName: 'index',
33 | hidePageTitle: false,
34 | useCodeBlocks: true,
35 | disableSources: true,
36 | indexFormat: 'table',
37 | parametersFormat: 'table',
38 | interfacePropertiesFormat: 'table',
39 | classPropertiesFormat: 'table',
40 | propertyMembersFormat: 'table',
41 | typeAliasPropertiesFormat: 'table',
42 | enumMembersFormat: 'table',
43 |
44 | // typedoc-vitepress-theme options
45 | // ref: https://typedoc-plugin-markdown.org/plugins/vitepress/options
46 | docsRoot: '.',
47 | };
48 |
--------------------------------------------------------------------------------
/docs/update-api-index.ts:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env -S bun -b
2 |
3 | /**
4 | * Post-processing script to update API index with module descriptions
5 | */
6 |
7 | import { join } from 'node:path';
8 | import process from 'node:process';
9 | import { $ } from 'bun';
10 |
11 | const descriptions = {
12 | '\\_consts': 'Internal constants (not exported in public API)',
13 | 'calculate-cost': 'Cost calculation utilities for usage data analysis',
14 | 'data-loader': 'Data loading utilities for Claude Code usage analysis',
15 | 'debug': 'Debug utilities for cost calculation validation',
16 | 'index': 'Main entry point for ccusage CLI tool',
17 | 'logger': 'Logging utilities for the ccusage application',
18 | 'mcp': 'MCP (Model Context Protocol) server implementation',
19 | 'pricing-fetcher': 'Model pricing data fetcher for cost calculations',
20 | } as const;
21 |
22 | async function updateApiIndex() {
23 | const apiIndexPath = join(process.cwd(), 'api', 'index.md');
24 |
25 | try {
26 | let content = await Bun.file(apiIndexPath).text();
27 |
28 | // Replace empty descriptions with actual ones
29 | for (const [module, description] of Object.entries(descriptions)) {
30 | let linkPath = `${module}/index.md`;
31 | // Special case for _consts which links to consts/
32 | if (module === '\\_consts') {
33 | linkPath = 'consts/index.md';
34 | }
35 |
36 | const oldPattern = new RegExp(`\\|\\s*\\[${module}\\]\\(${linkPath}\\)\\s*\\|\\s*-\\s*\\|`, 'g');
37 | content = content.replace(oldPattern, `| [${module}](${linkPath}) | ${description} |`);
38 | }
39 |
40 | await Bun.write(apiIndexPath, content);
41 | console.log('✅ Updated API index with module descriptions');
42 | }
43 | catch (error) {
44 | console.error('❌ Failed to update API index:', error);
45 | process.exit(1);
46 | }
47 | }
48 |
49 | async function updateConstsPage() {
50 | const constsIndexPath = join(process.cwd(), 'api', 'consts', 'index.md');
51 |
52 | try {
53 | let content = await Bun.file(constsIndexPath).text();
54 |
55 | // Add note about constants not being exported (only if not already present)
56 | const noteText = '> **Note**: These constants are internal implementation details and are not exported in the public API. They are documented here for reference purposes only.';
57 |
58 | if (!content.includes(noteText)) {
59 | const oldHeader = '# \\_consts';
60 | const newHeader = `# \\_consts
61 |
62 | ${noteText}`;
63 |
64 | content = content.replace(oldHeader, newHeader);
65 | }
66 |
67 | await Bun.write(constsIndexPath, content);
68 | console.log('✅ Updated constants page with disclaimer');
69 | }
70 | catch (error) {
71 | console.error('❌ Failed to update constants page:', error);
72 | // Don't exit here as this is optional
73 | }
74 | }
75 |
76 | async function main() {
77 | await
bun -b typedoc --excludeInternal`
78 | await updateApiIndex();
79 | await updateConstsPage();
80 | }
81 |
82 | await main();
83 |
--------------------------------------------------------------------------------
/docs/wrangler.jsonc:
--------------------------------------------------------------------------------
1 | {
2 | "$schema": "../node_modules/wrangler/config-schema.json",
3 | "name": "ccusage-guide",
4 | "compatibility_date": "2025-07-21",
5 | "build": {
6 | "command": "bun run build"
7 | },
8 | "assets": {
9 | "directory": ".vitepress/dist/",
10 | "not_found_handling": "404-page"
11 | }
12 | }
13 |
--------------------------------------------------------------------------------
/eslint.config.js:
--------------------------------------------------------------------------------
1 | import { ryoppippi } from '@ryoppippi/eslint-config';
2 |
3 | export default ryoppippi({
4 | type: 'lib',
5 | svelte: false,
6 | typescript: {
7 | tsconfigPath: './tsconfig.json',
8 | },
9 | ignores: [
10 | 'docs/**',
11 | ],
12 | }, {
13 | rules: {
14 | 'test/no-importing-vitest-globals': 'error',
15 | },
16 | });
17 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "ccusage",
3 | "type": "module",
4 | "version": "15.9.2",
5 | "description": "Usage analysis tool for Claude Code",
6 | "author": "ryoppippi",
7 | "license": "MIT",
8 | "funding": "https://github.com/ryoppippi/ccusage?sponsor=1",
9 | "homepage": "https://github.com/ryoppippi/ccusage#readme",
10 | "repository": {
11 | "type": "git",
12 | "url": "git+https://github.com/ryoppippi/ccusage.git"
13 | },
14 | "bugs": {
15 | "url": "https://github.com/ryoppippi/ccusage/issues"
16 | },
17 | "exports": {
18 | ".": "./dist/index.js",
19 | "./calculate-cost": "./dist/calculate-cost.js",
20 | "./data-loader": "./dist/data-loader.js",
21 | "./debug": "./dist/debug.js",
22 | "./logger": "./dist/logger.js",
23 | "./mcp": "./dist/mcp.js",
24 | "./pricing-fetcher": "./dist/pricing-fetcher.js",
25 | "./package.json": "./package.json"
26 | },
27 | "main": "./dist/index.js",
28 | "module": "./dist/index.js",
29 | "types": "./dist/index.d.ts",
30 | "bin": "./dist/index.js",
31 | "files": [
32 | "dist"
33 | ],
34 | "workspaces": [
35 | ".",
36 | "docs"
37 | ],
38 | "engines": {
39 | "node": ">=20.19.4"
40 | },
41 | "scripts": {
42 | "build": "tsdown",
43 | "docs:build": "cd docs && bun run build",
44 | "docs:deploy": "cd docs && bun run deploy",
45 | "docs:dev": "cd docs && bun run dev",
46 | "docs:preview": "cd docs && bun run preview",
47 | "format": "bun run lint --fix",
48 | "lint": "eslint --cache .",
49 | "mcp": "bunx @modelcontextprotocol/inspector bun run start mcp",
50 | "prepack": "bun run build && clean-pkg-json",
51 | "prepare": "simple-git-hooks",
52 | "release": "bun lint && bun typecheck && vitest run && bun run build && bumpp",
53 | "start": "bun run ./src/index.ts",
54 | "test": "TZ=UTC vitest",
55 | "test:statusline": "cat test/statusline-test.json | bun run start statusline",
56 | "typecheck": "tsgo --noEmit"
57 | },
58 | "devDependencies": {
59 | "@antfu/utils": "^9.2.0",
60 | "@core/errorutil": "npm:@jsr/core__errorutil",
61 | "@hono/mcp": "^0.1.0",
62 | "@hono/node-server": "^1.18.1",
63 | "@jsr/std__async": "1",
64 | "@mizchi/lsmcp": "^0.9.3",
65 | "@modelcontextprotocol/sdk": "^1.17.2",
66 | "@oxc-project/runtime": "^0.81.0",
67 | "@praha/byethrow": "^0.6.2",
68 | "@praha/byethrow-mcp": "^0.1.0",
69 | "@ryoppippi/eslint-config": "^0.3.7",
70 | "@types/bun": "^1.2.19",
71 | "@typescript/native-preview": "^7.0.0-dev.20250807.1",
72 | "ansi-escapes": "^7.0.0",
73 | "bumpp": "^10.2.2",
74 | "clean-pkg-json": "^1.3.0",
75 | "cli-table3": "^0.6.5",
76 | "consola": "^3.4.2",
77 | "es-toolkit": "^1.39.8",
78 | "eslint": "^9.32.0",
79 | "eslint-plugin-format": "^1.0.1",
80 | "fast-sort": "^3.4.1",
81 | "fs-fixture": "^2.8.1",
82 | "get-stdin": "^9.0.0",
83 | "gunshi": "^0.26.3",
84 | "hono": "^4.8.12",
85 | "lint-staged": "^16.1.2",
86 | "nano-spawn": "^1.0.2",
87 | "path-type": "^6.0.0",
88 | "picocolors": "^1.1.1",
89 | "pretty-ms": "^9.2.0",
90 | "publint": "^0.3.12",
91 | "simple-git-hooks": "^2.13.1",
92 | "sort-package-json": "^3.4.0",
93 | "string-width": "^7.2.0",
94 | "tinyglobby": "^0.2.14",
95 | "tsdown": "^0.13.3",
96 | "type-fest": "^4.41.0",
97 | "unplugin-macros": "^0.17.1",
98 | "unplugin-unused": "^0.5.1",
99 | "vitest": "^3.2.4",
100 | "xdg-basedir": "^5.1.0",
101 | "zod": "^3.25.67"
102 | },
103 | "overrides": {
104 | "vite": "npm:rolldown-vite@latest"
105 | },
106 | "simple-git-hooks": {
107 | "pre-commit": "bun lint-staged"
108 | },
109 | "lint-staged": {
110 | "*": [
111 | "eslint --cache --fix"
112 | ],
113 | "package.json": [
114 | "sort-package-json"
115 | ]
116 | },
117 | "trustedDependencies": [
118 | "simple-git-hooks"
119 | ]
120 | }
121 |
--------------------------------------------------------------------------------
/src/_consts.ts:
--------------------------------------------------------------------------------
1 | import { homedir } from 'node:os';
2 | import { xdgConfig } from 'xdg-basedir';
3 |
4 | /**
5 | * URL for LiteLLM's model pricing and context window data
6 | */
7 | export const LITELLM_PRICING_URL
8 | = 'https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json';
9 |
10 | /**
11 | * Default number of recent days to include when filtering blocks
12 | * Used in both session blocks and commands for consistent behavior
13 | */
14 | export const DEFAULT_RECENT_DAYS = 3;
15 |
16 | /**
17 | * Threshold percentage for showing usage warnings in blocks command (80%)
18 | * When usage exceeds this percentage of limits, warnings are displayed
19 | */
20 | export const BLOCKS_WARNING_THRESHOLD = 0.8;
21 |
22 | /**
23 | * Terminal width threshold for switching to compact display mode in blocks command
24 | * Below this width, tables use more compact formatting
25 | */
26 | export const BLOCKS_COMPACT_WIDTH_THRESHOLD = 120;
27 |
28 | /**
29 | * Default terminal width when stdout.columns is not available in blocks command
30 | * Used as fallback for responsive table formatting
31 | */
32 | export const BLOCKS_DEFAULT_TERMINAL_WIDTH = 120;
33 |
34 | /**
35 | * Threshold percentage for considering costs as matching (0.1% tolerance)
36 | * Used in debug cost validation to allow for minor calculation differences
37 | */
38 | export const DEBUG_MATCH_THRESHOLD_PERCENT = 0.1;
39 |
40 | /**
41 | * User's home directory path
42 | * Centralized access to OS home directory for consistent path building
43 | */
44 | export const USER_HOME_DIR = homedir();
45 |
46 | /**
47 | * XDG config directory path
48 | * Uses XDG_CONFIG_HOME if set, otherwise falls back to ~/.config
49 | */
50 | const XDG_CONFIG_DIR = xdgConfig ?? `${USER_HOME_DIR}/.config`;
51 |
52 | /**
53 | * Default Claude data directory path (~/.claude)
54 | * Used as base path for loading usage data from JSONL files
55 | */
56 | export const DEFAULT_CLAUDE_CODE_PATH = '.claude';
57 |
58 | /**
59 | * Default Claude data directory path using XDG config directory
60 | * Uses XDG_CONFIG_HOME if set, otherwise falls back to ~/.config/claude
61 | */
62 | export const DEFAULT_CLAUDE_CONFIG_PATH = `${XDG_CONFIG_DIR}/claude`;
63 |
64 | /**
65 | * Environment variable for specifying multiple Claude data directories
66 | * Supports comma-separated paths for multiple locations
67 | */
68 | export const CLAUDE_CONFIG_DIR_ENV = 'CLAUDE_CONFIG_DIR';
69 |
70 | /**
71 | * Environment variable for custom project name aliases
72 | *
73 | * Allows users to configure readable display names for cryptic or long project directory names.
74 | * This is particularly useful for:
75 | * - UUID-based project directories generated by Claude Code
76 | * - Long path-based project names that are hard to read in tables
77 | * - Custom branding of project names for organizational consistency
78 | *
79 | * Format: "raw-name=alias,another-name=other-alias"
80 | * Example: "a2cd99ed-a586-4fe4-8f59-b0026409ec09=My Project,long-project-name=Short"
81 | *
82 | * Environment variable approach is used because:
83 | * - No config file needed - simple and lightweight configuration
84 | * - Works in any shell/environment without file management
85 | * - Easy to set temporarily for specific invocations
86 | * - Follows Unix conventions for tool configuration
87 | * - Doesn't require file system permissions or config directory setup
88 | *
89 | * Used to override display names for project directories in all output formats.
90 | */
91 | export const PROJECT_ALIASES_ENV = 'CCUSAGE_PROJECT_ALIASES';
92 |
93 | /**
94 | * Claude projects directory name within the data directory
95 | * Contains subdirectories for each project with usage data
96 | */
97 | export const CLAUDE_PROJECTS_DIR_NAME = 'projects';
98 |
99 | /**
100 | * JSONL file glob pattern for finding usage data files
101 | * Used to recursively find all JSONL files in project directories
102 | */
103 | export const USAGE_DATA_GLOB_PATTERN = '**/*.jsonl';
104 |
105 | /**
106 | * Default port for MCP server HTTP transport
107 | * Used when no port is specified for MCP server communication
108 | */
109 | export const MCP_DEFAULT_PORT = 8080;
110 |
111 | /**
112 | * Default refresh interval in seconds for live monitoring mode
113 | * Used in blocks command for real-time updates
114 | */
115 | export const DEFAULT_REFRESH_INTERVAL_SECONDS = 1;
116 |
117 | /**
118 | * Minimum refresh interval in seconds for live monitoring mode
119 | * Prevents too-frequent updates that could impact performance
120 | */
121 | export const MIN_REFRESH_INTERVAL_SECONDS = 1;
122 |
123 | /**
124 | * Maximum refresh interval in seconds for live monitoring mode
125 | * Prevents too-slow updates that reduce monitoring effectiveness
126 | */
127 | export const MAX_REFRESH_INTERVAL_SECONDS = 60;
128 |
129 | /**
130 | * Frame rate limit for live monitoring (16ms = ~60fps)
131 | * Prevents terminal flickering and excessive CPU usage during rapid updates
132 | */
133 | export const MIN_RENDER_INTERVAL_MS = 16;
134 |
135 | /**
136 | * Burn rate thresholds for indicator display (tokens per minute)
137 | */
138 | export const BURN_RATE_THRESHOLDS = {
139 | HIGH: 1000,
140 | MODERATE: 500,
141 | } as const;
142 |
143 | /**
144 | * Days of the week for weekly aggregation
145 | */
146 | export const WEEK_DAYS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'] as const;
147 |
--------------------------------------------------------------------------------
/src/_daily-grouping.ts:
--------------------------------------------------------------------------------
1 | import type { DailyProjectOutput } from './_json-output-types.ts';
2 | import type { loadDailyUsageData } from './data-loader.ts';
3 | import { createDailyDate, createModelName } from './_types.ts';
4 | import { getTotalTokens } from './calculate-cost.ts';
5 |
6 | /**
7 | * Type for daily data returned from loadDailyUsageData
8 | */
9 | type DailyData = Awaited<ReturnType<typeof loadDailyUsageData>>;
10 |
11 | /**
12 | * Group daily usage data by project for JSON output
13 | */
14 | export function groupByProject(dailyData: DailyData): Record<string, DailyProjectOutput[]> {
15 | const projects: Record<string, DailyProjectOutput[]> = {};
16 |
17 | for (const data of dailyData) {
18 | const projectName = data.project ?? 'unknown';
19 |
20 | if (projects[projectName] == null) {
21 | projects[projectName] = [];
22 | }
23 |
24 | projects[projectName].push({
25 | date: data.date,
26 | inputTokens: data.inputTokens,
27 | outputTokens: data.outputTokens,
28 | cacheCreationTokens: data.cacheCreationTokens,
29 | cacheReadTokens: data.cacheReadTokens,
30 | totalTokens: getTotalTokens(data),
31 | totalCost: data.totalCost,
32 | modelsUsed: data.modelsUsed,
33 | modelBreakdowns: data.modelBreakdowns,
34 | });
35 | }
36 |
37 | return projects;
38 | }
39 |
40 | /**
41 | * Group daily usage data by project for table display
42 | */
43 | export function groupDataByProject(dailyData: DailyData): Record<string, DailyData> {
44 | const projects: Record<string, DailyData> = {};
45 |
46 | for (const data of dailyData) {
47 | const projectName = data.project ?? 'unknown';
48 |
49 | if (projects[projectName] == null) {
50 | projects[projectName] = [];
51 | }
52 |
53 | projects[projectName].push(data);
54 | }
55 |
56 | return projects;
57 | }
58 |
59 | if (import.meta.vitest != null) {
60 | describe('groupByProject', () => {
61 | it('groups daily data by project for JSON output', () => {
62 | const mockData = [
63 | {
64 | date: createDailyDate('2024-01-01'),
65 | project: 'project-a',
66 | inputTokens: 1000,
67 | outputTokens: 500,
68 | cacheCreationTokens: 100,
69 | cacheReadTokens: 200,
70 | totalCost: 0.01,
71 | modelsUsed: [createModelName('claude-sonnet-4-20250514')],
72 | modelBreakdowns: [],
73 | },
74 | {
75 | date: createDailyDate('2024-01-01'),
76 | project: 'project-b',
77 | inputTokens: 2000,
78 | outputTokens: 1000,
79 | cacheCreationTokens: 200,
80 | cacheReadTokens: 300,
81 | totalCost: 0.02,
82 | modelsUsed: [createModelName('claude-opus-4-20250514')],
83 | modelBreakdowns: [],
84 | },
85 | ];
86 |
87 | const result = groupByProject(mockData);
88 |
89 | expect(Object.keys(result)).toHaveLength(2);
90 | expect(result['project-a']).toHaveLength(1);
91 | expect(result['project-b']).toHaveLength(1);
92 | expect(result['project-a']![0]!.totalTokens).toBe(1800);
93 | expect(result['project-b']![0]!.totalTokens).toBe(3500);
94 | });
95 |
96 | it('handles unknown project names', () => {
97 | const mockData = [
98 | {
99 | date: createDailyDate('2024-01-01'),
100 | project: undefined,
101 | inputTokens: 1000,
102 | outputTokens: 500,
103 | cacheCreationTokens: 0,
104 | cacheReadTokens: 0,
105 | totalCost: 0.01,
106 | modelsUsed: [createModelName('claude-sonnet-4-20250514')],
107 | modelBreakdowns: [],
108 | },
109 | ];
110 |
111 | const result = groupByProject(mockData);
112 |
113 | expect(Object.keys(result)).toHaveLength(1);
114 | expect(result.unknown).toHaveLength(1);
115 | });
116 | });
117 |
118 | describe('groupDataByProject', () => {
119 | it('groups daily data by project for table display', () => {
120 | const mockData = [
121 | {
122 | date: createDailyDate('2024-01-01'),
123 | project: 'project-a',
124 | inputTokens: 1000,
125 | outputTokens: 500,
126 | cacheCreationTokens: 100,
127 | cacheReadTokens: 200,
128 | totalCost: 0.01,
129 | modelsUsed: [createModelName('claude-sonnet-4-20250514')],
130 | modelBreakdowns: [],
131 | },
132 | {
133 | date: createDailyDate('2024-01-02'),
134 | project: 'project-a',
135 | inputTokens: 800,
136 | outputTokens: 400,
137 | cacheCreationTokens: 50,
138 | cacheReadTokens: 150,
139 | totalCost: 0.008,
140 | modelsUsed: [createModelName('claude-sonnet-4-20250514')],
141 | modelBreakdowns: [],
142 | },
143 | ];
144 |
145 | const result = groupDataByProject(mockData);
146 |
147 | expect(Object.keys(result)).toHaveLength(1);
148 | expect(result['project-a']).toHaveLength(2);
149 | expect(result['project-a']).toEqual(mockData);
150 | });
151 | });
152 | }
153 |
--------------------------------------------------------------------------------
/src/_jq-processor.ts:
--------------------------------------------------------------------------------
1 | import { Result } from '@praha/byethrow';
2 | import spawn from 'nano-spawn';
3 |
4 | /**
5 | * Process JSON data with a jq command
6 | * @param jsonData - The JSON data to process
7 | * @param jqCommand - The jq command/filter to apply
8 | * @returns The processed output from jq
9 | */
10 | export async function processWithJq(jsonData: unknown, jqCommand: string): Result.ResultAsync<string, Error> {
11 | // Convert JSON data to string
12 | const jsonString = JSON.stringify(jsonData);
13 |
14 | // Use Result.try with object form to wrap spawn call
15 | const result = Result.try({
16 | try: async () => {
17 | const spawnResult = await spawn('jq', [jqCommand], {
18 | stdin: { string: jsonString },
19 | });
20 | return spawnResult.output.trim();
21 | },
22 | catch: (error: unknown) => {
23 | if (error instanceof Error) {
24 | // Check if jq is not installed
25 | if (error.message.includes('ENOENT') || error.message.includes('not found')) {
26 | return new Error('jq command not found. Please install jq to use the --jq option.');
27 | }
28 | // Return other errors (e.g., invalid jq syntax)
29 | return new Error(`jq processing failed: ${error.message}`);
30 | }
31 | return new Error('Unknown error during jq processing');
32 | },
33 | });
34 |
35 | return result();
36 | }
37 |
38 | // In-source tests
39 | if (import.meta.vitest != null) {
40 | describe('processWithJq', () => {
41 | it('should process JSON with simple filter', async () => {
42 | const data = { name: 'test', value: 42 };
43 | const result = await processWithJq(data, '.name');
44 | const unwrapped = Result.unwrap(result);
45 | expect(unwrapped).toBe('"test"');
46 | });
47 |
48 | it('should process JSON with complex filter', async () => {
49 | const data = {
50 | items: [
51 | { id: 1, name: 'apple' },
52 | { id: 2, name: 'banana' },
53 | ],
54 | };
55 | const result = await processWithJq(data, '.items | map(.name)');
56 | const unwrapped = Result.unwrap(result);
57 | const parsed = JSON.parse(unwrapped) as string[];
58 | expect(parsed).toEqual(['apple', 'banana']);
59 | });
60 |
61 | it('should handle raw output', async () => {
62 | const data = { message: 'hello world' };
63 | const result = await processWithJq(data, '.message | @text');
64 | const unwrapped = Result.unwrap(result);
65 | expect(unwrapped).toBe('"hello world"');
66 | });
67 |
68 | it('should return error for invalid jq syntax', async () => {
69 | const data = { test: 'value' };
70 | const result = await processWithJq(data, 'invalid syntax {');
71 | const error = Result.unwrapError(result);
72 | expect(error.message).toContain('jq processing failed');
73 | });
74 |
75 | it('should handle complex jq operations', async () => {
76 | const data = {
77 | users: [
78 | { name: 'Alice', age: 30 },
79 | { name: 'Bob', age: 25 },
80 | { name: 'Charlie', age: 35 },
81 | ],
82 | };
83 | const result = await processWithJq(data, '.users | sort_by(.age) | .[0].name');
84 | const unwrapped = Result.unwrap(result);
85 | expect(unwrapped).toBe('"Bob"');
86 | });
87 |
88 | it('should handle numeric output', async () => {
89 | const data = { values: [1, 2, 3, 4, 5] };
90 | const result = await processWithJq(data, '.values | add');
91 | const unwrapped = Result.unwrap(result);
92 | expect(unwrapped).toBe('15');
93 | });
94 | });
95 | }
96 |
--------------------------------------------------------------------------------
/src/_json-output-types.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * @fileoverview JSON output interface types for daily command groupByProject function
3 | *
4 | * This module provides TypeScript interfaces for the JSON output structure
5 | * used by the daily command's groupByProject function, replacing the
6 | * unsafe Record<string, any[]> type with proper type definitions.
7 | *
8 | * @module json-output-types
9 | */
10 |
11 | import type { DailyDate, ModelName } from './_types.ts';
12 | import type { ModelBreakdown } from './data-loader.ts';
13 |
14 | /**
15 | * Interface for daily command JSON output structure (groupByProject)
16 | * Used in src/commands/daily.ts
17 | */
18 | export type DailyProjectOutput = {
19 | date: DailyDate;
20 | inputTokens: number;
21 | outputTokens: number;
22 | cacheCreationTokens: number;
23 | cacheReadTokens: number;
24 | totalTokens: number;
25 | totalCost: number;
26 | modelsUsed: ModelName[];
27 | modelBreakdowns: ModelBreakdown[];
28 | };
29 |
--------------------------------------------------------------------------------
/src/_live-monitor.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * @fileoverview Live monitoring implementation for Claude usage data
3 | *
4 | * This module provides efficient incremental data loading for the live monitoring feature
5 | * in the blocks command. It tracks file modifications and only reads changed data,
6 | * maintaining a cache of processed entries to minimize file I/O during live updates.
7 | *
8 | * Used exclusively by blocks-live.ts for the --live flag functionality.
9 | */
10 |
11 | import type { LoadedUsageEntry, SessionBlock } from './_session-blocks.ts';
12 | import type { CostMode, SortOrder } from './_types.ts';
13 | import { readFile } from 'node:fs/promises';
14 | import { identifySessionBlocks } from './_session-blocks.ts';
15 | import {
16 | calculateCostForEntry,
17 | createUniqueHash,
18 | getEarliestTimestamp,
19 | getUsageLimitResetTime,
20 | globUsageFiles,
21 | sortFilesByTimestamp,
22 | usageDataSchema,
23 | } from './data-loader.ts';
24 | import { PricingFetcher } from './pricing-fetcher.ts';
25 |
26 | /**
27 | * Configuration for live monitoring
28 | */
29 | export type LiveMonitorConfig = {
30 | claudePaths: string[];
31 | sessionDurationHours: number;
32 | mode: CostMode;
33 | order: SortOrder;
34 | };
35 |
36 | /**
37 | * Manages live monitoring of Claude usage with efficient data reloading
38 | */
39 | export class LiveMonitor implements Disposable {
40 | private config: LiveMonitorConfig;
41 | private fetcher: PricingFetcher | null = null;
42 | private lastFileTimestamps = new Map<string, number>();
43 | private processedHashes = new Set<string>();
44 | private allEntries: LoadedUsageEntry[] = [];
45 |
46 | constructor(config: LiveMonitorConfig) {
47 | this.config = config;
48 | // Initialize pricing fetcher once if needed
49 | if (config.mode !== 'display') {
50 | this.fetcher = new PricingFetcher();
51 | }
52 | }
53 |
54 | /**
55 | * Implements Disposable interface
56 | */
57 | [Symbol.dispose](): void {
58 | this.fetcher?.[Symbol.dispose]();
59 | }
60 |
61 | /**
62 | * Gets the current active session block with minimal file reading
63 | * Only reads new or modified files since last check
64 | */
65 | async getActiveBlock(): Promise<SessionBlock | null> {
66 | const results = await globUsageFiles(this.config.claudePaths);
67 | const allFiles = results.map(r => r.file);
68 |
69 | if (allFiles.length === 0) {
70 | return null;
71 | }
72 |
73 | // Check for new or modified files
74 | const filesToRead: string[] = [];
75 | for (const file of allFiles) {
76 | const timestamp = await getEarliestTimestamp(file);
77 | const lastTimestamp = this.lastFileTimestamps.get(file);
78 |
79 | if (timestamp != null && (lastTimestamp == null || timestamp.getTime() > lastTimestamp)) {
80 | filesToRead.push(file);
81 | this.lastFileTimestamps.set(file, timestamp.getTime());
82 | }
83 | }
84 |
85 | // Read only new/modified files
86 | if (filesToRead.length > 0) {
87 | const sortedFiles = await sortFilesByTimestamp(filesToRead);
88 |
89 | for (const file of sortedFiles) {
90 | const content = await readFile(file, 'utf-8')
91 | .catch(() => {
92 | // Skip files that can't be read
93 | return '';
94 | });
95 |
96 | const lines = content
97 | .trim()
98 | .split('\n')
99 | .filter(line => line.length > 0);
100 |
101 | for (const line of lines) {
102 | try {
103 | const parsed = JSON.parse(line) as unknown;
104 | const result = usageDataSchema.safeParse(parsed);
105 | if (!result.success) {
106 | continue;
107 | }
108 | const data = result.data;
109 |
110 | // Check for duplicates
111 | const uniqueHash = createUniqueHash(data);
112 | if (uniqueHash != null && this.processedHashes.has(uniqueHash)) {
113 | continue;
114 | }
115 | if (uniqueHash != null) {
116 | this.processedHashes.add(uniqueHash);
117 | }
118 |
119 | // Calculate cost if needed
120 | const costUSD: number = await (this.config.mode === 'display'
121 | ? Promise.resolve(data.costUSD ?? 0)
122 | : calculateCostForEntry(
123 | data,
124 | this.config.mode,
125 | this.fetcher!,
126 | ));
127 |
128 | const usageLimitResetTime = getUsageLimitResetTime(data);
129 |
130 | // Add entry
131 | this.allEntries.push({
132 | timestamp: new Date(data.timestamp),
133 | usage: {
134 | inputTokens: data.message.usage.input_tokens ?? 0,
135 | outputTokens: data.message.usage.output_tokens ?? 0,
136 | cacheCreationInputTokens: data.message.usage.cache_creation_input_tokens ?? 0,
137 | cacheReadInputTokens: data.message.usage.cache_read_input_tokens ?? 0,
138 | },
139 | costUSD,
140 | model: data.message.model ?? '<synthetic>',
141 | version: data.version,
142 | usageLimitResetTime: usageLimitResetTime ?? undefined,
143 | });
144 | }
145 | catch {
146 | // Skip malformed lines
147 | }
148 | }
149 | }
150 | }
151 |
152 | // Generate blocks and find active one
153 | const blocks = identifySessionBlocks(
154 | this.allEntries,
155 | this.config.sessionDurationHours,
156 | );
157 |
158 | // Sort blocks
159 | const sortedBlocks = this.config.order === 'asc'
160 | ? blocks
161 | : blocks.reverse();
162 |
163 | // Find active block
164 | return sortedBlocks.find(block => block.isActive) ?? null;
165 | }
166 |
167 | /**
168 | * Clears all cached data to force a full reload
169 | */
170 | clearCache(): void {
171 | this.lastFileTimestamps.clear();
172 | this.processedHashes.clear();
173 | this.allEntries = [];
174 | }
175 | }
176 |
177 | if (import.meta.vitest != null) {
178 | describe('LiveMonitor', () => {
179 | let tempDir: string;
180 | let monitor: LiveMonitor;
181 |
182 | beforeEach(async () => {
183 | const { createFixture } = await import('fs-fixture');
184 | const now = new Date();
185 | const recentTimestamp = new Date(now.getTime() - 60 * 60 * 1000); // 1 hour ago
186 |
187 | const fixture = await createFixture({
188 | 'projects/test-project/session1/usage.jsonl': `${JSON.stringify({
189 | timestamp: recentTimestamp.toISOString(),
190 | message: {
191 | model: 'claude-sonnet-4-20250514',
192 | usage: {
193 | input_tokens: 100,
194 | output_tokens: 50,
195 | cache_creation_input_tokens: 0,
196 | cache_read_input_tokens: 0,
197 | },
198 | },
199 | costUSD: 0.01,
200 | version: '1.0.0',
201 | })}\n`,
202 | });
203 | tempDir = fixture.path;
204 |
205 | monitor = new LiveMonitor({
206 | claudePaths: [tempDir],
207 | sessionDurationHours: 5,
208 | mode: 'display',
209 | order: 'desc',
210 | });
211 | });
212 |
213 | afterEach(() => {
214 | monitor[Symbol.dispose]();
215 | });
216 |
217 | it('should initialize and handle clearing cache', async () => {
218 | // Test initial state by calling getActiveBlock which should work
219 | const initialBlock = await monitor.getActiveBlock();
220 | expect(initialBlock).not.toBeNull();
221 |
222 | // Clear cache and test again
223 | monitor.clearCache();
224 | const afterClearBlock = await monitor.getActiveBlock();
225 | expect(afterClearBlock).not.toBeNull();
226 | });
227 |
228 | it('should load and process usage data', async () => {
229 | const activeBlock = await monitor.getActiveBlock();
230 |
231 | expect(activeBlock).not.toBeNull();
232 | if (activeBlock != null) {
233 | expect(activeBlock.tokenCounts.inputTokens).toBe(100);
234 | expect(activeBlock.tokenCounts.outputTokens).toBe(50);
235 | expect(activeBlock.costUSD).toBe(0.01);
236 | expect(activeBlock.models).toContain('claude-sonnet-4-20250514');
237 | }
238 | });
239 |
240 | it('should handle empty directories', async () => {
241 | const { createFixture } = await import('fs-fixture');
242 | const emptyFixture = await createFixture({});
243 |
244 | const emptyMonitor = new LiveMonitor({
245 | claudePaths: [emptyFixture.path],
246 | sessionDurationHours: 5,
247 | mode: 'display',
248 | order: 'desc',
249 | });
250 |
251 | const activeBlock = await emptyMonitor.getActiveBlock();
252 | expect(activeBlock).toBeNull();
253 |
254 | emptyMonitor[Symbol.dispose]();
255 | });
256 | });
257 | }
258 |
--------------------------------------------------------------------------------
/src/_macro.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * Prefetch claude data for the current user.
3 | */
4 |
5 | import type { ModelPricing } from './_types.ts';
6 | import { LITELLM_PRICING_URL } from './_consts.ts';
7 | import { modelPricingSchema } from './_types.ts';
8 |
9 | /**
10 | * Prefetches the pricing data for Claude models from the LiteLLM API.
11 | * This function fetches the pricing data and filters out models that start with 'claude-'.
12 | * It returns a record of model names to their pricing information.
13 | *
14 | * @returns A promise that resolves to a record of model names and their pricing information.
15 | * @throws Will throw an error if the fetch operation fails.
16 | */
17 | export async function prefetchClaudePricing(): Promise<Record<string, ModelPricing>> {
18 | const response = await fetch(LITELLM_PRICING_URL);
19 | if (!response.ok) {
20 | throw new Error(`Failed to fetch pricing data: ${response.statusText}`);
21 | }
22 |
23 | const data = await response.json() as Record<string, unknown>;
24 |
25 | const prefetchClaudeData: Record<string, ModelPricing> = {};
26 |
27 | // Cache all models that start with 'claude-'
28 | for (const [modelName, modelData] of Object.entries(data)) {
29 | if (modelName.startsWith('claude-') && modelData != null && typeof modelData === 'object') {
30 | const parsed = modelPricingSchema.safeParse(modelData);
31 | if (parsed.success) {
32 | prefetchClaudeData[modelName] = parsed.data;
33 | }
34 | }
35 | }
36 |
37 | return prefetchClaudeData;
38 | }
39 |
--------------------------------------------------------------------------------
/src/_project-names.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * @fileoverview Project name formatting and alias utilities
3 | *
4 | * Provides utilities for formatting raw project directory names into user-friendly
5 | * display names with support for custom aliases and improved path parsing.
6 | *
7 | * @module project-names
8 | */
9 |
10 | import process from 'node:process';
11 | import { PROJECT_ALIASES_ENV } from './_consts.ts';
12 |
13 | /**
14 | * Cache for parsed aliases to avoid repeated parsing
15 | */
16 | let aliasCache: Map<string, string> | null = null;
17 |
18 | /**
19 | * Parse project aliases from environment variable
20 | * @returns Map of raw project names to their aliases
21 | */
22 | function getProjectAliases(): Map<string, string> {
23 | if (aliasCache !== null) {
24 | return aliasCache;
25 | }
26 |
27 | aliasCache = new Map();
28 |
29 | const aliasEnv = (process.env[PROJECT_ALIASES_ENV] ?? '').trim();
30 | if (aliasEnv === '') {
31 | return aliasCache;
32 | }
33 |
34 | // Parse comma-separated name=alias pairs
35 | const pairs = aliasEnv.split(',').map(pair => pair.trim()).filter(pair => pair !== '');
36 | for (const pair of pairs) {
37 | const parts = pair.split('=').map(s => s.trim());
38 | const rawName = parts[0];
39 | const alias = parts[1];
40 | if (rawName != null && alias != null && rawName !== '' && alias !== '') {
41 | aliasCache.set(rawName, alias);
42 | }
43 | }
44 |
45 | return aliasCache;
46 | }
47 |
48 | /**
49 | * Clear the alias cache (useful for testing)
50 | * @internal
51 | */
52 | export function clearAliasCache(): void {
53 | aliasCache = null;
54 | }
55 |
56 | /**
57 | * Extract meaningful project name from directory-style project paths
58 | * Uses improved heuristics to handle complex project structures
59 | *
60 | * @param projectName - Raw project name from directory path
61 | * @returns Cleaned and formatted project name
62 | *
63 | * @example
64 | * ```typescript
65 | * // Basic cleanup
66 | * parseProjectName('-Users-phaedrus-Development-ccusage')
67 | * // → 'ccusage'
68 | *
69 | * // Complex project with feature branch
70 | * parseProjectName('-Users-phaedrus-Development-adminifi-edugakko-api--feature-ticket-002-configure-dependabot')
71 | * // → 'configure-dependabot'
72 | *
73 | * // Handle unknown projects
74 | * parseProjectName('unknown')
75 | * // → 'Unknown Project'
76 | * ```
77 | */
78 | function parseProjectName(projectName: string): string {
79 | if (projectName === 'unknown' || projectName === '') {
80 | return 'Unknown Project';
81 | }
82 |
83 | // Remove common directory prefixes
84 | let cleaned = projectName;
85 |
86 | // Handle Windows-style paths: C:\Users\... or \Users\...
87 | if (cleaned.match(/^[A-Z]:\\Users\\|^\\Users\\/) != null) {
88 | const segments = cleaned.split('\\');
89 | const userIndex = segments.findIndex(seg => seg === 'Users');
90 | if (userIndex !== -1 && userIndex + 3 < segments.length) {
91 | // Take everything after Users/username/Projects or similar
92 | cleaned = segments.slice(userIndex + 3).join('-');
93 | }
94 | }
95 |
96 | // Handle Unix-style paths: /Users/... or -Users-...
97 | if (cleaned.startsWith('-Users-') || cleaned.startsWith('/Users/')) {
98 | const separator = cleaned.startsWith('-Users-') ? '-' : '/';
99 | const segments = cleaned.split(separator).filter(s => s.length > 0);
100 | const userIndex = segments.findIndex(seg => seg === 'Users');
101 |
102 | if (userIndex !== -1 && userIndex + 3 < segments.length) {
103 | // Take everything after Users/username/Development or similar
104 | cleaned = segments.slice(userIndex + 3).join('-');
105 | }
106 | }
107 |
108 | // If no path cleanup occurred, use original name
109 | if (cleaned === projectName) {
110 | // Just basic cleanup for non-path names
111 | cleaned = projectName.replace(/^[/\\-]+|[/\\-]+$/g, '');
112 | }
113 |
114 | // Handle UUID-like patterns
115 | if (cleaned.match(/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}/i) != null) {
116 | // Extract last two segments of UUID for brevity
117 | const parts = cleaned.split('-');
118 | if (parts.length >= 5) {
119 | // Take the last two segments, which may include file extension in the last segment
120 | cleaned = parts.slice(-2).join('-');
121 | }
122 | }
123 |
124 | // Improved project name extraction for complex names
125 | if (cleaned.includes('--')) {
126 | // Handle project--feature patterns like "adminifi-edugakko-api--feature-ticket-002"
127 | const parts = cleaned.split('--');
128 | if (parts.length >= 2 && parts[0] != null) {
129 | // Take the main project part before the first --
130 | cleaned = parts[0];
131 | }
132 | }
133 |
134 | // For compound project names, try to extract the most meaningful part
135 | if (cleaned.includes('-') && cleaned.length > 20) {
136 | const segments = cleaned.split('-');
137 |
138 | // Look for common meaningful patterns
139 | const meaningfulSegments = segments.filter(seg =>
140 | seg.length > 2
141 | && seg.match(/^(?:dev|development|feat|feature|fix|bug|test|staging|prod|production|main|master|branch)$/i) == null,
142 | );
143 |
144 | // If we have compound project names like "adminifi-edugakko-api"
145 | // Try to find the last 2-3 meaningful segments
146 | if (meaningfulSegments.length >= 2) {
147 | // Take last 2-3 segments to get "edugakko-api" from "adminifi-edugakko-api"
148 | const lastSegments = meaningfulSegments.slice(-2);
149 | if (lastSegments.join('-').length >= 6) {
150 | cleaned = lastSegments.join('-');
151 | }
152 | else if (meaningfulSegments.length >= 3) {
153 | cleaned = meaningfulSegments.slice(-3).join('-');
154 | }
155 | }
156 | }
157 |
158 | // Final cleanup
159 | cleaned = cleaned.replace(/^[/\\-]+|[/\\-]+$/g, '');
160 |
161 | return cleaned !== '' ? cleaned : (projectName !== '' ? projectName : 'Unknown Project');
162 | }
163 |
164 | /**
165 | * Format project name for display with custom alias support
166 | *
167 | * @param projectName - Raw project name from directory path
168 | * @returns User-friendly project name with alias support
169 | *
170 | * @example
171 | * ```typescript
172 | * // Without aliases
173 | * formatProjectName('-Users-phaedrus-Development-ccusage')
174 | * // → 'ccusage'
175 | *
176 | * // With alias (when CCUSAGE_PROJECT_ALIASES="ccusage=Usage Tracker")
177 | * formatProjectName('-Users-phaedrus-Development-ccusage')
178 | * // → 'Usage Tracker'
179 | * ```
180 | */
181 | export function formatProjectName(projectName: string): string {
182 | // Check for custom alias first
183 | const aliases = getProjectAliases();
184 | if (aliases.has(projectName)) {
185 | return aliases.get(projectName)!;
186 | }
187 |
188 | // Parse the project name using improved logic
189 | const parsed = parseProjectName(projectName);
190 |
191 | // Check if parsed name has an alias
192 | if (aliases.has(parsed)) {
193 | return aliases.get(parsed)!;
194 | }
195 |
196 | return parsed;
197 | }
198 |
199 | /**
200 | * Get all configured project aliases
201 | * @returns Map of project names to their aliases
202 | */
203 | export function getConfiguredAliases(): Map<string, string> {
204 | return new Map(getProjectAliases());
205 | }
206 |
207 | if (import.meta.vitest != null) {
208 | const { describe, it, expect, beforeEach } = import.meta.vitest;
209 |
210 | describe('project name formatting', () => {
211 | beforeEach(() => {
212 | clearAliasCache();
213 | delete (process.env as Record<string, string | undefined>)[PROJECT_ALIASES_ENV];
214 | });
215 |
216 | describe('parseProjectName', () => {
217 | it('handles unknown project names', () => {
218 | expect(formatProjectName('unknown')).toBe('Unknown Project');
219 | expect(formatProjectName('')).toBe('Unknown Project');
220 | });
221 |
222 | it('extracts project names from Unix-style paths', () => {
223 | expect(formatProjectName('-Users-phaedrus-Development-ccusage')).toBe('ccusage');
224 | expect(formatProjectName('/Users/phaedrus/Development/ccusage')).toBe('ccusage');
225 | });
226 |
227 | it('handles complex project names with features', () => {
228 | const complexName = '-Users-phaedrus-Development-adminifi-edugakko-api--feature-ticket-002-configure-dependabot';
229 | const result = formatProjectName(complexName);
230 | // Current logic processes the name and extracts meaningful segments
231 | expect(result).toBe('configure-dependabot');
232 | });
233 |
234 | it('handles UUID-based project names', () => {
235 | const uuidName = 'a2cd99ed-a586-4fe4-8f59-b0026409ec09.jsonl';
236 | const result = formatProjectName(uuidName);
237 | expect(result).toBe('8f59-b0026409ec09.jsonl');
238 | });
239 |
240 | it('returns original name for simple names', () => {
241 | expect(formatProjectName('simple-project')).toBe('simple-project');
242 | expect(formatProjectName('project')).toBe('project');
243 | });
244 | });
245 |
246 | describe('custom aliases', () => {
247 | it('uses configured aliases', () => {
248 | (process.env as Record<string, string | undefined>)[PROJECT_ALIASES_ENV] = 'ccusage=Usage Tracker,test=Test Project';
249 |
250 | expect(formatProjectName('ccusage')).toBe('Usage Tracker');
251 | expect(formatProjectName('test')).toBe('Test Project');
252 | expect(formatProjectName('other')).toBe('other');
253 | });
254 |
255 | it('applies aliases to parsed project names', () => {
256 | (process.env as Record<string, string | undefined>)[PROJECT_ALIASES_ENV] = 'ccusage=Usage Tracker';
257 |
258 | expect(formatProjectName('-Users-phaedrus-Development-ccusage')).toBe('Usage Tracker');
259 | });
260 |
261 | it('handles malformed alias configuration gracefully', () => {
262 | (process.env as Record<string, string | undefined>)[PROJECT_ALIASES_ENV] = 'invalid,=empty,valid=good';
263 |
264 | expect(formatProjectName('valid')).toBe('good');
265 | expect(formatProjectName('invalid')).toBe('invalid');
266 | });
267 |
268 | it('caches aliases for performance', () => {
269 | (process.env as Record<string, string | undefined>)[PROJECT_ALIASES_ENV] = 'test=cached';
270 |
271 | expect(formatProjectName('test')).toBe('cached');
272 |
273 | // Change env var but cache should still be used
274 | (process.env as Record<string, string | undefined>)[PROJECT_ALIASES_ENV] = 'test=changed';
275 | expect(formatProjectName('test')).toBe('cached');
276 |
277 | // Clear cache and test again
278 | clearAliasCache();
279 | expect(formatProjectName('test')).toBe('changed');
280 | });
281 | });
282 |
283 | describe('getConfiguredAliases', () => {
284 | it('returns configured aliases', () => {
285 | (process.env as Record<string, string | undefined>)[PROJECT_ALIASES_ENV] = 'proj1=Project One,proj2=Project Two';
286 |
287 | const aliases = getConfiguredAliases();
288 | expect(aliases.get('proj1')).toBe('Project One');
289 | expect(aliases.get('proj2')).toBe('Project Two');
290 | expect(aliases.size).toBe(2);
291 | });
292 |
293 | it('returns empty map when no aliases configured', () => {
294 | const aliases = getConfiguredAliases();
295 | expect(aliases.size).toBe(0);
296 | });
297 | });
298 | });
299 | }
300 |
--------------------------------------------------------------------------------
/src/_shared-args.ts:
--------------------------------------------------------------------------------
1 | import type { Args } from 'gunshi';
2 | import type { CostMode, SortOrder } from './_types.ts';
3 | import { CostModes, filterDateSchema, SortOrders } from './_types.ts';
4 |
5 | /**
6 | * Parses and validates a date argument in YYYYMMDD format
7 | * @param value - Date string to parse
8 | * @returns Validated date string
9 | * @throws TypeError if date format is invalid
10 | */
11 | function parseDateArg(value: string): string {
12 | const result = filterDateSchema.safeParse(value);
13 | if (!result.success) {
14 | throw new TypeError(result.error.issues[0]?.message ?? 'Invalid date format');
15 | }
16 | return result.data;
17 | }
18 |
19 | /**
20 | * Shared command line arguments used across multiple CLI commands
21 | */
22 | export const sharedArgs = {
23 | since: {
24 | type: 'custom',
25 | short: 's',
26 | description: 'Filter from date (YYYYMMDD format)',
27 | parse: parseDateArg,
28 | },
29 | until: {
30 | type: 'custom',
31 | short: 'u',
32 | description: 'Filter until date (YYYYMMDD format)',
33 | parse: parseDateArg,
34 | },
35 | json: {
36 | type: 'boolean',
37 | short: 'j',
38 | description: 'Output in JSON format',
39 | default: false,
40 | },
41 | mode: {
42 | type: 'enum',
43 | short: 'm',
44 | description:
45 | 'Cost calculation mode: auto (use costUSD if exists, otherwise calculate), calculate (always calculate), display (always use costUSD)',
46 | default: 'auto' as const satisfies CostMode,
47 | choices: CostModes,
48 | },
49 | debug: {
50 | type: 'boolean',
51 | short: 'd',
52 | description: 'Show pricing mismatch information for debugging',
53 | default: false,
54 | },
55 | debugSamples: {
56 | type: 'number',
57 | description:
58 | 'Number of sample discrepancies to show in debug output (default: 5)',
59 | default: 5,
60 | },
61 | order: {
62 | type: 'enum',
63 | short: 'o',
64 | description: 'Sort order: desc (newest first) or asc (oldest first)',
65 | default: 'asc' as const satisfies SortOrder,
66 | choices: SortOrders,
67 | },
68 | breakdown: {
69 | type: 'boolean',
70 | short: 'b',
71 | description: 'Show per-model cost breakdown',
72 | default: false,
73 | },
74 | offline: {
75 | type: 'boolean',
76 | negatable: true,
77 | short: 'O',
78 | description: 'Use cached pricing data for Claude models instead of fetching from API',
79 | default: false,
80 | },
81 | color: { // --color and FORCE_COLOR=1 is handled by picocolors
82 | type: 'boolean',
83 | description: 'Enable colored output (default: auto). FORCE_COLOR=1 has the same effect.',
84 | },
85 | noColor: { // --no-color and NO_COLOR=1 is handled by picocolors
86 | type: 'boolean',
87 | description: 'Disable colored output (default: auto). NO_COLOR=1 has the same effect.',
88 | },
89 | timezone: {
90 | type: 'string',
91 | short: 'z',
92 | description: 'Timezone for date grouping (e.g., UTC, America/New_York, Asia/Tokyo). Default: system timezone',
93 | },
94 | locale: {
95 | type: 'string',
96 | short: 'l',
97 | description: 'Locale for date/time formatting (e.g., en-US, ja-JP, de-DE)',
98 | default: 'en-CA',
99 | },
100 | jq: {
101 | type: 'string',
102 | short: 'q',
103 | description: 'Process JSON output with jq command (requires jq binary, implies --json)',
104 | },
105 | } as const satisfies Args;
106 |
107 | /**
108 | * Shared command configuration for Gunshi CLI commands
109 | */
110 | export const sharedCommandConfig = {
111 | args: sharedArgs,
112 | toKebab: true,
113 | } as const;
114 |
--------------------------------------------------------------------------------
/src/_token-utils.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * @fileoverview Token calculation utilities
3 | *
4 | * This module provides shared utilities for calculating token totals
5 | * across different token types. Used throughout the application to
6 | * ensure consistent token counting logic.
7 | */
8 |
9 | /**
10 | * Token counts structure for raw usage data (uses InputTokens suffix)
11 | */
12 | export type TokenCounts = {
13 | inputTokens: number;
14 | outputTokens: number;
15 | cacheCreationInputTokens: number;
16 | cacheReadInputTokens: number;
17 | };
18 |
19 | /**
20 | * Token counts structure for aggregated data (uses shorter names)
21 | */
22 | export type AggregatedTokenCounts = {
23 | inputTokens: number;
24 | outputTokens: number;
25 | cacheCreationTokens: number;
26 | cacheReadTokens: number;
27 | };
28 |
29 | /**
30 | * Union type that supports both token count formats
31 | */
32 | export type AnyTokenCounts = TokenCounts | AggregatedTokenCounts;
33 |
34 | /**
35 | * Calculates the total number of tokens across all token types
36 | * Supports both raw usage data format and aggregated data format
37 | * @param tokenCounts - Object containing counts for each token type
38 | * @returns Total number of tokens
39 | */
40 | export function getTotalTokens(tokenCounts: AnyTokenCounts): number {
41 | // Support both property naming conventions
42 | const cacheCreation = 'cacheCreationInputTokens' in tokenCounts
43 | ? tokenCounts.cacheCreationInputTokens
44 | : (tokenCounts).cacheCreationTokens;
45 |
46 | const cacheRead = 'cacheReadInputTokens' in tokenCounts
47 | ? tokenCounts.cacheReadInputTokens
48 | : (tokenCounts).cacheReadTokens;
49 |
50 | return (
51 | tokenCounts.inputTokens
52 | + tokenCounts.outputTokens
53 | + cacheCreation
54 | + cacheRead
55 | );
56 | }
57 |
58 | // In-source testing
59 | if (import.meta.vitest != null) {
60 | describe('getTotalTokens', () => {
61 | it('should sum all token types correctly (raw format)', () => {
62 | const tokens: TokenCounts = {
63 | inputTokens: 1000,
64 | outputTokens: 500,
65 | cacheCreationInputTokens: 2000,
66 | cacheReadInputTokens: 300,
67 | };
68 | expect(getTotalTokens(tokens)).toBe(3800);
69 | });
70 |
71 | it('should sum all token types correctly (aggregated format)', () => {
72 | const tokens: AggregatedTokenCounts = {
73 | inputTokens: 1000,
74 | outputTokens: 500,
75 | cacheCreationTokens: 2000,
76 | cacheReadTokens: 300,
77 | };
78 | expect(getTotalTokens(tokens)).toBe(3800);
79 | });
80 |
81 | it('should handle zero values (raw format)', () => {
82 | const tokens: TokenCounts = {
83 | inputTokens: 0,
84 | outputTokens: 0,
85 | cacheCreationInputTokens: 0,
86 | cacheReadInputTokens: 0,
87 | };
88 | expect(getTotalTokens(tokens)).toBe(0);
89 | });
90 |
91 | it('should handle zero values (aggregated format)', () => {
92 | const tokens: AggregatedTokenCounts = {
93 | inputTokens: 0,
94 | outputTokens: 0,
95 | cacheCreationTokens: 0,
96 | cacheReadTokens: 0,
97 | };
98 | expect(getTotalTokens(tokens)).toBe(0);
99 | });
100 |
101 | it('should handle missing cache tokens (raw format)', () => {
102 | const tokens: TokenCounts = {
103 | inputTokens: 1000,
104 | outputTokens: 500,
105 | cacheCreationInputTokens: 0,
106 | cacheReadInputTokens: 0,
107 | };
108 | expect(getTotalTokens(tokens)).toBe(1500);
109 | });
110 |
111 | it('should handle missing cache tokens (aggregated format)', () => {
112 | const tokens: AggregatedTokenCounts = {
113 | inputTokens: 1000,
114 | outputTokens: 500,
115 | cacheCreationTokens: 0,
116 | cacheReadTokens: 0,
117 | };
118 | expect(getTotalTokens(tokens)).toBe(1500);
119 | });
120 | });
121 | }
122 |
--------------------------------------------------------------------------------
/src/_types.ts:
--------------------------------------------------------------------------------
1 | import type { TupleToUnion } from 'type-fest';
2 | import { z } from 'zod';
3 |
4 | /**
5 | * Branded Zod schemas for type safety using Zod's built-in brand functionality
6 | */
7 |
8 | // Core identifier schemas
9 | export const modelNameSchema = z.string()
10 | .min(1, 'Model name cannot be empty')
11 | .brand<'ModelName'>();
12 |
13 | export const sessionIdSchema = z.string()
14 | .min(1, 'Session ID cannot be empty')
15 | .brand<'SessionId'>();
16 |
17 | export const requestIdSchema = z.string()
18 | .min(1, 'Request ID cannot be empty')
19 | .brand<'RequestId'>();
20 |
21 | export const messageIdSchema = z.string()
22 | .min(1, 'Message ID cannot be empty')
23 | .brand<'MessageId'>();
24 |
25 | // Date and timestamp schemas
26 | export const isoTimestampSchema = z.string()
27 | .regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/, 'Invalid ISO timestamp')
28 | .brand<'ISOTimestamp'>();
29 |
30 | export const dailyDateSchema = z.string()
31 | .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in YYYY-MM-DD format')
32 | .brand<'DailyDate'>();
33 |
34 | export const activityDateSchema = z.string()
35 | .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in YYYY-MM-DD format')
36 | .brand<'ActivityDate'>();
37 |
38 | export const monthlyDateSchema = z.string()
39 | .regex(/^\d{4}-\d{2}$/, 'Date must be in YYYY-MM format')
40 | .brand<'MonthlyDate'>();
41 |
42 | export const weeklyDateSchema = z
43 | .string()
44 | .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in YYYY-MM-DD format')
45 | .brand<'WeeklyDate'>();
46 |
47 | export const filterDateSchema = z.string()
48 | .regex(/^\d{8}$/, 'Date must be in YYYYMMDD format')
49 | .brand<'FilterDate'>();
50 |
51 | // Other domain-specific schemas
52 | export const projectPathSchema = z.string()
53 | .min(1, 'Project path cannot be empty')
54 | .brand<'ProjectPath'>();
55 |
56 | export const versionSchema = z.string()
57 | .regex(/^\d+\.\d+\.\d+/, 'Invalid version format')
58 | .brand<'Version'>();
59 |
60 | /**
61 | * Inferred branded types from schemas
62 | */
63 | export type ModelName = z.infer<typeof modelNameSchema>;
64 | export type SessionId = z.infer<typeof sessionIdSchema>;
65 | export type RequestId = z.infer<typeof requestIdSchema>;
66 | export type MessageId = z.infer<typeof messageIdSchema>;
67 | export type ISOTimestamp = z.infer<typeof isoTimestampSchema>;
68 | export type DailyDate = z.infer<typeof dailyDateSchema>;
69 | export type ActivityDate = z.infer<typeof activityDateSchema>;
70 | export type MonthlyDate = z.infer<typeof monthlyDateSchema>;
71 | export type WeeklyDate = z.infer<typeof weeklyDateSchema>;
72 | export type Bucket = MonthlyDate | WeeklyDate;
73 | export type FilterDate = z.infer<typeof filterDateSchema>;
74 | export type ProjectPath = z.infer<typeof projectPathSchema>;
75 | export type Version = z.infer<typeof versionSchema>;
76 |
77 | /**
78 | * Helper functions to create branded values by parsing and validating input strings
79 | * These functions should be used when converting plain strings to branded types
80 | */
81 | export const createModelName = (value: string): ModelName => modelNameSchema.parse(value);
82 | export const createSessionId = (value: string): SessionId => sessionIdSchema.parse(value);
83 | export const createRequestId = (value: string): RequestId => requestIdSchema.parse(value);
84 | export const createMessageId = (value: string): MessageId => messageIdSchema.parse(value);
85 | export const createISOTimestamp = (value: string): ISOTimestamp => isoTimestampSchema.parse(value);
86 | export const createDailyDate = (value: string): DailyDate => dailyDateSchema.parse(value);
87 | export const createActivityDate = (value: string): ActivityDate => activityDateSchema.parse(value);
88 | export const createMonthlyDate = (value: string): MonthlyDate => monthlyDateSchema.parse(value);
89 | export const createWeeklyDate = (value: string): WeeklyDate => weeklyDateSchema.parse(value);
90 | export const createFilterDate = (value: string): FilterDate => filterDateSchema.parse(value);
91 | export const createProjectPath = (value: string): ProjectPath => projectPathSchema.parse(value);
92 | export const createVersion = (value: string): Version => versionSchema.parse(value);
93 |
94 | export function createBucket(value: string): Bucket {
95 | if (weeklyDateSchema.safeParse(value).success) {
96 | return createWeeklyDate(value);
97 | }
98 | return createMonthlyDate(value);
99 | };
100 |
101 | /**
102 | * Available cost calculation modes
103 | * - auto: Use pre-calculated costs when available, otherwise calculate from tokens
104 | * - calculate: Always calculate costs from token counts using model pricing
105 | * - display: Always use pre-calculated costs, show 0 for missing costs
106 | */
107 | export const CostModes = ['auto', 'calculate', 'display'] as const;
108 |
109 | /**
110 | * Union type for cost calculation modes
111 | */
112 | export type CostMode = TupleToUnion<typeof CostModes>;
113 |
114 | /**
115 | * Available sort orders for data presentation
116 | */
117 | export const SortOrders = ['desc', 'asc'] as const;
118 |
119 | /**
120 | * Union type for sort order options
121 | */
122 | export type SortOrder = TupleToUnion<typeof SortOrders>;
123 |
124 | /**
125 | * Zod schema for model pricing information from LiteLLM
126 | */
127 | export const modelPricingSchema = z.object({
128 | input_cost_per_token: z.number().optional(),
129 | output_cost_per_token: z.number().optional(),
130 | cache_creation_input_token_cost: z.number().optional(),
131 | cache_read_input_token_cost: z.number().optional(),
132 | });
133 |
134 | /**
135 | * Type definition for model pricing information
136 | */
137 | export type ModelPricing = z.infer<typeof modelPricingSchema>;
138 |
139 | /**
140 | * Zod schema for Claude Code statusline hook JSON data
141 | */
142 | export const statuslineHookJsonSchema = z.object({
143 | session_id: z.string(),
144 | transcript_path: z.string(),
145 | cwd: z.string(),
146 | model: z.object({
147 | id: z.string(),
148 | display_name: z.string(),
149 | }),
150 | workspace: z.object({
151 | current_dir: z.string(),
152 | project_dir: z.string(),
153 | }),
154 | version: z.string().optional(),
155 | });
156 |
157 | /**
158 | * Type definition for Claude Code statusline hook JSON data
159 | */
160 | export type StatuslineHookJson = z.infer<typeof statuslineHookJsonSchema>;
161 |
--------------------------------------------------------------------------------
/src/calculate-cost.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * @fileoverview Cost calculation utilities for usage data analysis
3 | *
4 | * This module provides functions for calculating costs and aggregating token usage
5 | * across different time periods and models. It handles both pre-calculated costs
6 | * and dynamic cost calculations based on model pricing.
7 | *
8 | * @module calculate-cost
9 | */
10 |
11 | import type { AggregatedTokenCounts } from './_token-utils.ts';
12 | import type { DailyUsage, MonthlyUsage, SessionUsage, WeeklyUsage } from './data-loader.ts';
13 | import { getTotalTokens } from './_token-utils.ts';
14 | import {
15 | createActivityDate,
16 | createDailyDate,
17 | createModelName,
18 | createProjectPath,
19 | createSessionId,
20 | createVersion,
21 | } from './_types.ts';
22 |
23 | /**
24 | * Alias for AggregatedTokenCounts from shared utilities
25 | * @deprecated Use AggregatedTokenCounts from _token-utils.ts instead
26 | */
27 | type TokenData = AggregatedTokenCounts;
28 |
29 | /**
30 | * Token totals including cost information
31 | */
32 | type TokenTotals = TokenData & {
33 | totalCost: number;
34 | };
35 |
36 | /**
37 | * Complete totals object with token counts, cost, and total token sum
38 | */
39 | type TotalsObject = TokenTotals & {
40 | totalTokens: number;
41 | };
42 |
43 | /**
44 | * Calculates total token usage and cost across multiple usage data entries
45 | * @param data - Array of daily, monthly, or session usage data
46 | * @returns Aggregated token totals and cost
47 | */
48 | export function calculateTotals(
49 | data: Array<DailyUsage | MonthlyUsage | WeeklyUsage | SessionUsage>,
50 | ): TokenTotals {
51 | return data.reduce(
52 | (acc, item) => ({
53 | inputTokens: acc.inputTokens + item.inputTokens,
54 | outputTokens: acc.outputTokens + item.outputTokens,
55 | cacheCreationTokens: acc.cacheCreationTokens + item.cacheCreationTokens,
56 | cacheReadTokens: acc.cacheReadTokens + item.cacheReadTokens,
57 | totalCost: acc.totalCost + item.totalCost,
58 | }),
59 | {
60 | inputTokens: 0,
61 | outputTokens: 0,
62 | cacheCreationTokens: 0,
63 | cacheReadTokens: 0,
64 | totalCost: 0,
65 | },
66 | );
67 | }
68 |
69 | // Re-export getTotalTokens from shared utilities for backward compatibility
70 | export { getTotalTokens };
71 |
72 | /**
73 | * Creates a complete totals object by adding total token count to existing totals
74 | * @param totals - Token totals with cost information
75 | * @returns Complete totals object including total token sum
76 | */
77 | export function createTotalsObject(totals: TokenTotals): TotalsObject {
78 | return {
79 | ...totals,
80 | totalTokens: getTotalTokens(totals),
81 | };
82 | }
83 |
84 | if (import.meta.vitest != null) {
85 | describe('token aggregation utilities', () => {
86 | it('calculateTotals should aggregate daily usage data', () => {
87 | const dailyData: DailyUsage[] = [
88 | {
89 | date: createDailyDate('2024-01-01'),
90 | inputTokens: 100,
91 | outputTokens: 50,
92 | cacheCreationTokens: 25,
93 | cacheReadTokens: 10,
94 | totalCost: 0.01,
95 | modelsUsed: [createModelName('claude-sonnet-4-20250514')],
96 | modelBreakdowns: [],
97 | },
98 | {
99 | date: createDailyDate('2024-01-02'),
100 | inputTokens: 200,
101 | outputTokens: 100,
102 | cacheCreationTokens: 50,
103 | cacheReadTokens: 20,
104 | totalCost: 0.02,
105 | modelsUsed: [createModelName('claude-opus-4-20250514')],
106 | modelBreakdowns: [],
107 | },
108 | ];
109 |
110 | const totals = calculateTotals(dailyData);
111 | expect(totals.inputTokens).toBe(300);
112 | expect(totals.outputTokens).toBe(150);
113 | expect(totals.cacheCreationTokens).toBe(75);
114 | expect(totals.cacheReadTokens).toBe(30);
115 | expect(totals.totalCost).toBeCloseTo(0.03);
116 | });
117 |
118 | it('calculateTotals should aggregate session usage data', () => {
119 | const sessionData: SessionUsage[] = [
120 | {
121 | sessionId: createSessionId('session-1'),
122 | projectPath: createProjectPath('project/path'),
123 | inputTokens: 100,
124 | outputTokens: 50,
125 | cacheCreationTokens: 25,
126 | cacheReadTokens: 10,
127 | totalCost: 0.01,
128 | lastActivity: createActivityDate('2024-01-01'),
129 | versions: [createVersion('1.0.3')],
130 | modelsUsed: [createModelName('claude-sonnet-4-20250514')],
131 | modelBreakdowns: [],
132 | },
133 | {
134 | sessionId: createSessionId('session-2'),
135 | projectPath: createProjectPath('project/path'),
136 | inputTokens: 200,
137 | outputTokens: 100,
138 | cacheCreationTokens: 50,
139 | cacheReadTokens: 20,
140 | totalCost: 0.02,
141 | lastActivity: createActivityDate('2024-01-02'),
142 | versions: [createVersion('1.0.3'), createVersion('1.0.4')],
143 | modelsUsed: [createModelName('claude-opus-4-20250514')],
144 | modelBreakdowns: [],
145 | },
146 | ];
147 |
148 | const totals = calculateTotals(sessionData);
149 | expect(totals.inputTokens).toBe(300);
150 | expect(totals.outputTokens).toBe(150);
151 | expect(totals.cacheCreationTokens).toBe(75);
152 | expect(totals.cacheReadTokens).toBe(30);
153 | expect(totals.totalCost).toBeCloseTo(0.03);
154 | });
155 |
156 | it('getTotalTokens should sum all token types', () => {
157 | const tokens = {
158 | inputTokens: 100,
159 | outputTokens: 50,
160 | cacheCreationTokens: 25,
161 | cacheReadTokens: 10,
162 | };
163 |
164 | const total = getTotalTokens(tokens);
165 | expect(total).toBe(185);
166 | });
167 |
168 | it('getTotalTokens should handle zero values', () => {
169 | const tokens = {
170 | inputTokens: 0,
171 | outputTokens: 0,
172 | cacheCreationTokens: 0,
173 | cacheReadTokens: 0,
174 | };
175 |
176 | const total = getTotalTokens(tokens);
177 | expect(total).toBe(0);
178 | });
179 |
180 | it('createTotalsObject should create complete totals object', () => {
181 | const totals = {
182 | inputTokens: 100,
183 | outputTokens: 50,
184 | cacheCreationTokens: 25,
185 | cacheReadTokens: 10,
186 | totalCost: 0.01,
187 | };
188 |
189 | const totalsObject = createTotalsObject(totals);
190 | expect(totalsObject).toEqual({
191 | inputTokens: 100,
192 | outputTokens: 50,
193 | cacheCreationTokens: 25,
194 | cacheReadTokens: 10,
195 | totalTokens: 185,
196 | totalCost: 0.01,
197 | });
198 | });
199 |
200 | it('calculateTotals should handle empty array', () => {
201 | const totals = calculateTotals([]);
202 | expect(totals).toEqual({
203 | inputTokens: 0,
204 | outputTokens: 0,
205 | cacheCreationTokens: 0,
206 | cacheReadTokens: 0,
207 | totalCost: 0,
208 | });
209 | });
210 | });
211 | }
212 |
--------------------------------------------------------------------------------
/src/commands/_blocks.live.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * @fileoverview Live monitoring command orchestration
3 | *
4 | * This module provides the command-line interface for live monitoring,
5 | * handling process lifecycle, signal management, and terminal setup.
6 | * The actual rendering logic is handled by the _live-rendering module.
7 | */
8 |
9 | import type { LiveMonitoringConfig } from '../_live-rendering.ts';
10 | import process from 'node:process';
11 | import { Result } from '@praha/byethrow';
12 | import pc from 'picocolors';
13 | import { MIN_RENDER_INTERVAL_MS } from '../_consts.ts';
14 | import { LiveMonitor } from '../_live-monitor.ts';
15 | import {
16 | delayWithAbort,
17 | renderActiveBlock,
18 | renderWaitingState,
19 | } from '../_live-rendering.ts';
20 | import { TerminalManager } from '../_terminal-utils.ts';
21 | import { logger } from '../logger.ts';
22 |
23 | export async function startLiveMonitoring(config: LiveMonitoringConfig): Promise<void> {
24 | const terminal = new TerminalManager();
25 | const abortController = new AbortController();
26 | let lastRenderTime = 0;
27 |
28 | // Setup graceful shutdown
29 | const cleanup = (): void => {
30 | abortController.abort();
31 | terminal.cleanup();
32 | terminal.clearScreen();
33 | logger.info('Live monitoring stopped.');
34 | if (process.exitCode == null) {
35 | process.exit(0);
36 | }
37 | };
38 |
39 | process.on('SIGINT', cleanup);
40 | process.on('SIGTERM', cleanup);
41 |
42 | // Setup terminal for optimal TUI performance
43 | terminal.enterAlternateScreen();
44 | terminal.enableSyncMode();
45 | terminal.clearScreen();
46 | terminal.hideCursor();
47 |
48 | // Create live monitor with efficient data loading
49 | using monitor = new LiveMonitor({
50 | claudePaths: config.claudePaths,
51 | sessionDurationHours: config.sessionDurationHours,
52 | mode: config.mode,
53 | order: config.order,
54 | });
55 |
56 | const monitoringResult = await Result.try({
57 | try: async () => {
58 | while (!abortController.signal.aborted) {
59 | const now = Date.now();
60 | const timeSinceLastRender = now - lastRenderTime;
61 |
62 | // Skip render if too soon (frame rate limiting)
63 | if (timeSinceLastRender < MIN_RENDER_INTERVAL_MS) {
64 | await delayWithAbort(MIN_RENDER_INTERVAL_MS - timeSinceLastRender, abortController.signal);
65 | continue;
66 | }
67 |
68 | // Get latest data
69 | const activeBlock = await monitor.getActiveBlock();
70 | monitor.clearCache(); // TODO: debug LiveMonitor.getActiveBlock() efficiency
71 |
72 | if (activeBlock == null) {
73 | await renderWaitingState(terminal, config, abortController.signal);
74 | continue;
75 | }
76 |
77 | // Render active block
78 | renderActiveBlock(terminal, activeBlock, config);
79 | lastRenderTime = Date.now();
80 |
81 | // Wait before next refresh (refreshInterval passed, aborted, or terminal resized)
82 | let resizeEventHandler: undefined | ((value: unknown) => void);
83 |
84 | try {
85 | await Promise.race([
86 | delayWithAbort(config.refreshInterval, abortController.signal),
87 | new Promise((resolve) => {
88 | resizeEventHandler = resolve;
89 | process.stdout.once('resize', resolve);
90 | }),
91 | ]);
92 | }
93 | finally {
94 | if (resizeEventHandler != null) {
95 | process.stdout.removeListener('resize', resizeEventHandler);
96 | }
97 | }
98 | }
99 | },
100 | catch: error => error,
101 | })();
102 |
103 | if (Result.isFailure(monitoringResult)) {
104 | const error = monitoringResult.error;
105 | if ((error instanceof DOMException || error instanceof Error) && error.name === 'AbortError') {
106 | return; // Normal graceful shutdown
107 | }
108 |
109 | // Handle and display errors
110 | const errorMessage = error instanceof Error ? error.message : String(error);
111 | terminal.startBuffering();
112 | terminal.clearScreen();
113 | terminal.write(pc.red(`Error: ${errorMessage}\n`));
114 | terminal.flush();
115 | logger.error(`Live monitoring error: ${errorMessage}`);
116 | await delayWithAbort(config.refreshInterval, abortController.signal).catch(() => {});
117 | }
118 | }
119 |
--------------------------------------------------------------------------------
/src/commands/daily.ts:
--------------------------------------------------------------------------------
1 | import process from 'node:process';
2 | import { Result } from '@praha/byethrow';
3 | import { define } from 'gunshi';
4 | import pc from 'picocolors';
5 | import { groupByProject, groupDataByProject } from '../_daily-grouping.ts';
6 | import { processWithJq } from '../_jq-processor.ts';
7 | import { formatProjectName } from '../_project-names.ts';
8 | import { sharedCommandConfig } from '../_shared-args.ts';
9 | import { formatCurrency, formatModelsDisplayMultiline, formatNumber, pushBreakdownRows, ResponsiveTable } from '../_utils.ts';
10 | import {
11 | calculateTotals,
12 | createTotalsObject,
13 | getTotalTokens,
14 | } from '../calculate-cost.ts';
15 | import { formatDateCompact, loadDailyUsageData } from '../data-loader.ts';
16 | import { detectMismatches, printMismatchReport } from '../debug.ts';
17 | import { log, logger } from '../logger.ts';
18 |
19 | export const dailyCommand = define({
20 | name: 'daily',
21 | description: 'Show usage report grouped by date',
22 | ...sharedCommandConfig,
23 | args: {
24 | ...sharedCommandConfig.args,
25 | instances: {
26 | type: 'boolean',
27 | short: 'i',
28 | description: 'Show usage breakdown by project/instance',
29 | default: false,
30 | },
31 | project: {
32 | type: 'string',
33 | short: 'p',
34 | description: 'Filter to specific project name',
35 | },
36 | },
37 | async run(ctx) {
38 | // --jq implies --json
39 | const useJson = ctx.values.json || ctx.values.jq != null;
40 | if (useJson) {
41 | logger.level = 0;
42 | }
43 |
44 | const dailyData = await loadDailyUsageData({
45 | since: ctx.values.since,
46 | until: ctx.values.until,
47 | mode: ctx.values.mode,
48 | order: ctx.values.order,
49 | offline: ctx.values.offline,
50 | groupByProject: ctx.values.instances,
51 | project: ctx.values.project,
52 | timezone: ctx.values.timezone,
53 | locale: ctx.values.locale,
54 | });
55 |
56 | if (dailyData.length === 0) {
57 | if (useJson) {
58 | log(JSON.stringify([]));
59 | }
60 | else {
61 | logger.warn('No Claude usage data found.');
62 | }
63 | process.exit(0);
64 | }
65 |
66 | // Calculate totals
67 | const totals = calculateTotals(dailyData);
68 |
69 | // Show debug information if requested
70 | if (ctx.values.debug && !useJson) {
71 | const mismatchStats = await detectMismatches(undefined);
72 | printMismatchReport(mismatchStats, ctx.values.debugSamples);
73 | }
74 |
75 | if (useJson) {
76 | // Output JSON format - group by project if instances flag is used
77 | const jsonOutput = ctx.values.instances && dailyData.some(d => d.project != null)
78 | ? {
79 | projects: groupByProject(dailyData),
80 | totals: createTotalsObject(totals),
81 | }
82 | : {
83 | daily: dailyData.map(data => ({
84 | date: data.date,
85 | inputTokens: data.inputTokens,
86 | outputTokens: data.outputTokens,
87 | cacheCreationTokens: data.cacheCreationTokens,
88 | cacheReadTokens: data.cacheReadTokens,
89 | totalTokens: getTotalTokens(data),
90 | totalCost: data.totalCost,
91 | modelsUsed: data.modelsUsed,
92 | modelBreakdowns: data.modelBreakdowns,
93 | ...(data.project != null && { project: data.project }),
94 | })),
95 | totals: createTotalsObject(totals),
96 | };
97 |
98 | // Process with jq if specified
99 | if (ctx.values.jq != null) {
100 | const jqResult = await processWithJq(jsonOutput, ctx.values.jq);
101 | if (Result.isFailure(jqResult)) {
102 | logger.error((jqResult.error).message);
103 | process.exit(1);
104 | }
105 | log(jqResult.value);
106 | }
107 | else {
108 | log(JSON.stringify(jsonOutput, null, 2));
109 | }
110 | }
111 | else {
112 | // Print header
113 | logger.box('Claude Code Token Usage Report - Daily');
114 |
115 | // Create table with compact mode support
116 | const table = new ResponsiveTable({
117 | head: [
118 | 'Date',
119 | 'Models',
120 | 'Input',
121 | 'Output',
122 | 'Cache Create',
123 | 'Cache Read',
124 | 'Total Tokens',
125 | 'Cost (USD)',
126 | ],
127 | style: {
128 | head: ['cyan'],
129 | },
130 | colAligns: [
131 | 'left',
132 | 'left',
133 | 'right',
134 | 'right',
135 | 'right',
136 | 'right',
137 | 'right',
138 | 'right',
139 | ],
140 | dateFormatter: (dateStr: string) => formatDateCompact(dateStr, ctx.values.timezone, ctx.values.locale),
141 | compactHead: [
142 | 'Date',
143 | 'Models',
144 | 'Input',
145 | 'Output',
146 | 'Cost (USD)',
147 | ],
148 | compactColAligns: [
149 | 'left',
150 | 'left',
151 | 'right',
152 | 'right',
153 | 'right',
154 | ],
155 | compactThreshold: 100,
156 | });
157 |
158 | // Add daily data - group by project if instances flag is used
159 | if (ctx.values.instances && dailyData.some(d => d.project != null)) {
160 | // Group data by project for visual separation
161 | const projectGroups = groupDataByProject(dailyData);
162 |
163 | let isFirstProject = true;
164 | for (const [projectName, projectData] of Object.entries(projectGroups)) {
165 | // Add project section header
166 | if (!isFirstProject) {
167 | // Add empty row for visual separation between projects
168 | table.push(['', '', '', '', '', '', '', '']);
169 | }
170 |
171 | // Add project header row
172 | table.push([
173 | pc.cyan(`Project: ${formatProjectName(projectName)}`),
174 | '',
175 | '',
176 | '',
177 | '',
178 | '',
179 | '',
180 | '',
181 | ]);
182 |
183 | // Add data rows for this project
184 | for (const data of projectData) {
185 | table.push([
186 | data.date,
187 | formatModelsDisplayMultiline(data.modelsUsed),
188 | formatNumber(data.inputTokens),
189 | formatNumber(data.outputTokens),
190 | formatNumber(data.cacheCreationTokens),
191 | formatNumber(data.cacheReadTokens),
192 | formatNumber(getTotalTokens(data)),
193 | formatCurrency(data.totalCost),
194 | ]);
195 |
196 | // Add model breakdown rows if flag is set
197 | if (ctx.values.breakdown) {
198 | pushBreakdownRows(table, data.modelBreakdowns);
199 | }
200 | }
201 |
202 | isFirstProject = false;
203 | }
204 | }
205 | else {
206 | // Standard display without project grouping
207 | for (const data of dailyData) {
208 | // Main row
209 | table.push([
210 | data.date,
211 | formatModelsDisplayMultiline(data.modelsUsed),
212 | formatNumber(data.inputTokens),
213 | formatNumber(data.outputTokens),
214 | formatNumber(data.cacheCreationTokens),
215 | formatNumber(data.cacheReadTokens),
216 | formatNumber(getTotalTokens(data)),
217 | formatCurrency(data.totalCost),
218 | ]);
219 |
220 | // Add model breakdown rows if flag is set
221 | if (ctx.values.breakdown) {
222 | pushBreakdownRows(table, data.modelBreakdowns);
223 | }
224 | }
225 | }
226 |
227 | // Add empty row for visual separation before totals
228 | table.push([
229 | '',
230 | '',
231 | '',
232 | '',
233 | '',
234 | '',
235 | '',
236 | '',
237 | ]);
238 |
239 | // Add totals
240 | table.push([
241 | pc.yellow('Total'),
242 | '', // Empty for Models column in totals
243 | pc.yellow(formatNumber(totals.inputTokens)),
244 | pc.yellow(formatNumber(totals.outputTokens)),
245 | pc.yellow(formatNumber(totals.cacheCreationTokens)),
246 | pc.yellow(formatNumber(totals.cacheReadTokens)),
247 | pc.yellow(formatNumber(getTotalTokens(totals))),
248 | pc.yellow(formatCurrency(totals.totalCost)),
249 | ]);
250 |
251 | log(table.toString());
252 |
253 | // Show guidance message if in compact mode
254 | if (table.isCompactMode()) {
255 | logger.info('\nRunning in Compact Mode');
256 | logger.info('Expand terminal width to see cache metrics and total tokens');
257 | }
258 | }
259 | },
260 | });
261 |
--------------------------------------------------------------------------------
/src/commands/index.ts:
--------------------------------------------------------------------------------
1 | import process from 'node:process';
2 | import { cli } from 'gunshi';
3 | import { description, name, version } from '../../package.json';
4 | import { blocksCommand } from './blocks.ts';
5 | import { dailyCommand } from './daily.ts';
6 | import { mcpCommand } from './mcp.ts';
7 | import { monthlyCommand } from './monthly.ts';
8 | import { sessionCommand } from './session.ts';
9 | import { statuslineCommand } from './statusline.ts';
10 | import { weeklyCommand } from './weekly.ts';
11 |
12 | /**
13 | * Map of available CLI subcommands
14 | */
15 | const subCommands = new Map();
16 | subCommands.set('daily', dailyCommand);
17 | subCommands.set('monthly', monthlyCommand);
18 | subCommands.set('weekly', weeklyCommand);
19 | subCommands.set('session', sessionCommand);
20 | subCommands.set('blocks', blocksCommand);
21 | subCommands.set('mcp', mcpCommand);
22 | subCommands.set('statusline', statuslineCommand);
23 |
24 | /**
25 | * Default command when no subcommand is specified (defaults to daily)
26 | */
27 | const mainCommand = dailyCommand;
28 |
29 | // eslint-disable-next-line antfu/no-top-level-await
30 | await cli(process.argv.slice(2), mainCommand, {
31 | name,
32 | version,
33 | description,
34 | subCommands,
35 | renderHeader: null,
36 | });
37 |
--------------------------------------------------------------------------------
/src/commands/mcp.ts:
--------------------------------------------------------------------------------
1 | import { serve } from '@hono/node-server';
2 | import { define } from 'gunshi';
3 | import { MCP_DEFAULT_PORT } from '../_consts.ts';
4 | import { sharedArgs } from '../_shared-args.ts';
5 | import { getClaudePaths } from '../data-loader.ts';
6 | import { logger } from '../logger.ts';
7 | import { createMcpHttpApp, createMcpServer, startMcpServerStdio } from '../mcp.ts';
8 |
9 | /**
10 | * MCP server command that supports both stdio and HTTP transports.
11 | * Allows starting an MCP server for external integrations with usage reporting tools.
12 | */
13 | export const mcpCommand = define({
14 | name: 'mcp',
15 | description: 'Start MCP server with usage reporting tools',
16 | args: {
17 | mode: sharedArgs.mode,
18 | type: {
19 | type: 'enum',
20 | short: 't',
21 | description: 'Transport type for MCP server',
22 | choices: ['stdio', 'http'] as const,
23 | default: 'stdio',
24 | },
25 | port: {
26 | type: 'number',
27 | description: `Port for HTTP transport (default: ${MCP_DEFAULT_PORT})`,
28 | default: MCP_DEFAULT_PORT,
29 | },
30 | },
31 | async run(ctx) {
32 | const { type, mode, port } = ctx.values;
33 | // disable info logging for stdio
34 | if (type === 'stdio') {
35 | logger.level = 0;
36 | }
37 |
38 | const paths = getClaudePaths();
39 | if (paths.length === 0) {
40 | logger.error('No valid Claude data directory found');
41 | throw new Error('No valid Claude data directory found');
42 | }
43 |
44 | const options = {
45 | claudePath: paths[0]!,
46 | mode,
47 | };
48 |
49 | if (type === 'stdio') {
50 | const server = createMcpServer(options);
51 | await startMcpServerStdio(server);
52 | }
53 | else {
54 | const app = createMcpHttpApp(options);
55 | // Use the Hono app to handle requests
56 | serve({
57 | fetch: app.fetch,
58 | port,
59 | });
60 | logger.info(`MCP server is running on http://localhost:${port}`);
61 | }
62 | },
63 | });
64 |
--------------------------------------------------------------------------------
/src/commands/monthly.ts:
--------------------------------------------------------------------------------
1 | import process from 'node:process';
2 | import { Result } from '@praha/byethrow';
3 | import { define } from 'gunshi';
4 | import pc from 'picocolors';
5 | import { processWithJq } from '../_jq-processor.ts';
6 | import { sharedCommandConfig } from '../_shared-args.ts';
7 | import { formatCurrency, formatModelsDisplayMultiline, formatNumber, pushBreakdownRows, ResponsiveTable } from '../_utils.ts';
8 | import {
9 | calculateTotals,
10 | createTotalsObject,
11 | getTotalTokens,
12 | } from '../calculate-cost.ts';
13 | import { formatDateCompact, loadMonthlyUsageData } from '../data-loader.ts';
14 | import { detectMismatches, printMismatchReport } from '../debug.ts';
15 | import { log, logger } from '../logger.ts';
16 |
17 | export const monthlyCommand = define({
18 | name: 'monthly',
19 | description: 'Show usage report grouped by month',
20 | ...sharedCommandConfig,
21 | async run(ctx) {
22 | // --jq implies --json
23 | const useJson = ctx.values.json || ctx.values.jq != null;
24 | if (useJson) {
25 | logger.level = 0;
26 | }
27 |
28 | const monthlyData = await loadMonthlyUsageData({
29 | since: ctx.values.since,
30 | until: ctx.values.until,
31 | mode: ctx.values.mode,
32 | order: ctx.values.order,
33 | offline: ctx.values.offline,
34 | timezone: ctx.values.timezone,
35 | locale: ctx.values.locale,
36 | });
37 |
38 | if (monthlyData.length === 0) {
39 | if (useJson) {
40 | const emptyOutput = {
41 | monthly: [],
42 | totals: {
43 | inputTokens: 0,
44 | outputTokens: 0,
45 | cacheCreationTokens: 0,
46 | cacheReadTokens: 0,
47 | totalTokens: 0,
48 | totalCost: 0,
49 | },
50 | };
51 | log(JSON.stringify(emptyOutput, null, 2));
52 | }
53 | else {
54 | logger.warn('No Claude usage data found.');
55 | }
56 | process.exit(0);
57 | }
58 |
59 | // Calculate totals
60 | const totals = calculateTotals(monthlyData);
61 |
62 | // Show debug information if requested
63 | if (ctx.values.debug && !useJson) {
64 | const mismatchStats = await detectMismatches(undefined);
65 | printMismatchReport(mismatchStats, ctx.values.debugSamples);
66 | }
67 |
68 | if (useJson) {
69 | // Output JSON format
70 | const jsonOutput = {
71 | monthly: monthlyData.map(data => ({
72 | month: data.month,
73 | inputTokens: data.inputTokens,
74 | outputTokens: data.outputTokens,
75 | cacheCreationTokens: data.cacheCreationTokens,
76 | cacheReadTokens: data.cacheReadTokens,
77 | totalTokens: getTotalTokens(data),
78 | totalCost: data.totalCost,
79 | modelsUsed: data.modelsUsed,
80 | modelBreakdowns: data.modelBreakdowns,
81 | })),
82 | totals: createTotalsObject(totals),
83 | };
84 |
85 | // Process with jq if specified
86 | if (ctx.values.jq != null) {
87 | const jqResult = await processWithJq(jsonOutput, ctx.values.jq);
88 | if (Result.isFailure(jqResult)) {
89 | logger.error((jqResult.error).message);
90 | process.exit(1);
91 | }
92 | log(jqResult.value);
93 | }
94 | else {
95 | log(JSON.stringify(jsonOutput, null, 2));
96 | }
97 | }
98 | else {
99 | // Print header
100 | logger.box('Claude Code Token Usage Report - Monthly');
101 |
102 | // Create table with compact mode support
103 | const table = new ResponsiveTable({
104 | head: [
105 | 'Month',
106 | 'Models',
107 | 'Input',
108 | 'Output',
109 | 'Cache Create',
110 | 'Cache Read',
111 | 'Total Tokens',
112 | 'Cost (USD)',
113 | ],
114 | style: {
115 | head: ['cyan'],
116 | },
117 | colAligns: [
118 | 'left',
119 | 'left',
120 | 'right',
121 | 'right',
122 | 'right',
123 | 'right',
124 | 'right',
125 | 'right',
126 | ],
127 | dateFormatter: (dateStr: string) => formatDateCompact(dateStr, ctx.values.timezone, ctx.values.locale),
128 | compactHead: [
129 | 'Month',
130 | 'Models',
131 | 'Input',
132 | 'Output',
133 | 'Cost (USD)',
134 | ],
135 | compactColAligns: [
136 | 'left',
137 | 'left',
138 | 'right',
139 | 'right',
140 | 'right',
141 | ],
142 | compactThreshold: 100,
143 | });
144 |
145 | // Add monthly data
146 | for (const data of monthlyData) {
147 | // Main row
148 | table.push([
149 | data.month,
150 | formatModelsDisplayMultiline(data.modelsUsed),
151 | formatNumber(data.inputTokens),
152 | formatNumber(data.outputTokens),
153 | formatNumber(data.cacheCreationTokens),
154 | formatNumber(data.cacheReadTokens),
155 | formatNumber(getTotalTokens(data)),
156 | formatCurrency(data.totalCost),
157 | ]);
158 |
159 | // Add model breakdown rows if flag is set
160 | if (ctx.values.breakdown) {
161 | pushBreakdownRows(table, data.modelBreakdowns);
162 | }
163 | }
164 |
165 | // Add empty row for visual separation before totals
166 | table.push([
167 | '',
168 | '',
169 | '',
170 | '',
171 | '',
172 | '',
173 | '',
174 | '',
175 | ]);
176 |
177 | // Add totals
178 | table.push([
179 | pc.yellow('Total'),
180 | '', // Empty for Models column in totals
181 | pc.yellow(formatNumber(totals.inputTokens)),
182 | pc.yellow(formatNumber(totals.outputTokens)),
183 | pc.yellow(formatNumber(totals.cacheCreationTokens)),
184 | pc.yellow(formatNumber(totals.cacheReadTokens)),
185 | pc.yellow(formatNumber(getTotalTokens(totals))),
186 | pc.yellow(formatCurrency(totals.totalCost)),
187 | ]);
188 |
189 | log(table.toString());
190 |
191 | // Show guidance message if in compact mode
192 | if (table.isCompactMode()) {
193 | logger.info('\nRunning in Compact Mode');
194 | logger.info('Expand terminal width to see cache metrics and total tokens');
195 | }
196 | }
197 | },
198 | });
199 |
--------------------------------------------------------------------------------
/src/commands/session.ts:
--------------------------------------------------------------------------------
1 | import process from 'node:process';
2 | import { Result } from '@praha/byethrow';
3 | import { define } from 'gunshi';
4 | import pc from 'picocolors';
5 | import { processWithJq } from '../_jq-processor.ts';
6 | import { sharedCommandConfig } from '../_shared-args.ts';
7 | import { formatCurrency, formatModelsDisplayMultiline, formatNumber, pushBreakdownRows, ResponsiveTable } from '../_utils.ts';
8 | import {
9 | calculateTotals,
10 | createTotalsObject,
11 | getTotalTokens,
12 | } from '../calculate-cost.ts';
13 | import { formatDateCompact, loadSessionData } from '../data-loader.ts';
14 | import { detectMismatches, printMismatchReport } from '../debug.ts';
15 | import { log, logger } from '../logger.ts';
16 |
17 | export const sessionCommand = define({
18 | name: 'session',
19 | description: 'Show usage report grouped by conversation session',
20 | ...sharedCommandConfig,
21 | async run(ctx) {
22 | // --jq implies --json
23 | const useJson = ctx.values.json || ctx.values.jq != null;
24 | if (useJson) {
25 | logger.level = 0;
26 | }
27 |
28 | const sessionData = await loadSessionData({
29 | since: ctx.values.since,
30 | until: ctx.values.until,
31 | mode: ctx.values.mode,
32 | order: ctx.values.order,
33 | offline: ctx.values.offline,
34 | timezone: ctx.values.timezone,
35 | locale: ctx.values.locale,
36 | });
37 |
38 | if (sessionData.length === 0) {
39 | if (useJson) {
40 | log(JSON.stringify([]));
41 | }
42 | else {
43 | logger.warn('No Claude usage data found.');
44 | }
45 | process.exit(0);
46 | }
47 |
48 | // Calculate totals
49 | const totals = calculateTotals(sessionData);
50 |
51 | // Show debug information if requested
52 | if (ctx.values.debug && !useJson) {
53 | const mismatchStats = await detectMismatches(undefined);
54 | printMismatchReport(mismatchStats, ctx.values.debugSamples);
55 | }
56 |
57 | if (useJson) {
58 | // Output JSON format
59 | const jsonOutput = {
60 | sessions: sessionData.map(data => ({
61 | sessionId: data.sessionId,
62 | inputTokens: data.inputTokens,
63 | outputTokens: data.outputTokens,
64 | cacheCreationTokens: data.cacheCreationTokens,
65 | cacheReadTokens: data.cacheReadTokens,
66 | totalTokens: getTotalTokens(data),
67 | totalCost: data.totalCost,
68 | lastActivity: data.lastActivity,
69 | modelsUsed: data.modelsUsed,
70 | modelBreakdowns: data.modelBreakdowns,
71 | projectPath: data.projectPath,
72 | })),
73 | totals: createTotalsObject(totals),
74 | };
75 |
76 | // Process with jq if specified
77 | if (ctx.values.jq != null) {
78 | const jqResult = await processWithJq(jsonOutput, ctx.values.jq);
79 | if (Result.isFailure(jqResult)) {
80 | logger.error((jqResult.error).message);
81 | process.exit(1);
82 | }
83 | log(jqResult.value);
84 | }
85 | else {
86 | log(JSON.stringify(jsonOutput, null, 2));
87 | }
88 | }
89 | else {
90 | // Print header
91 | logger.box('Claude Code Token Usage Report - By Session');
92 |
93 | // Create table with compact mode support
94 | const table = new ResponsiveTable({
95 | head: [
96 | 'Session',
97 | 'Models',
98 | 'Input',
99 | 'Output',
100 | 'Cache Create',
101 | 'Cache Read',
102 | 'Total Tokens',
103 | 'Cost (USD)',
104 | 'Last Activity',
105 | ],
106 | style: {
107 | head: ['cyan'],
108 | },
109 | colAligns: [
110 | 'left',
111 | 'left',
112 | 'right',
113 | 'right',
114 | 'right',
115 | 'right',
116 | 'right',
117 | 'right',
118 | 'left',
119 | ],
120 | dateFormatter: (dateStr: string) => formatDateCompact(dateStr, ctx.values.timezone, ctx.values.locale),
121 | compactHead: [
122 | 'Session',
123 | 'Models',
124 | 'Input',
125 | 'Output',
126 | 'Cost (USD)',
127 | 'Last Activity',
128 | ],
129 | compactColAligns: [
130 | 'left',
131 | 'left',
132 | 'right',
133 | 'right',
134 | 'right',
135 | 'left',
136 | ],
137 | compactThreshold: 100,
138 | });
139 |
140 | // Add session data
141 | let maxSessionLength = 0;
142 | for (const data of sessionData) {
143 | const sessionDisplay = data.sessionId.split('-').slice(-2).join('-'); // Display last two parts of session ID
144 |
145 | maxSessionLength = Math.max(maxSessionLength, sessionDisplay.length);
146 |
147 | // Main row
148 | table.push([
149 | sessionDisplay,
150 | formatModelsDisplayMultiline(data.modelsUsed),
151 | formatNumber(data.inputTokens),
152 | formatNumber(data.outputTokens),
153 | formatNumber(data.cacheCreationTokens),
154 | formatNumber(data.cacheReadTokens),
155 | formatNumber(getTotalTokens(data)),
156 | formatCurrency(data.totalCost),
157 | data.lastActivity,
158 | ]);
159 |
160 | // Add model breakdown rows if flag is set
161 | if (ctx.values.breakdown) {
162 | // Session has 1 extra column before data and 1 trailing column
163 | pushBreakdownRows(table, data.modelBreakdowns, 1, 1);
164 | }
165 | }
166 |
167 | // Add empty row for visual separation before totals
168 | table.push([
169 | '',
170 | '',
171 | '',
172 | '',
173 | '',
174 | '',
175 | '',
176 | '',
177 | '',
178 | ]);
179 |
180 | // Add totals
181 | table.push([
182 | pc.yellow('Total'),
183 | '', // Empty for Models column in totals
184 | pc.yellow(formatNumber(totals.inputTokens)),
185 | pc.yellow(formatNumber(totals.outputTokens)),
186 | pc.yellow(formatNumber(totals.cacheCreationTokens)),
187 | pc.yellow(formatNumber(totals.cacheReadTokens)),
188 | pc.yellow(formatNumber(getTotalTokens(totals))),
189 | pc.yellow(formatCurrency(totals.totalCost)),
190 | '',
191 | ]);
192 |
193 | log(table.toString());
194 |
195 | // Show guidance message if in compact mode
196 | if (table.isCompactMode()) {
197 | logger.info('\nRunning in Compact Mode');
198 | logger.info('Expand terminal width to see cache metrics and total tokens');
199 | }
200 | }
201 | },
202 | });
203 |
--------------------------------------------------------------------------------
/src/commands/statusline.ts:
--------------------------------------------------------------------------------
1 | import process from 'node:process';
2 | import getStdin from 'get-stdin';
3 | import { define } from 'gunshi';
4 | import pc from 'picocolors';
5 | import { calculateBurnRate } from '../_session-blocks.ts';
6 | import { sharedArgs } from '../_shared-args.ts';
7 | import { statuslineHookJsonSchema } from '../_types.ts';
8 | import { formatCurrency } from '../_utils.ts';
9 | import { calculateTotals } from '../calculate-cost.ts';
10 | import { getClaudePaths, loadDailyUsageData, loadSessionBlockData, loadSessionUsageById } from '../data-loader.ts';
11 | import { log, logger } from '../logger.ts';
12 |
13 | /**
14 | /**
15 | * Formats the remaining time for display
16 | * @param remaining - Remaining minutes
17 | * @returns Formatted time string
18 | */
19 | function formatRemainingTime(remaining: number): string {
20 | const remainingHours = Math.floor(remaining / 60);
21 | const remainingMins = remaining % 60;
22 |
23 | if (remainingHours > 0) {
24 | return `${remainingHours}h ${remainingMins}m left`;
25 | }
26 | return `${remainingMins}m left`;
27 | }
28 |
29 | export const statuslineCommand = define({
30 | name: 'statusline',
31 | description: 'Display compact status line for Claude Code hooks (Beta)',
32 | args: {
33 | offline: {
34 | ...sharedArgs.offline,
35 | default: true, // Default to offline mode for faster performance
36 | },
37 | },
38 | async run(ctx) {
39 | // Set logger to silent for statusline output
40 | logger.level = 0;
41 |
42 | // Read input from stdin
43 | const stdin = await getStdin();
44 | if (stdin.length === 0) {
45 | log('❌ No input provided');
46 | process.exit(1);
47 | }
48 | // Parse input as JSON
49 | const hookDataJson: unknown = JSON.parse(stdin.trim());
50 | const hookDataParseResult = statuslineHookJsonSchema.safeParse(hookDataJson);
51 | if (!hookDataParseResult.success) {
52 | log('❌ Invalid input format:', hookDataParseResult.error.message);
53 | process.exit(1);
54 | }
55 | const hookData = hookDataParseResult.data;
56 |
57 | // Get Claude paths
58 | const claudePaths = getClaudePaths();
59 | if (claudePaths.length === 0) {
60 | log('❌ No Claude data directory found');
61 | process.exit(1);
62 | }
63 |
64 | // Extract session ID from hook data
65 | const sessionId = hookData.session_id;
66 |
67 | // Load current session's cost by finding the specific JSONL file
68 | let sessionCost: number | null = null;
69 | try {
70 | const sessionData = await loadSessionUsageById(sessionId, { mode: 'auto', offline: ctx.values.offline });
71 | if (sessionData != null) {
72 | sessionCost = sessionData.totalCost;
73 | }
74 | }
75 | catch (error) {
76 | logger.error('Failed to load session data:', error);
77 | }
78 |
79 | // Load today's usage data
80 | const today = new Date();
81 | const todayStr = today.toISOString().split('T')[0]?.replace(/-/g, '') ?? ''; // Convert to YYYYMMDD format
82 |
83 | let todayCost = 0;
84 | try {
85 | const dailyData = await loadDailyUsageData({
86 | since: todayStr,
87 | until: todayStr,
88 | mode: 'auto',
89 | offline: ctx.values.offline,
90 | });
91 |
92 | if (dailyData.length > 0) {
93 | const totals = calculateTotals(dailyData);
94 | todayCost = totals.totalCost;
95 | }
96 | }
97 | catch (error) {
98 | logger.error('Failed to load daily data:', error);
99 | }
100 |
101 | // Load session block data to find active block
102 | let blockInfo = '';
103 | let burnRateInfo = '';
104 | try {
105 | const blocks = await loadSessionBlockData({
106 | mode: 'auto',
107 | offline: ctx.values.offline,
108 | });
109 |
110 | // Only identify blocks if we have data
111 | if (blocks.length === 0) {
112 | blockInfo = 'No active block';
113 | }
114 | else {
115 | // Find active block that contains our session
116 | const activeBlock = blocks.find((block) => {
117 | if (!block.isActive) {
118 | return false;
119 | }
120 |
121 | // Check if any entry in this block matches our session
122 | // Since we don't have direct session mapping in entries,
123 | // we use the active block that's currently running
124 | return true;
125 | });
126 |
127 | if (activeBlock != null) {
128 | const now = new Date();
129 | const remaining = Math.round((activeBlock.endTime.getTime() - now.getTime()) / (1000 * 60));
130 | const blockCost = activeBlock.costUSD;
131 |
132 | blockInfo = `${formatCurrency(blockCost)} block (${formatRemainingTime(remaining)})`;
133 |
134 | // Calculate burn rate
135 | const burnRate = calculateBurnRate(activeBlock);
136 | if (burnRate != null) {
137 | const costPerHour = burnRate.costPerHour;
138 | const costPerHourStr = `${formatCurrency(costPerHour)}/hr`;
139 |
140 | // Apply color based on burn rate (tokens per minute non-cache)
141 | let coloredBurnRate = costPerHourStr;
142 | if (burnRate.tokensPerMinuteForIndicator < 2000) {
143 | coloredBurnRate = pc.green(costPerHourStr); // Normal
144 | }
145 | else if (burnRate.tokensPerMinuteForIndicator < 5000) {
146 | coloredBurnRate = pc.yellow(costPerHourStr); // Moderate
147 | }
148 | else {
149 | coloredBurnRate = pc.red(costPerHourStr); // High
150 | }
151 |
152 | burnRateInfo = ` | 🔥 ${coloredBurnRate}`;
153 | }
154 | }
155 | else {
156 | blockInfo = 'No active block';
157 | }
158 | }
159 | }
160 | catch (error) {
161 | logger.error('Failed to load block data:', error);
162 | blockInfo = 'No active block';
163 | }
164 |
165 | // Get model display name
166 | const modelName = hookData.model.display_name;
167 |
168 | // Format and output the status line
169 | // Format: 🤖 model | 💰 session / today / block | 🔥 burn
170 | const sessionDisplay = sessionCost !== null ? formatCurrency(sessionCost) : 'N/A';
171 | const statusLine = `🤖 ${modelName} | 💰 ${sessionDisplay} session / ${formatCurrency(todayCost)} today / ${blockInfo}${burnRateInfo}`;
172 |
173 | log(statusLine);
174 | },
175 | });
176 |
--------------------------------------------------------------------------------
/src/commands/weekly.ts:
--------------------------------------------------------------------------------
1 | import process from 'node:process';
2 | import { Result } from '@praha/byethrow';
3 | import { define } from 'gunshi';
4 | import pc from 'picocolors';
5 | import { WEEK_DAYS } from '../_consts.ts';
6 | import { processWithJq } from '../_jq-processor.ts';
7 | import { sharedArgs } from '../_shared-args.ts';
8 | import { formatCurrency, formatModelsDisplayMultiline, formatNumber, pushBreakdownRows, ResponsiveTable } from '../_utils.ts';
9 | import {
10 | calculateTotals,
11 | createTotalsObject,
12 | getTotalTokens,
13 | } from '../calculate-cost.ts';
14 | import { formatDateCompact, loadWeeklyUsageData } from '../data-loader.ts';
15 | import { detectMismatches, printMismatchReport } from '../debug.ts';
16 | import { log, logger } from '../logger.ts';
17 |
18 | export const weeklyCommand = define({
19 | name: 'weekly',
20 | description: 'Show usage report grouped by week',
21 | args: {
22 | ...sharedArgs,
23 | startOfWeek: {
24 | type: 'enum',
25 | short: 'w',
26 | description: 'Day to start the week on',
27 | default: 'sunday' as const,
28 | choices: WEEK_DAYS,
29 | },
30 | },
31 | toKebab: true,
32 | async run(ctx) {
33 | // --jq implies --json
34 | const useJson = ctx.values.json || ctx.values.jq != null;
35 | if (useJson) {
36 | logger.level = 0;
37 | }
38 |
39 | const weeklyData = await loadWeeklyUsageData({
40 | since: ctx.values.since,
41 | until: ctx.values.until,
42 | timezone: ctx.values.timezone,
43 | mode: ctx.values.mode,
44 | order: ctx.values.order,
45 | offline: ctx.values.offline,
46 | startOfWeek: ctx.values.startOfWeek,
47 | locale: ctx.values.locale,
48 | });
49 |
50 | if (weeklyData.length === 0) {
51 | if (useJson) {
52 | const emptyOutput = {
53 | weekly: [],
54 | totals: {
55 | inputTokens: 0,
56 | outputTokens: 0,
57 | cacheCreationTokens: 0,
58 | cacheReadTokens: 0,
59 | totalTokens: 0,
60 | totalCost: 0,
61 | },
62 | };
63 | log(JSON.stringify(emptyOutput, null, 2));
64 | }
65 | else {
66 | logger.warn('No Claude usage data found.');
67 | }
68 | process.exit(0);
69 | }
70 |
71 | // Calculate totals
72 | const totals = calculateTotals(weeklyData);
73 |
74 | // Show debug information if requested
75 | if (ctx.values.debug && !useJson) {
76 | const mismatchStats = await detectMismatches(undefined);
77 | printMismatchReport(mismatchStats, ctx.values.debugSamples);
78 | }
79 |
80 | if (useJson) {
81 | // Output JSON format
82 | const jsonOutput = {
83 | weekly: weeklyData.map(data => ({
84 | week: data.week,
85 | inputTokens: data.inputTokens,
86 | outputTokens: data.outputTokens,
87 | cacheCreationTokens: data.cacheCreationTokens,
88 | cacheReadTokens: data.cacheReadTokens,
89 | totalTokens: getTotalTokens(data),
90 | totalCost: data.totalCost,
91 | modelsUsed: data.modelsUsed,
92 | modelBreakdowns: data.modelBreakdowns,
93 | })),
94 | totals: createTotalsObject(totals),
95 | };
96 |
97 | // Process with jq if specified
98 | if (ctx.values.jq != null) {
99 | const jqResult = await processWithJq(jsonOutput, ctx.values.jq);
100 | if (Result.isFailure(jqResult)) {
101 | logger.error((jqResult.error).message);
102 | process.exit(1);
103 | }
104 | log(jqResult.value);
105 | }
106 | else {
107 | log(JSON.stringify(jsonOutput, null, 2));
108 | }
109 | }
110 | else {
111 | // Print header
112 | logger.box('Claude Code Token Usage Report - Weekly');
113 |
114 | // Create table with compact mode support
115 | const table = new ResponsiveTable({
116 | head: [
117 | 'Week',
118 | 'Models',
119 | 'Input',
120 | 'Output',
121 | 'Cache Create',
122 | 'Cache Read',
123 | 'Total Tokens',
124 | 'Cost (USD)',
125 | ],
126 | style: {
127 | head: ['cyan'],
128 | },
129 | colAligns: [
130 | 'left',
131 | 'left',
132 | 'right',
133 | 'right',
134 | 'right',
135 | 'right',
136 | 'right',
137 | 'right',
138 | ],
139 | dateFormatter: (dateStr: string) => formatDateCompact(dateStr, ctx.values.timezone, ctx.values.locale),
140 | compactHead: [
141 | 'Week',
142 | 'Models',
143 | 'Input',
144 | 'Output',
145 | 'Cost (USD)',
146 | ],
147 | compactColAligns: [
148 | 'left',
149 | 'left',
150 | 'right',
151 | 'right',
152 | 'right',
153 | ],
154 | compactThreshold: 100,
155 | });
156 |
157 | // Add weekly data
158 | for (const data of weeklyData) {
159 | // Main row
160 | table.push([
161 | data.week,
162 | formatModelsDisplayMultiline(data.modelsUsed),
163 | formatNumber(data.inputTokens),
164 | formatNumber(data.outputTokens),
165 | formatNumber(data.cacheCreationTokens),
166 | formatNumber(data.cacheReadTokens),
167 | formatNumber(getTotalTokens(data)),
168 | formatCurrency(data.totalCost),
169 | ]);
170 |
171 | // Add model breakdown rows if flag is set
172 | if (ctx.values.breakdown) {
173 | pushBreakdownRows(table, data.modelBreakdowns);
174 | }
175 | }
176 |
177 | // Add empty row for visual separation before totals
178 | table.push([
179 | '',
180 | '',
181 | '',
182 | '',
183 | '',
184 | '',
185 | '',
186 | '',
187 | ]);
188 |
189 | // Add totals
190 | table.push([
191 | pc.yellow('Total'),
192 | '', // Empty for Models column in totals
193 | pc.yellow(formatNumber(totals.inputTokens)),
194 | pc.yellow(formatNumber(totals.outputTokens)),
195 | pc.yellow(formatNumber(totals.cacheCreationTokens)),
196 | pc.yellow(formatNumber(totals.cacheReadTokens)),
197 | pc.yellow(formatNumber(getTotalTokens(totals))),
198 | pc.yellow(formatCurrency(totals.totalCost)),
199 | ]);
200 |
201 | log(table.toString());
202 |
203 | // Show guidance message if in compact mode
204 | if (table.isCompactMode()) {
205 | logger.info('\nRunning in Compact Mode');
206 | logger.info('Expand terminal width to see cache metrics and total tokens');
207 | }
208 | }
209 | },
210 | });
211 |
--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env node
2 |
3 | /**
4 | * @fileoverview Main entry point for ccusage CLI tool
5 | *
6 | * This is the main entry point for the ccusage command-line interface tool.
7 | * It provides analysis of Claude Code usage data from local JSONL files.
8 | *
9 | * @module index
10 | */
11 |
12 | import './commands/index.ts';
13 |
--------------------------------------------------------------------------------
/src/logger.ts:
--------------------------------------------------------------------------------
1 | /**
2 | * @fileoverview Logging utilities for the ccusage application
3 | *
4 | * This module provides configured logger instances using consola for consistent
5 | * logging throughout the application with package name tagging.
6 | *
7 | * @module logger
8 | */
9 |
10 | import type { ConsolaInstance } from 'consola';
11 | import process from 'node:process';
12 | import { consola } from 'consola';
13 |
14 | import { name } from '../package.json';
15 |
16 | /**
17 | * Application logger instance with package name tag
18 | */
19 | export const logger: ConsolaInstance = consola.withTag(name);
20 |
21 | // Apply LOG_LEVEL environment variable if set
22 | if (process.env.LOG_LEVEL != null) {
23 | const level = Number.parseInt(process.env.LOG_LEVEL, 10);
24 | if (!Number.isNaN(level)) {
25 | logger.level = level;
26 | }
27 | }
28 |
29 | /**
30 | * Direct console.log function for cases where logger formatting is not desired
31 | */
32 | // eslint-disable-next-line no-console
33 | export const log = console.log;
34 |
--------------------------------------------------------------------------------
/test/statusline-test.json:
--------------------------------------------------------------------------------
1 | {
2 | "session_id": "test-session-123",
3 | "transcript_path": "/Users/test/.config/claude/projects/test-project/test-session-123/transcript.json",
4 | "cwd": "/Users/test/project",
5 | "model": {
6 | "id": "claude-opus-4-1-20250805",
7 | "display_name": "Opus 4.1"
8 | },
9 | "workspace": {
10 | "current_dir": "/Users/test/project",
11 | "project_dir": "/Users/test/project"
12 | }
13 | }
14 |
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
1 | {
2 | "compilerOptions": {
3 | "target": "ESNext",
4 | "jsx": "react-jsx",
5 | // Environment setup & latest features
6 | "lib": [
7 | "ESNext"
8 | ],
9 | "moduleDetection": "force",
10 | "module": "Preserve",
11 | // Bundler mode
12 | "moduleResolution": "bundler",
13 | "resolveJsonModule": true,
14 | "types": [
15 | "vitest/globals",
16 | "vitest/importMeta"
17 | ],
18 | "allowImportingTsExtensions": true,
19 | "allowJs": true,
20 | // Best practices
21 | "strict": true,
22 | "noFallthroughCasesInSwitch": true,
23 | "noImplicitOverride": true,
24 | "noPropertyAccessFromIndexSignature": false,
25 | "noUncheckedIndexedAccess": true,
26 | // Some stricter flags (disabled by default)
27 | "noUnusedLocals": false,
28 | "noUnusedParameters": false,
29 | "noEmit": true,
30 | "verbatimModuleSyntax": true,
31 | "erasableSyntaxOnly": true,
32 | "skipLibCheck": true
33 | },
34 | "exclude": [
35 | "dist"
36 | ]
37 | }
38 |
--------------------------------------------------------------------------------
/tsdown.config.ts:
--------------------------------------------------------------------------------
1 | import { defineConfig } from 'tsdown';
2 | import Macros from 'unplugin-macros/rolldown';
3 |
4 | export default defineConfig({
5 | entry: [
6 | './src/*.ts',
7 | '!./src/**/*.test.ts', // Exclude test files
8 | '!./src/_*.ts', // Exclude internal files with underscore prefix
9 | ],
10 | outDir: 'dist',
11 | format: 'esm',
12 | clean: true,
13 | sourcemap: false,
14 | minify: 'dce-only',
15 | treeshake: true,
16 | dts: {
17 | tsgo: true,
18 | resolve: ['type-fest'],
19 | },
20 | publint: true,
21 | unused: true,
22 | exports: true,
23 | nodeProtocol: true,
24 | plugins: [
25 | Macros({
26 | include: ['src/index.ts', 'src/pricing-fetcher.ts'],
27 | }),
28 | ],
29 | define: {
30 | 'import.meta.vitest': 'undefined',
31 | },
32 | onSuccess: 'sort-package-json',
33 | });
34 |
--------------------------------------------------------------------------------
/typos.toml:
--------------------------------------------------------------------------------
1 | [default]
2 | locale = 'en-us'
3 | extend-ignore-re = [
4 | "(?s)(#|//)\\s*spellchecker:off.*?\\n\\s*(#|//)\\s*spellchecker:on",
5 | "(?s)<!--\\s*spellchecker:off.*?\\n\\s*spellchecker:on\\s*-->",
6 | "(?Rm)^.*#\\s*spellchecker:disable-line
quot;,
7 | "(?m)^.*<!--\\s*spellchecker:disable-line\\s*-->\\n.*
quot;
8 | ]
9 |
10 | [default.extend-words]
11 | color = "color"
12 |
13 | [files]
14 | extend-exclude = [
15 | "node_modules",
16 | "biome.json"
17 | ]
18 |
--------------------------------------------------------------------------------
/vitest.config.ts:
--------------------------------------------------------------------------------
1 | import Macros from 'unplugin-macros/vite';
2 | import { defineConfig } from 'vitest/config';
3 |
4 | export default defineConfig({
5 | test: {
6 | watch: false,
7 | includeSource: ['src/**/*.{js,ts}'],
8 | globals: true,
9 | },
10 | plugins: [
11 | Macros({
12 | include: ['src/index.ts', 'src/pricing-fetcher.ts'],
13 | }),
14 | ],
15 | });
16 |
--------------------------------------------------------------------------------