English · 简体中文
Version 1.0.0 · October 2, 2026 · Changelog
See what happened in a Codex task, where time went, and how many tokens it used.
Codex Trajectory is a plugin that turns local Codex logs into a searchable event ledger and interactive timeline. Open it from a task's right panel or through the show_codex_trajectory MCP tool.
Captured from the current viewer on October 2, 2026, using synthetic demo data.
- Task history: messages, saved reasoning summaries, tool calls, subagent activity, and context compaction.
- Timing and failures: event durations, execution status, and a timeline to locate slow calls.
- Current task timing: active time for the open task, split into local/tool execution, estimated model/token time, and unattributed time, with percentages.
- Tokens and cost: task and turn totals, cache usage, and estimated cost.
- Live activity: a scrolling event stream, token totals, cost estimates, and the latest available local quota sample.
- History browsing: search, event filters, task switching, and earlier records, including compressed and paginated logs.
Steps are approximate, and reasoning summaries appear only when saved in the log. Cost figures are estimates based on bundled API prices, not a Codex subscription bill. Local quota samples may lag the account service.
You need Codex and uv. The plugin runs on macOS, Linux, and Windows.
codex plugin marketplace add icesixgod/codex-trajectory
codex plugin add codex-trajectory@icesixgodOpen a new Codex task to load the plugin. After updating an existing installation, fully quit and reopen Codex.
- Select + → More tools… → Plugins and MCPs → Codex Trajectory in the task's right panel, or ask Codex to show the task trajectory using
show_codex_trajectory. - Browse the timeline and event ledger. Use search and filters to find a record; select it to inspect it.
- Click Live window to follow activity, or Load earlier records to browse history.
- In either opened page, find Current task timing distribution below the top statistics and click Calculate task timing. Use Recalculate for a new snapshot of this task.
Timing reads the selected task's complete history, independently of loaded pages, and reuses its loaded summary index when available. It excludes gaps between turns and counts overlapping tools once. Tool time includes local commands, external tools, and call waits. Model/token time is an estimate that includes network, queueing, and scheduling waits, rather than a measurement of pure token generation. Missing and invalid tool timing are reported separately from zero and sub-millisecond durations. Only a missing/invalid tool's possible execution window remains unattributed; other time can still be estimated. Zero and below-precision durations count as 0 ms in this breakdown without blocking the rest of a turn.
The native task-panel entry opens without a model turn. With valid task context, the viewer opens that exact task; without available task context, it shows a local task selector. The plugin panel and MCP show tool use the same viewer, including current-task timing.
You can also ask Codex:
Show the safe trajectory summary for this Codex task.
For logs larger than the default 512 MiB read limit, choose a sufficient Read limit (GB) and click Enable and retry. The higher limit applies only to that task in the current panel; large logs take longer to scan.
The viewer starts with a safe summary: tool inputs, outputs, and raw metadata are hidden. Load full details asks for confirmation before exposing bounded details to the active conversation. Its checkbox can remember your choice for all tasks on this device; Restore safe summary default clears that preference. Live views always use safe summaries.
Source logs remain unchanged. Base instructions and encrypted reasoning are never returned. The Python runtime has no telemetry or application network requests; uv may download Python and dependencies during setup.
See PRIVACY.md for the complete privacy model.
| Tool | Use |
|---|---|
list_codex_sessions |
Find recent local tasks. |
get_codex_project_timing |
Read timing for the selected task only; original tool name retained for compatibility. |
get_codex_trajectory |
Read structured trajectory data. |
show_codex_trajectory |
Open the interactive viewer. |
Pass an explicit sessionId to read a specific task. Without one, the public read/show tools select the most recently modified active task, which may differ from the current task. See the interface reference for arguments, pagination, and schemas.
uv sync --group dev
uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytestSee CONTRIBUTING.md for browser tests and release checks, the native viewer guide for migration and troubleshooting, and CHANGELOG.md for changes.
MIT. Parts of the ledger, timeline, and inspector are adapted from DeepSeek's MIT-licensed DeepSeek Harness trajectory UI, copyright © 2026 DeepSeek. See NOTICE and the upstream license. This is an independent project, not affiliated with or endorsed by DeepSeek.
Friendly link: Linux.do