Skip to content

Commit d781670

Browse files
committed
docs(statusline): add cost source option documentation
Add comprehensive documentation for the new --cost-source option in statusline command: - Document all four cost source modes: auto, ccusage, cc, both - Add setup examples for settings.json configuration - Show output format differences for both mode - Explain when to use each mode with practical guidance - Update output format examples with both costs display References recent PRs: - feat(statusline): add costSource option to use Claude Code session cost (#571) - feat(statusline): add 'both' cost source option to display cc and ccusage costs (#574)
1 parent a5c4cc7 commit d781670

1 file changed

Lines changed: 74 additions & 1 deletion

File tree

‎docs/guide/statusline.md‎

Lines changed: 74 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,22 @@ You can enhance the burn rate display with visual indicators:
6060

6161
See [Visual Burn Rate](#visual-burn-rate) section for all available options.
6262

63+
### With Cost Source Options (Optional)
64+
65+
You can control how session costs are calculated and displayed:
66+
67+
```json
68+
{
69+
"statusLine": {
70+
"type": "command",
71+
"command": "bun x ccusage statusline --cost-source both", // Show both CC and ccusage costs
72+
"padding": 0
73+
}
74+
}
75+
```
76+
77+
See [Cost Source Options](#cost-source-options) section for all available modes.
78+
6379
## Output Format
6480

6581
The statusline displays a compact, single-line summary:
@@ -68,10 +84,16 @@ The statusline displays a compact, single-line summary:
6884
🤖 Opus | 💰 $0.23 session / $1.23 today / $0.45 block (2h 45m left) | 🔥 $0.12/hr | 🧠 25,000 (12%)
6985
```
7086

87+
When using `--cost-source both`, the session cost shows both Claude Code and ccusage calculations:
88+
89+
```
90+
🤖 Opus | 💰 ($0.25 cc / $0.23 ccusage) session / $1.23 today / $0.45 block (2h 45m left) | 🔥 $0.12/hr | 🧠 25,000 (12%)
91+
```
92+
7193
### Components Explained
7294

7395
- **Model** (`🤖 Opus`): Currently active Claude model
74-
- **Session Cost** (`💰 $0.23 session`): Cost for the current conversation session
96+
- **Session Cost** (`💰 $0.23 session`): Cost for the current conversation session (see [Cost Source Options](#cost-source-options) for different calculation modes)
7597
- **Today's Cost** (`$1.23 today`): Total cost for the current day across all sessions
7698
- **Session Block** (`$0.45 block (2h 45m left)`): Current 5-hour block cost with remaining time
7799
- **Burn Rate** (`🔥 $0.12/hr`): Cost burn rate per hour with color-coded indicators:
@@ -108,6 +130,57 @@ The statusline command:
108130
- Additional metrics display options
109131
- Session-specific cost tracking
110132

133+
### Cost Source Options
134+
135+
The `--cost-source` option controls how session costs are calculated and displayed:
136+
137+
**Available modes:**
138+
139+
- `auto` (default): Prefer Claude Code's pre-calculated cost when available, fallback to ccusage calculation
140+
- `ccusage`: Always calculate costs using ccusage's token-based calculation with LiteLLM pricing
141+
- `cc`: Always use Claude Code's pre-calculated cost from session data
142+
- `both`: Display both Claude Code and ccusage costs side by side for comparison
143+
144+
**Command-line usage:**
145+
146+
```bash
147+
# Default auto mode
148+
bun x ccusage statusline
149+
150+
# Always use ccusage calculation
151+
bun x ccusage statusline --cost-source ccusage
152+
153+
# Always use Claude Code cost
154+
bun x ccusage statusline --cost-source cc
155+
156+
# Show both costs for comparison
157+
bun x ccusage statusline --cost-source both
158+
```
159+
160+
**Settings.json configuration:**
161+
162+
```json
163+
{
164+
"statusLine": {
165+
"type": "command",
166+
"command": "bun x ccusage statusline --cost-source both",
167+
"padding": 0
168+
}
169+
}
170+
```
171+
172+
**When to use each mode:**
173+
174+
- **`auto`**: Best for most users, provides accurate costs with fallback reliability
175+
- **`ccusage`**: When you want consistent calculation methods across all ccusage commands
176+
- **`cc`**: When you trust Claude Code's cost calculations and want minimal processing
177+
- **`both`**: For debugging cost discrepancies or comparing calculation methods
178+
179+
**Output differences:**
180+
181+
- **Single cost modes** (`auto`, `ccusage`, `cc`): `💰 $0.23 session`
182+
- **Both mode**: `💰 ($0.25 cc / $0.23 ccusage) session`
183+
111184
## Configuration
112185

113186
### Environment Variables

0 commit comments

Comments
 (0)