Skip to content

Commit b7d4cfc

Browse files
a-c-mclaude
a-c-m
and
claude
committed
feat: add 5-hour blocks report command
Implements a new `blocks` command to analyze Claude Code usage in 5-hour billing windows as requested in #23: - Track active blocks with time remaining and burn rate projections - Support token limits with `-t` parameter (including `-t max` for highest previous block) - Add `--recent` flag to show last 3 days of blocks - Add `--active` flag for detailed view of current active block - Include REMAINING and PROJECTED rows in table view with percentage tracking - Fix max token calculation to include all blocks (not filtering synthetic models) - Update README with blocks command documentation The blocks report helps users understand: - When their 5-hour session windows start and end - How many tokens they've used vs their limit - Projected usage if current burn rate continues - Time remaining in active sessions Fixes #23 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
1 parent 932b9ec commit b7d4cfc

File tree

6 files changed

+9197
-0
lines changed

6 files changed

+9197
-0
lines changed

‎README.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -216,6 +216,49 @@ ccusage session --order desc # Show newest sessions first (default)
216216
ccusage session --breakdown # Show cost breakdown by model
217217
```
218218

219+
### 5-Hour Blocks Report
220+
221+
Shows usage grouped by Claude's 5-hour billing windows:
222+
223+
```bash
224+
# Show all 5-hour blocks
225+
ccusage blocks
226+
227+
# Show only the active block with detailed projections
228+
ccusage blocks --active
229+
230+
# Show blocks from the last 3 days (including active)
231+
ccusage blocks --recent
232+
233+
# Set a token limit to see if you'll exceed it
234+
ccusage blocks -t 500000
235+
236+
# Use the highest previous block as the token limit
237+
ccusage blocks -t max
238+
239+
# Combine options
240+
ccusage blocks --recent -t max
241+
242+
# Output in JSON format
243+
ccusage blocks --json
244+
245+
# Control cost calculation mode
246+
ccusage blocks --mode auto # Use costUSD when available, calculate otherwise (default)
247+
ccusage blocks --mode calculate # Always calculate costs from tokens
248+
ccusage blocks --mode display # Always show pre-calculated costUSD values
249+
250+
# Control sort order
251+
ccusage blocks --order asc # Show oldest blocks first
252+
ccusage blocks --order desc # Show newest blocks first (default)
253+
```
254+
255+
The blocks report helps you understand Claude Code's 5-hour rolling session windows:
256+
257+
- Sessions start with your first message and last for 5 hours
258+
- Shows active blocks with time remaining and burn rate projections
259+
- Helps track if you're approaching token limits within a session
260+
- The `-t max` option automatically uses your highest previous session as the limit
261+
219262
### Options
220263

221264
All commands support the following options:

0 commit comments

Comments
 (0)