Skip to content

Commit 105a10f

Browse files
authored
Merge branch 'main' into main
2 parents 9998ee2 + 6a66a7c commit 105a10f

16 files changed

Lines changed: 457 additions & 321 deletions

‎.mcp.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,14 @@
2222
"@eslint/mcp@latest"
2323
],
2424
"env": {}
25+
},
26+
"@praha/byethrow": {
27+
"type": "stdio",
28+
"command": "bun",
29+
"args": [
30+
"byethrow-mcp"
31+
],
32+
"env": {}
2533
}
2634
}
2735
}

‎CLAUDE.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,16 @@ This is a CLI tool that analyzes Claude Code usage data from local JSONL files s
109109
- File paths always use Node.js path utilities for cross-platform compatibility
110110
- **Import conventions**: Use `.ts` extensions for local file imports (e.g., `import { foo } from './utils.ts'`)
111111

112+
**Error Handling:**
113+
114+
- **Prefer @praha/byethrow Result type** over traditional try-catch for functional error handling
115+
- Use `Result.try()` for wrapping operations that may throw (JSON parsing, etc.)
116+
- Use `Result.isFailure()` for checking errors (more readable than `!Result.isSuccess()`)
117+
- Use early return pattern (`if (Result.isFailure(result)) continue;`) instead of ternary operators
118+
- For async operations: create wrapper function with `Result.try()` then call it
119+
- Keep traditional try-catch only for: file I/O with complex error handling, legacy code that's hard to refactor
120+
- Always use `Result.isFailure()` and `Result.isSuccess()` type guards for better code clarity
121+
112122
**Naming Conventions:**
113123

114124
- Variables: start with lowercase (camelCase) - e.g., `usageDataSchema`, `modelBreakdownSchema`

‎README.md‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,24 @@
2222

2323
### Quick Start (Recommended)
2424

25-
Run directly without installation:
25+
Thanks to ccusage's incredibly small bundle size ([![install size](https://packagephobia.com/badge?p=ccusage)](https://packagephobia.com/result?p=ccusage)), you can run it directly without installation:
2626

2727
```bash
28+
# Using bunx (recommended for speed)
29+
bunx ccusage
30+
31+
# Using npx
2832
npx ccusage@latest
33+
34+
# Using deno (with security flags)
35+
deno run -E -R=$HOME/.claude/projects/ -S=homedir -N='raw.githubusercontent.com:443' npm:ccusage@latest
2936
```
3037

31-
### Local Installation
38+
> 💡 **Tip**: We recommend using `bunx` instead of `npx` for a massive speed improvement!
39+
40+
### Local Installation (Optional)
41+
42+
Since ccusage has such a small bundle size, installation is entirely optional:
3243

3344
```bash
3445
npm install -g ccusage
@@ -72,6 +83,7 @@ ccusage daily --breakdown # Per-model cost breakdown
7283
- 🔄 **Cache Token Support**: Tracks and displays cache creation and cache read tokens separately
7384
- 🌐 **Offline Mode**: Use pre-cached pricing data without network connectivity with `--offline` (Claude models only)
7485
- 🔌 **MCP Integration**: Built-in Model Context Protocol server for integration with other tools
86+
- 🚀 **Ultra-Small Bundle**: Unlike other CLI tools, we pay extreme attention to bundle size - incredibly small even without minification!
7587

7688
## Documentation
7789

‎bun.lock‎

Lines changed: 38 additions & 32 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/guide/getting-started.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,10 @@ ccusage monthly --json > usage-data.json
100100
ccusage blocks --live
101101
```
102102

103+
## Colors
104+
105+
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.
106+
103107
## Troubleshooting
104108

105109
### No Data Found

‎docs/guide/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,10 @@ graph LR
4141

4242
## Key Features
4343

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+
4448
### 📊 Multiple Report Types
4549

4650
- **Daily Reports** - Usage aggregated by calendar date

‎docs/guide/installation.md‎

Lines changed: 33 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,27 @@
22

33
ccusage can be installed and used in several ways depending on your preferences and use case.
44

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+
514
## Quick Start (Recommended)
615

7-
The fastest way to try ccusage is to run it directly without installation:
16+
The fastest way to use ccusage is to run it directly:
817

918
::: code-group
1019

11-
```bash [npx]
12-
npx ccusage@latest
20+
```bash [bunx (Recommended)]
21+
bunx ccusage
1322
```
1423

15-
```bash [bunx]
16-
bunx ccusage
24+
```bash [npx]
25+
npx ccusage@latest
1726
```
1827

