Skip to content

Commit 34c697b

Browse files
authored
feat(codex): add usage breakdowns by originator
Adds opt-in originator breakdowns while preserving default output and deterministic deduplication.
1 parent 033d25e commit 34c697b

37 files changed

Lines changed: 2226 additions & 173 deletions

‎apps/ccusage/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,7 @@ bunx ccusage statusline # Claude Code status line for hooks (Beta)
121121
# Source-focused reports and options
122122
bunx ccusage claude daily --mode display
123123
bunx ccusage codex daily --speed fast
124+
bunx ccusage codex daily --by-source
124125
bunx ccusage opencode weekly
125126
bunx ccusage amp session
126127
bunx ccusage droid daily
@@ -141,6 +142,7 @@ bunx ccusage pi daily --pi-path /path/to/sessions,/archive/pi/sessions
141142
bunx ccusage daily --all
142143
bunx ccusage daily --sections daily,monthly,session --json
143144
bunx ccusage daily --by-agent --json
145+
bunx ccusage daily --by-source --json
144146

145147
# Filters and options
146148
bunx ccusage daily --since 2026-04-25 --until 2026-05-16

‎apps/ccusage/config-schema.json‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2635,6 +2635,12 @@
26352635
"markdownDescription": "Show per-model cost breakdown.",
26362636
"type": "boolean"
26372637
},
2638+
"bySource": {
2639+
"default": false,
2640+
"description": "Include usage breakdowns by Codex client or originator.",
2641+
"markdownDescription": "Include usage breakdowns by Codex client or originator.",
2642+
"type": "boolean"
2643+
},
26382644
"color": {
26392645
"description": "Enable colored output.",
26402646
"markdownDescription": "Enable colored output.",
@@ -2794,6 +2800,12 @@
27942800
"markdownDescription": "Show per-model cost breakdown.",
27952801
"type": "boolean"
27962802
},
2803+
"bySource": {
2804+
"default": false,
2805+
"description": "Include usage breakdowns by Codex client or originator.",
2806+
"markdownDescription": "Include usage breakdowns by Codex client or originator.",
2807+
"type": "boolean"
2808+
},
27972809
"color": {
27982810
"description": "Enable colored output.",
27992811
"markdownDescription": "Enable colored output.",
@@ -2953,6 +2965,12 @@
29532965
"markdownDescription": "Show per-model cost breakdown.",
29542966
"type": "boolean"
29552967
},
2968+
"bySource": {
2969+
"default": false,
2970+
"description": "Include usage breakdowns by Codex client or originator.",
2971+
"markdownDescription": "Include usage breakdowns by Codex client or originator.",
2972+
"type": "boolean"
2973+
},
29562974
"color": {
29572975
"description": "Enable colored output.",
29582976
"markdownDescription": "Enable colored output.",
@@ -3115,6 +3133,12 @@
31153133
"markdownDescription": "Show per-model cost breakdown.",
31163134
"type": "boolean"
31173135
},
3136+
"bySource": {
3137+
"default": false,
3138+
"description": "Include usage breakdowns by Codex client or originator.",
3139+
"markdownDescription": "Include usage breakdowns by Codex client or originator.",
3140+
"type": "boolean"
3141+
},
31183142
"color": {
31193143
"description": "Enable colored output.",
31203144
"markdownDescription": "Enable colored output.",

‎docs/guide/all-reports.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,10 @@ For automation, unified JSON reports can emit several report sections from one l
2828
```bash
2929
ccusage daily --sections daily,monthly,session --json
3030
ccusage daily --by-agent --json
31+
ccusage daily --by-source --json
3132
```
3233

33-
`--sections` accepts `daily`, `weekly`, `monthly`, and `session`. The invoked report section is always included, and table output prints each requested section as a separate table. `--by-agent` adds an `agents` array to daily, weekly, and monthly JSON rows; session rows are already source-specific.
34+
`--sections` accepts `daily`, `weekly`, `monthly`, and `session`. The invoked report section is always included, and table output prints each requested section as a separate table. `--by-agent` adds an `agents` array to daily, weekly, and monthly JSON rows; session rows are already source-specific. `--by-source` adds Codex client/originator breakdowns to unified JSON rows and totals, and adds indented source rows to unified tables. Codex maps known originators to `CLI`, `Exec`, `Desktop App`, `VS Code`, and `SDK`, preserves unknown values, and groups missing or empty values under `Uncategorized`.
3435

3536
## How Unified Views Work
3637

‎docs/guide/cli-options.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -164,9 +164,12 @@ ccusage daily --sections daily,monthly,session --json
164164

165165
# Add per-agent breakdowns to daily, weekly, and monthly JSON rows
166166
ccusage daily --by-agent --json
167+
168+
# Add Codex client/originator breakdowns to unified output
169+
ccusage daily --by-source --json
167170
```
168171

169-
`--sections` accepts a comma-separated list of `daily`, `weekly`, `monthly`, and `session`. The invoked report section is always included. For table output, each requested section is printed as a separate table. `--by-agent` is JSON-only; session rows are already per-agent.
172+
`--sections` accepts a comma-separated list of `daily`, `weekly`, `monthly`, and `session`. The invoked report section is always included. For table output, each requested section is printed as a separate table. `--by-agent` is JSON-only; session rows are already per-agent. `--by-source` is opt-in and applies to Codex-focused reports and unified reports. It adds `sourceBreakdowns` to JSON and source rows to tables while leaving output unchanged when omitted.
170173

171174
### Daily Command
172175

‎docs/guide/codex/index.md‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,16 @@ CODEX_HOME="$HOME/.codex,$HOME/.codex-work,$HOME/codex-exec-logs" ccusage codex
3737
| `ccusage codex monthly` | Aggregate usage by month | [Monthly Usage](/guide/monthly-reports) |
3838
| `ccusage codex session` | Group usage by Codex session | [Session Usage](/guide/session-reports) |
3939

40-
These views support `--json`, `--compact`, `--offline`, and `--speed auto|standard|fast`.
40+
These views support `--json`, `--compact`, `--offline`, `--speed auto|standard|fast`, and the opt-in `--by-source` breakdown.
41+
42+
`--by-source` groups Codex usage by the `session_meta.payload.originator` value. The built-in
43+
labels are `CLI` (`codex-tui` and `codex_cli_rs`), `Exec` (`codex_exec`), and `Desktop App`
44+
(`Codex Desktop` and `codex_work_desktop`), `VS Code` (`codex_vscode`), and `SDK`
45+
(`codex_python_sdk`); other non-empty values are kept unchanged, while missing or empty values
46+
are reported as `Uncategorized`. Same-source copies of a usage event are deduplicated, while
47+
different normalized originators remain distinct so their totals are preserved. Tables add source
48+
rows below each period, and JSON adds `sourceBreakdowns` to the period and totals objects without
49+
changing the default output.
4150

4251
## Monthly Example
4352

@@ -79,6 +88,9 @@ ccusage codex daily --speed fast
7988

8089
# Force standard pricing
8190
ccusage codex daily --speed standard
91+
92+
# Show usage by Codex client/originator
93+
ccusage codex daily --by-source
8294
```
8395

8496
## JSON Output
@@ -89,9 +101,10 @@ Codex focused views use the same JSON mode as the shared reports:
89101
ccusage codex daily --json
90102
ccusage codex monthly --json
91103
ccusage codex session --json
104+
ccusage codex daily --by-source --json
92105
```
93106

94-
Session JSON includes per-model breakdowns, cached token counts, `lastActivity`, and `isFallback` flags for any events that required the legacy `gpt-5` pricing fallback.
107+
Session JSON includes per-model breakdowns, cached token counts, `lastActivity`, and `isFallback` flags for any events that required the legacy `gpt-5` pricing fallback. With `--by-source`, each source breakdown has the same token and model totals, and source totals conserve the report totals exactly.
95108

96109
Have feedback or ideas? [Open an issue](https://github.com/ccusage/ccusage/issues/new) so we can improve Codex support.
97110

‎docs/guide/config-files.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -192,7 +192,8 @@ Use data source namespaces to set defaults and report overrides. Supported names
192192
"codex": {
193193
"defaults": {
194194
"json": true,
195-
"offline": true
195+
"offline": true,
196+
"bySource": true
196197
},
197198
"commands": {
198199
"daily": {
@@ -280,7 +281,7 @@ ccusage copilot monthly
280281
ccusage gemini daily
281282
```
282283

283-
Source-specific settings are also applied when running unified reports such as `ccusage daily`. In that case, each source receives its own merged options before data is loaded.
284+
Source-specific report settings apply only to the focused commands shown above. In particular, `codex.defaults.bySource` is honored only by focused Codex commands. Unified reports such as `ccusage daily` do not apply agent-specific options; use the unified `--by-source` flag to request Codex client/originator breakdowns there.
284285

285286
Use `pi.stores` for additional pi-format session stores, such as tools or forks that write sessions outside `~/.pi/agent/sessions`. Named stores are additive to the default `pi` agent in unified reports, use their own agent name in JSON and tables, and prefix models with `[name]` followed by a space. Store names must match `^[a-z][a-z0-9_-]{0,31}$`, must be unique, and cannot use a built-in agent name. Each store path can be one sessions directory or a comma-separated list; `~` is expanded for store paths, nonexistent paths are treated as empty, and resolved paths that overlap the default `pi` store or another named store — including one path nested inside another — are rejected. They do not create focused commands such as `ccusage omp daily`; `PI_AGENT_DIR`, `--pi-path`, and `pi.defaults.piPath` still affect only the default `pi` agent.
286287

‎docs/guide/configuration.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,8 @@ Configure Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-a
128128
"codex": {
129129
"defaults": {
130130
"json": true,
131-
"offline": true
131+
"offline": true,
132+
"bySource": true
132133
},
133134
"commands": {
134135
"daily": {
@@ -140,7 +141,7 @@ Configure Claude Code, Codex, OpenCode, Amp, Droid, Codebuff, Hermes Agent, pi-a
140141
}
141142
```
142143

143-
Source sections apply to focused commands such as `ccusage codex daily` and `ccusage amp session`. They are also used by unified reports such as `ccusage daily`, where each source receives its own merged options before data is loaded.
144+
Source sections apply to focused commands such as `ccusage codex daily` and `ccusage amp session`. The `codex.defaults.bySource` option is honored only by focused Codex commands; unified reports such as `ccusage daily` do not apply agent-specific options. Use the unified `--by-source` flag to request Codex client/originator breakdowns there.
144145

145146
### Team Collaboration
146147

‎docs/guide/json-output.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,10 @@ Unified reports also support JSON-oriented flags for dashboard-style consumers:
3333

3434
```bash
3535
ccusage daily --sections daily,monthly,session --by-agent --json
36+
ccusage daily --by-source --json
3637
```
3738

38-
`--sections` emits each requested unified section from one load. The invoked command's section is always included, and the top-level `totals` object remains the total for that invoked section. JSON keys are emitted with the invoked section first, then remaining sections in `daily`, `weekly`, `monthly`, `session` order, with `totals` last. `--by-agent` adds an `agents` array to daily, weekly, and monthly rows; session rows are already per-agent.
39+
`--sections` emits each requested unified section from one load. The invoked command's section is always included, and the top-level `totals` object remains the total for that invoked section. JSON keys are emitted with the invoked section first, then remaining sections in `daily`, `weekly`, `monthly`, `session` order, with `totals` last. `--by-agent` adds an `agents` array to daily, weekly, and monthly rows; session rows are already per-agent. `--by-source` adds `sourceBreakdowns` to Codex rows and the applicable totals. Focused Codex JSON uses the same field name. Source token and cost totals conserve their containing Codex totals; known originators are normalized to `CLI`, `Exec`, `Desktop App`, `VS Code`, or `SDK`, while unknown originators remain unchanged and missing or empty values use `Uncategorized`.
3940

4041
```json
4142
{

0 commit comments

Comments
 (0)