Add profile usage summary command

[Hobeom]

Summary

• add aimux usage to summarize transcript token usage by profile
• support --profile, --since, and --all filters
• deduplicate repeated transcript entries by request id and surface unmapped sessions as unknown
• document the new command in the README

Notes

This builds on the existing session attribution logic from .claude.json and aimux session history. Historical shared transcripts that cannot be mapped to a profile are intentionally shown as unknown rather than guessed.

Closes #1

Test plan

• npm test
• npm run build
• node dist/cli.js usage --since 24h

[shahinyanm1-work]

Thanks for picking this up — the structure is good and the tests are a nice touch. Two things blocking the merge plus a couple of smaller notes.

Blockers

1. requestKey includes sessionId, so when a session gets forked (claude --resume <id> --fork-session, which aimux does automatically on cross-profile attach), the original transcript and the forked one share the same requestId but live under different session ids. The dedupe key treats them as two requests and double-counts the tokens. Drop sessionId from the key when a requestId is present — request:<requestId> is enough.

2. The walker reads every .jsonl under projects/ without filtering subagent transcripts. Real installs have thousands of those (classifier, memory, task-journal, etc.) — each one is a real assistant turn with message.usage, so they'll inflate "unknown" by a huge factor. sessionScanner.ts already has the logic — quickFirstLineType(path) === 'queue-operation' and parseSessionJsonl(path).isSubagent. Reuse those before parsing usage lines.

Should fix before merge

3. estimatedCostUsd is summed into the summary but never shown in the table. Either add a COST column (formatted as $X.XX) or drop the field — right now it's dead work.

4. In requestKey, the fallback when no id/uuid/requestId is found is Math.random(). That defeats the dedupe — every line gets a unique key. Either use a stable surrogate like ${sessionId}:line:${index} or just continue and skip the line.

Nit

5. usage.test.ts calls setAimuxDir in beforeEach but never restores it. If something else in the test run depends on the default aimux dir, it'll pick up the tmpdir from this test. Save the previous value and restore in afterEach.

Happy to discuss any of these if my read of the code is off. Once 1 and 2 are sorted I'll take another pass.

Re-posting from primary maintainer account.

[Shahinyanm]

Thanks for picking this up — structure is good and the tests are a nice touch. Two things blocking the merge plus a couple of smaller notes.

Blockers

1. requestKey includes sessionId, so when a session gets forked (claude --resume <id> --fork-session, which aimux does automatically on cross-profile attach), the original transcript and the forked one share the same requestId but live under different session ids. The dedupe key treats them as two requests and double-counts the tokens. Drop sessionId from the key when a requestId is present — request:<requestId> is enough.

2. The walker reads every .jsonl under projects/ without filtering subagent transcripts. Real installs have thousands of those (classifier, memory, task-journal, etc.) — each one is a real assistant turn with message.usage, so they'll inflate "unknown" by a huge factor. sessionScanner.ts already has the logic — quickFirstLineType(path) === 'queue-operation' and parseSessionJsonl(path).isSubagent. Reuse those before parsing usage lines.

Should fix before merge

3. estimatedCostUsd is summed into the summary but never shown in the table. Either add a COST column (formatted as $X.XX) or drop the field — right now it's dead work.

4. In requestKey, the fallback when no id/uuid/requestId is found is Math.random(). That defeats the dedupe — every line gets a unique key. Either use a stable surrogate like ${sessionId}:line:${index} or just continue and skip the line.

Nit

5. usage.test.ts calls setAimuxDir in beforeEach but never restores it. If something else in the test run depends on the default aimux dir, it'll pick up the tmpdir from this test. Save the previous value and restore in afterEach.

Happy to discuss any of these if my read is off. Once 1 and 2 are sorted I'll take another pass.

[Hobeom]

Thanks for the careful review. I updated the branch to address each item.

Blockers

1. requestKey includes sessionId

Fixed by changing the requestId path to use request:<requestId> without sessionId. This keeps forked transcripts that share the same request id from being counted twice. I also added coverage for the forked-session case.

2. The walker reads every .jsonl under projects/ without filtering subagent transcripts

Fixed by reusing the existing scanner checks before parsing usage lines: the fast quickFirstLineType(filePath) === 'queue-operation' check, followed by parseSessionJsonl(filePath).isSubagent.

Should fix before merge

3. estimatedCostUsd is summed but not shown

Kept estimatedCostUsd and surfaced it in the output table as a COST column formatted as $X.XX.

4. Math.random() fallback defeats dedupe

Replaced the random fallback with a stable ${sessionId}:line:${lineIndex} key.

Nit

5. setAimuxDir is not restored in tests

The usage tests now save the previous aimux dir and restore it in afterEach.

I also included one usage-specific hardening case: malformed or non-numeric usage values are ignored instead of corrupting totals, with test coverage.

Validation:

• npm test — 100 passed
• npm run build
• node dist/cli.js usage --since 24h