1928
```bash [pnpm]
@@ -26,16 +35,28 @@ deno run -E -R=$HOME/.claude/projects/ -S=homedir -N='raw.githubusercontent.com:
2635

2736
:::
2837

29-
This approach:
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:
3049

31-
- ✅ Always uses the latest version
32-
- ✅ No global installation required
33-
- ✅ Works across different systems
34-
- ✅ Perfect for occasional use
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 |
3556

36-
## Global Installation
57+
## Global Installation (Optional)
3758

38-
If you use ccusage frequently, install it globally:
59+
While not necessary due to our small bundle size, you can still install ccusage globally if you prefer:
3960

4061
::: code-group
4162

‎docs/guide/related-projects.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Projects that use ccusage internally or extend its functionality:
77
- [claude-usage-tracker-for-mac](https://github.com/penicillin0/claude-usage-tracker-for-mac) - macOS menu bar app for tracking Claude usage
88
- [ClaudeCode_Dashboard](https://github.com/m-sigepon/ClaudeCode_Dashboard) - Web dashboard with charts and visualizations
99
- [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.
1011

1112
## Extensions & Integrations
1213

‎docs/package.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,13 @@
1717
"devDependencies": {
1818
"@types/bun": "^1.2.17",
1919
"tinyglobby": "^0.2.14",
20-
"typedoc": "^0.28.5",
20+
"typedoc": "^0.28.6",
2121
"typedoc-plugin-markdown": "^4.7.0",
2222
"typedoc-vitepress-theme": "^1.1.2",
2323
"vitepress": "^1.6.3",
2424
"vitepress-plugin-group-icons": "^1.6.0",
25-
"vitepress-plugin-llms": "^1.5.1",
25+
"vitepress-plugin-llms": "^1.6.0",
2626
"vitepress-plugin-mermaid": "^2.0.17",
27-
"wrangler": "^4.20.5"
27+
"wrangler": "^4.22.0"
2828
}
2929
}

‎package.json‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,9 @@
3535
".",
3636
"docs"
3737
],
38+
"engines": {
39+
"node": ">=20.19.3"
40+
},
3841
"scripts": {
3942
"build": "tsdown",
4043
"docs:build": "cd docs && bun run build",
@@ -57,30 +60,32 @@
5760
"@hono/mcp": "^0.1.0",
5861
"@hono/node-server": "^1.14.4",
5962
"@jsr/std__async": "1",
60-
"@modelcontextprotocol/sdk": "^1.13.1",
61-
"@oxc-project/runtime": "^0.74.0",
63+
"@modelcontextprotocol/sdk": "^1.13.2",
64+
"@oxc-project/runtime": "^0.75.0",
65+
"@praha/byethrow": "^0.3.0",
66+
"@praha/byethrow-mcp": "^0.0.7",
6267
"@ryoppippi/eslint-config": "^0.3.7",
6368
"@types/bun": "^1.2.17",
64-
"@typescript/native-preview": "^7.0.0-dev.20250623.1",
69+
"@typescript/native-preview": "^7.0.0-dev.20250629.1",
6570
"ansi-escapes": "^7.0.0",
6671
"bumpp": "^10.2.0",
6772
"clean-pkg-json": "^1.3.0",
6873
"cli-table3": "^0.6.5",
6974
"consola": "^3.4.2",
70-
"es-toolkit": "^1.39.4",
71-
"eslint": "^9.29.0",
75+
"es-toolkit": "^1.39.5",
76+
"eslint": "^9.30.0",
7277
"eslint-plugin-format": "^1.0.1",
7378
"fast-sort": "^3.4.1",
7479
"fs-fixture": "^2.8.1",
7580
"gunshi": "^0.26.3",
76-
"hono": "^4.8.2",
81+
"hono": "^4.8.3",
7782
"lint-staged": "^16.1.2",
7883
"path-type": "^6.0.0",
7984
"picocolors": "^1.1.1",
8085
"pretty-ms": "^9.2.0",
8186
"publint": "^0.3.12",
8287
"simple-git-hooks": "^2.13.0",
83-
"sort-package-json": "^3.2.1",
88+
"sort-package-json": "^3.3.1",
8489
"string-width": "^7.2.0",
8590
"tinyglobby": "^0.2.14",
8691
"tsdown": "^0.12.9",

0 commit comments

Comments
 (0)