Skip to content

Commit 85f0b33

Browse files
committed
feat(codex): read saved exec JSON usage
Add CODEX_EXEC_LOG_DIR so ccusage can include JSONL files captured from codex exec --json alongside normal CODEX_HOME session logs. The Codex parser now accepts direct and nested usage payloads, keeps model and timestamp metadata when present, and falls back to the file timestamp for saved output lines that do not include one.
1 parent 4aedac0 commit 85f0b33

6 files changed

Lines changed: 241 additions & 24 deletions

File tree

‎apps/ccusage/src/adapter/codex/parser.ts‎

Lines changed: 181 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,17 @@ import {
2020
import { Result } from '@praha/byethrow';
2121
import { createFixture } from 'fs-fixture';
2222
import { logger } from '../../logger.ts';
23-
import { getCodexSessionsPaths } from './paths.ts';
23+
import { getCodexUsagePaths } from './paths.ts';
2424

2525
const LEGACY_FALLBACK_MODEL = 'gpt-5';
26-
const CODEX_JSONL_MARKERS = ['turn_context', '"type":"token_count"', '"type": "token_count"'];
26+
const CODEX_JSONL_MARKERS = [
27+
'turn_context',
28+
'"type":"token_count"',
29+
'"type": "token_count"',
30+
'"usage"',
31+
'"input_tokens"',
32+
'"prompt_tokens"',
33+
];
2734
const ENCODED_CODEX_EVENT_NUMBER_STRIDE = 5;
2835
const TOKEN_USAGE_EVENT_KEY_SEPARATOR = '\0';
2936

@@ -176,6 +183,84 @@ function extractModel(value: unknown): string | undefined {
176183
return asNonEmptyString(metadata?.model);
177184
}
178185

186+
function extractModelFromResult(value: unknown): string | undefined {
187+
const payload = asRecord(value);
188+
if (payload == null) {
189+
return undefined;
190+
}
191+
return (
192+
extractModel(payload) ??
193+
extractModel(payload.data) ??
194+
extractModel(payload.result) ??
195+
extractModel(payload.response)
196+
);
197+
}
198+
199+
function extractUsageRecord(value: unknown): Record<string, unknown> | null {
200+
const payload = asRecord(value);
201+
if (payload == null) {
202+
return null;
203+
}
204+
return (
205+
asRecord(payload.usage) ??
206+
asRecord(asRecord(payload.data)?.usage) ??
207+
asRecord(asRecord(payload.result)?.usage) ??
208+
asRecord(asRecord(payload.response)?.usage)
209+
);
210+
}
211+
212+
function normalizeTimestamp(value: unknown): string | undefined {
213+
if (typeof value === 'string' && value.trim() !== '') {
214+
const parsed = Date.parse(value);
215+
return Number.isNaN(parsed) ? undefined : new Date(parsed).toISOString();
216+
}
217+
if (typeof value !== 'number' || !Number.isFinite(value)) {
218+
return undefined;
219+
}
220+
const milliseconds = value > 10_000_000_000 ? value : value * 1000;
221+
const date = new Date(milliseconds);
222+
return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
223+
}
224+
225+
function extractTimestamp(value: unknown): string | undefined {
226+
const payload = asRecord(value);
227+
if (payload == null) {
228+
return undefined;
229+
}
230+
return (
231+
normalizeTimestamp(payload.timestamp) ??
232+
normalizeTimestamp(payload.created_at) ??
233+
normalizeTimestamp(payload.createdAt) ??
234+
normalizeTimestamp(asRecord(payload.data)?.timestamp) ??
235+
normalizeTimestamp(asRecord(payload.result)?.timestamp) ??
236+
normalizeTimestamp(asRecord(payload.response)?.timestamp)
237+
);
238+
}
239+
240+
function normalizeHeadlessUsage(value: unknown): RawUsage | null {
241+
const usage = extractUsageRecord(value);
242+
if (usage == null) {
243+
return null;
244+
}
245+
const input = ensureNumber(usage.input_tokens ?? usage.prompt_tokens ?? usage.input);
246+
const cached = ensureNumber(
247+
usage.cached_input_tokens ?? usage.cache_read_input_tokens ?? usage.cached_tokens,
248+
);
249+
const output = ensureNumber(usage.output_tokens ?? usage.completion_tokens ?? usage.output);
250+
const reasoning = ensureNumber(usage.reasoning_output_tokens ?? usage.reasoning_tokens);
251+
const total = ensureNumber(usage.total_tokens);
252+
if (input === 0 && cached === 0 && output === 0 && reasoning === 0 && total === 0) {
253+
return null;
254+
}
255+
return {
256+
input_tokens: input,
257+
cached_input_tokens: cached,
258+
output_tokens: output,
259+
reasoning_output_tokens: reasoning,
260+
total_tokens: total > 0 ? total : calculateFallbackTotalTokens(input, output, reasoning),
261+
};
262+
}
263+
179264
function extractTurnContextModelFast(line: string): string | undefined {
180265
if (!line.includes('"type":"turn_context"') && !line.includes('"type": "turn_context"')) {
181266
return undefined;
@@ -201,6 +286,13 @@ async function parseCodexSessionFile(
201286
let previousTotals: RawUsage | null = null;
202287
let currentModel: string | undefined;
203288
let currentModelIsFallback = false;
289+
const fileStatResult = await Result.try({
290+
try: stat(file),
291+
catch: (error) => error,
292+
});
293+
const fallbackTimestamp = Result.isFailure(fileStatResult)
294+
? new Date(0).toISOString()
295+
: fileStatResult.value.mtime.toISOString();
204296

205297
const addTokenCountEvent = (parsed: ParsedTokenCountLine): void => {
206298
let raw = parsed.lastUsage;
@@ -249,6 +341,35 @@ async function parseCodexSessionFile(
249341
});
250342
};
251343

344+
const addHeadlessUsageEvent = (entry: Record<string, unknown>): void => {
345+
const raw = normalizeHeadlessUsage(entry);
346+
if (raw == null) {
347+
return;
348+
}
349+
const modelFromEntry = extractModelFromResult(entry);
350+
if (modelFromEntry != null) {
351+
currentModel = modelFromEntry;
352+
currentModelIsFallback = false;
353+
}
354+
let isFallbackModel = false;
355+
let model = modelFromEntry ?? currentModel;
356+
if (model == null) {
357+
model = LEGACY_FALLBACK_MODEL;
358+
isFallbackModel = true;
359+
currentModel = model;
360+
currentModelIsFallback = true;
361+
} else if (modelFromEntry == null && currentModelIsFallback) {
362+
isFallbackModel = true;
363+
}
364+
events.push({
365+
sessionId,
366+
timestamp: extractTimestamp(entry) ?? fallbackTimestamp,
367+
model,
368+
...convertToEventUsage(raw),
369+
...(isFallbackModel ? { isFallbackModel: true } : {}),
370+
});
371+
};
372+
252373
try {
253374
await processJSONLFileByMarkers(
254375
file,
@@ -283,6 +404,7 @@ async function parseCodexSessionFile(
283404
}
284405
return;
285406
}
407+
addHeadlessUsageEvent(entry);
286408
if (entryType !== 'event_msg' || timestamp == null) {
287409
return;
288410
}
@@ -429,7 +551,7 @@ async function loadTokenUsageEventsFromDirectory(
429551

430552
export async function loadTokenUsageEvents(): Promise<TokenUsageEvent[]> {
431553
const directoryEvents = await Promise.all(
432-
getCodexSessionsPaths().map(loadTokenUsageEventsFromDirectory),
554+
getCodexUsagePaths().map(loadTokenUsageEventsFromDirectory),
433555
);
434556
return deduplicateTokenUsageEvents(directoryEvents.flat()).sort((a, b) =>
435557
compareStrings(a.timestamp, b.timestamp),
@@ -757,6 +879,62 @@ if (import.meta.vitest != null) {
757879
]);
758880
});
759881

882+
it('loads saved codex exec JSON usage from CODEX_EXEC_LOG_DIR', async () => {
883+
await using fixture = await createFixture({
884+
codex: {},
885+
exec: {
886+
'run.jsonl': [
887+
JSON.stringify({
888+
type: 'turn.completed',
889+
timestamp: '2026-01-02T03:04:05.000Z',
890+
model: 'gpt-5.2-codex',
891+
usage: {
892+
input_tokens: 120,
893+
cached_input_tokens: 20,
894+
output_tokens: 30,
895+
total_tokens: 150,
896+
},
897+
}),
898+
JSON.stringify({
899+
type: 'result',
900+
data: {
901+
timestamp: '2026-01-02T03:05:05.000Z',
902+
model_name: 'gpt-5.2-codex',
903+
usage: {
904+
prompt_tokens: 50,
905+
cached_tokens: 5,
906+
completion_tokens: 12,
907+
},
908+
},
909+
}),
910+
].join('\n'),
911+
},
912+
});
913+
vi.stubEnv('CODEX_HOME', fixture.getPath('codex'));
914+
vi.stubEnv('CODEX_EXEC_LOG_DIR', fixture.getPath('exec'));
915+
916+
await expect(loadTokenUsageEvents()).resolves.toMatchObject([
917+
{
918+
sessionId: 'run',
919+
timestamp: '2026-01-02T03:04:05.000Z',
920+
model: 'gpt-5.2-codex',
921+
inputTokens: 120,
922+
cachedInputTokens: 20,
923+
outputTokens: 30,
924+
totalTokens: 150,
925+
},
926+
{
927+
sessionId: 'run',
928+
timestamp: '2026-01-02T03:05:05.000Z',
929+
model: 'gpt-5.2-codex',
930+
inputTokens: 50,
931+
cachedInputTokens: 5,
932+
outputTokens: 12,
933+
totalTokens: 62,
934+
},
935+
]);
936+
});
937+
760938
it('deduplicates copied branch history across session files', async () => {
761939
const copiedHistory = [
762940
JSON.stringify({

‎apps/ccusage/src/adapter/codex/paths.ts‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import { createFixture } from 'fs-fixture';
66
import { normalizePathList } from '../path-list.ts';
77

88
export const CODEX_HOME_ENV = 'CODEX_HOME';
9+
export const CODEX_EXEC_LOG_DIR_ENV = 'CODEX_EXEC_LOG_DIR';
910
const DEFAULT_CODEX_DIR = path.join(os.homedir(), '.codex');
1011
const DEFAULT_SESSION_SUBDIR = 'sessions';
1112

@@ -17,14 +18,22 @@ export function getCodexSessionsPaths(): string[] {
1718
return getCodexHomePaths().map((codexHome) => path.join(codexHome, DEFAULT_SESSION_SUBDIR));
1819
}
1920

21+
export function getCodexExecLogPaths(): string[] {
22+
return normalizePathList(process.env[CODEX_EXEC_LOG_DIR_ENV], []);
23+
}
24+
25+
export function getCodexUsagePaths(): string[] {
26+
return [...getCodexSessionsPaths(), ...getCodexExecLogPaths()];
27+
}
28+
2029
export function getCodexSessionsPath(): string {
2130
return getCodexSessionsPaths()[0]!;
2231
}
2332

2433
export async function detectCodex(): Promise<boolean> {
2534
const results = await Promise.all(
26-
getCodexSessionsPaths().map(async (sessionsPath) =>
27-
hasFileRecursive(sessionsPath, { extension: '.jsonl' }),
35+
getCodexUsagePaths().map(async (usagePath) =>
36+
hasFileRecursive(usagePath, { extension: '.jsonl' }),
2837
),
2938
);
3039
return results.some(Boolean);
@@ -71,5 +80,22 @@ if (import.meta.vitest != null) {
7180
fixture2.getPath('sessions'),
7281
]);
7382
});
83+
84+
it('uses CODEX_EXEC_LOG_DIR for saved codex exec JSONL files', async () => {
85+
await using fixture = await createFixture({
86+
exec: {
87+
'run.jsonl': '{}',
88+
},
89+
});
90+
vi.stubEnv(CODEX_HOME_ENV, fixture.getPath('missing'));
91+
vi.stubEnv(CODEX_EXEC_LOG_DIR_ENV, fixture.getPath('exec'));
92+
93+
expect(getCodexExecLogPaths()).toEqual([fixture.getPath('exec')]);
94+
expect(getCodexUsagePaths()).toEqual([
95+
fixture.getPath('missing', 'sessions'),
96+
fixture.getPath('exec'),
97+
]);
98+
await expect(detectCodex()).resolves.toBe(true);
99+
});
74100
});
75101
}

‎docs/guide/codex/index.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,11 @@ Most users can start with unified reports such as `ccusage daily`. Add the `code
2525

2626
The CLI reads Codex session JSONL files located under `CODEX_HOME` (defaults to `~/.codex`). `CODEX_HOME` can be one directory or a comma-separated list of directories. Each file represents a single Codex CLI session and contains running token totals that the tool converts into per-day or per-month deltas.
2727

28+
Saved `codex exec --json` output can also be read from `CODEX_EXEC_LOG_DIR`. Point it at one directory or a comma-separated list of directories containing `.jsonl` files captured from `codex exec --json`.
29+
2830
```bash
2931
CODEX_HOME="$HOME/.codex,$HOME/.codex-work" ccusage codex daily
32+
CODEX_EXEC_LOG_DIR="$HOME/codex-exec-logs" ccusage codex daily
3033
```
3134

3235
## Report Views
@@ -55,10 +58,11 @@ These views support `--json`, `--compact`, `--offline`, and `--speed auto|standa
5558

5659
## Environment Variables
5760

58-
| Variable | Description |
59-
| ------------ | -------------------------------------------------------------------------------------------------- |
60-
| `CODEX_HOME` | Override the root directory, or comma-separated root directories, containing Codex session folders |
61-
| `LOG_LEVEL` | Adjust log verbosity (0 silent … 5 trace) |
61+
| Variable | Description |
62+
| -------------------- | -------------------------------------------------------------------------------------------------- |
63+
| `CODEX_HOME` | Override the root directory, or comma-separated root directories, containing Codex session folders |
64+
| `CODEX_EXEC_LOG_DIR` | Override one or more directories containing saved `codex exec --json` JSONL output files |
65+
| `LOG_LEVEL` | Adjust log verbosity (0 silent … 5 trace) |
6266

6367
When Codex emits a model alias (for example `gpt-5.5`), the CLI automatically resolves it through the LiteLLM pricing data when possible. No manual override is needed.
6468

‎docs/guide/environment-variables.md‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,20 @@ ccusage supports several environment variables for configuration and customizati
66

77
ccusage detects supported data source files from conventional locations by default. Set these variables when your data lives somewhere else. Each value can be one directory or a comma-separated list of directories:
88

9-
| Variable | Agent | Default |
10-
| ------------------- | ----------- | ---------------------------------- |
11-
| `CLAUDE_CONFIG_DIR` | Claude Code | `~/.config/claude` and `~/.claude` |
12-
| `CODEX_HOME` | Codex | `~/.codex` |
13-
| `OPENCODE_DATA_DIR` | OpenCode | `~/.local/share/opencode` |
14-
| `AMP_DATA_DIR` | Amp | `~/.local/share/amp` |
15-
| `PI_AGENT_DIR` | pi-agent | `~/.pi/agent/sessions` |
9+
| Variable | Agent | Default |
10+
| -------------------- | ----------- | ---------------------------------- |
11+
| `CLAUDE_CONFIG_DIR` | Claude Code | `~/.config/claude` and `~/.claude` |
12+
| `CODEX_HOME` | Codex | `~/.codex` |
13+
| `CODEX_EXEC_LOG_DIR` | Codex | unset |
14+
| `OPENCODE_DATA_DIR` | OpenCode | `~/.local/share/opencode` |
15+
| `AMP_DATA_DIR` | Amp | `~/.local/share/amp` |
16+
| `PI_AGENT_DIR` | pi-agent | `~/.pi/agent/sessions` |
1617

1718
Example:
1819

1920
```bash
2021
export CODEX_HOME="/path/to/codex,/archive/codex"
22+
export CODEX_EXEC_LOG_DIR="/path/to/codex-exec-jsonl"
2123
export OPENCODE_DATA_DIR="/path/to/opencode,/archive/opencode"
2224
export AMP_DATA_DIR="/path/to/amp,/archive/amp"
2325
export PI_AGENT_DIR="/path/to/pi/sessions,/archive/pi/sessions"
@@ -138,6 +140,7 @@ LOG_LEVEL=0 ccusage daily
138140

139141
# Set for current shell session
140142
export CODEX_HOME="/path/to/codex,/archive/codex"
143+
export CODEX_EXEC_LOG_DIR="/path/to/codex-exec-jsonl"
141144
ccusage daily
142145
```
143146

@@ -149,27 +152,31 @@ Add to your shell configuration file:
149152

150153
```bash
151154
export CODEX_HOME="$HOME/.codex"
155+
export CODEX_EXEC_LOG_DIR="$HOME/codex-exec-jsonl"
152156
export LOG_LEVEL=3
153157
```
154158

155159
#### Zsh (~/.zshrc)
156160

157161
```zsh
158162
export CODEX_HOME="$HOME/.codex"
163+
export CODEX_EXEC_LOG_DIR="$HOME/codex-exec-jsonl"
159164
export LOG_LEVEL=3
160165
```
161166

162167
#### Fish (~/.config/fish/config.fish)
163168

164169
```fish
165170
set -x CODEX_HOME "$HOME/.codex"
171+
set -x CODEX_EXEC_LOG_DIR "$HOME/codex-exec-jsonl"
166172
set -x LOG_LEVEL 3
167173
```
168174

169175
#### PowerShell (Profile.ps1)
170176

171177
```powershell
172178
$env:CODEX_HOME = "$env:USERPROFILE\.codex"
179+
$env:CODEX_EXEC_LOG_DIR = "$env:USERPROFILE\codex-exec-jsonl"
173180
$env:LOG_LEVEL = "3"
174181
```
175182

0 commit comments

Comments
 (0)