Skip to content

Commit 04599a8

Browse files
committed
docs(claude): document sidechain dedupe
Document Claude Code /btw side question logs, the isSidechain field used by ccusage, and issue #913 as the motivation for sidechain replay deduplication. Add short comments at the message-only fallback so the daily and full Claude loaders explain why sidechain duplicates can match by message ID when request IDs differ.
1 parent b5b27d2 commit 04599a8

3 files changed

Lines changed: 16 additions & 0 deletions

File tree

‎rust/crates/ccusage/src/adapter/claude/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,20 @@ projects/{project}/{sessionId}.jsonl
1616

1717
`projects/` is scanned recursively, so both nested session directories and legacy flat JSONL files can be loaded.
1818

19+
Sidechain entries:
20+
21+
- Claude Code may write `isSidechain: true` entries for isolated sidechain
22+
conversations such as `/btw` `aside_question` logs under `subagents/`. See
23+
the Claude Code
24+
[side questions documentation](https://code.claude.com/docs/en/interactive-mode#side-questions-with-btw).
25+
- These files can replay parent conversation messages with the same message ID
26+
but a different request ID, including the parent cache-read usage.
27+
- ccusage keeps the parent entry and drops the replayed sidechain copy when at
28+
least one duplicate carries `isSidechain: true`. Distinct sidechain responses
29+
with their own message IDs are still counted.
30+
- This behavior fixes the overcounting reported in
31+
[#913](https://github.com/ryoppippi/ccusage/issues/913).
32+
1933
The term `session` has two meanings in this codebase:
2034

2135
- Session report grouping uses project directories.

‎rust/crates/ccusage/src/adapter/claude/daily.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -365,6 +365,7 @@ fn push_deduped_daily_entry(
365365
})
366366
})
367367
.or_else(|| {
368+
// /btw sidechain logs can replay parent messages with new request IDs.
368369
let message_hash = usage_dedupe_hash(message_id, None);
369370
let candidate_is_sidechain = is_sidechain_daily_entry(&entry);
370371
deduped_indexes.get(&message_hash).and_then(|indexes| {

‎rust/crates/ccusage/src/adapter/claude/mod.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -247,6 +247,7 @@ fn push_deduped_entry(
247247
})
248248
})
249249
.or_else(|| {
250+
// /btw sidechain logs can replay parent messages with new request IDs.
250251
let message_hash = usage_dedupe_hash(message_id, None);
251252
let candidate_is_sidechain = is_sidechain_usage_entry(&entry.data);
252253
deduped_indexes.get(&message_hash).and_then(|indexes| {

0 commit comments

Comments
 (0)