Read this in 简体中文.
Codex Trajectory is a read-only Codex plugin that turns local task logs into a privacy-aware event ledger and interactive timeline. It shows turns, approximate model steps, reasoning summaries, assistant messages, tool timing, subagents, compaction, token usage, and failures without changing the original logs.
Prerequisites: Codex and uv on macOS, Linux, or Windows.
codex plugin marketplace add icesixgod/codex-trajectory
codex plugin add codex-trajectory@icesixgodOpen a new Codex task so the installed tools and skill are loaded. Then ask:
Show the safe trajectory summary for this Codex task.
Safe summary mode is the default. It returns event names, timing, status, token usage, and bounded summaries while hiding tool inputs, tool outputs, raw record metadata, absolute log paths, Git remotes, base instructions, and encrypted reasoning.
Full details are opt-in through detailLevel: "full" or the viewer's confirmation button. They expose bounded record details to the active Codex conversation, but still never return base instructions or encrypted reasoning. The Python runtime has no telemetry and makes no application network requests; the uv launcher may provision a compatible Python according to the user's own uv configuration. See PRIVACY.md.
| Tool | Purpose |
|---|---|
list_codex_sessions |
List recent task metadata without transcript bodies. |
get_codex_trajectory |
Return structured trajectory data for analysis. |
show_codex_trajectory |
Return the trajectory with an interactive MCP Apps viewer. |
get_codex_trajectory and show_codex_trajectory accept sessionId, maxRecords (50–1000), the exclusive beforeRecord cursor, includeArchived, and detailLevel (summary or full). Omit sessionId for the latest task and omit beforeRecord for its newest tail; pass pagination.nextBeforeRecord to retrieve the immediately preceding page.
The output uses schemaVersion: 1. Both legacy rollouts and current paginated history_base lineages are supported. Paginated identities, byte boundaries, and contiguous ordinals are validated before inherited history is joined; copied parent context before a subagent's subagent_history_start_ordinal is excluded from the child trajectory. Codex logs do not expose DeepSeek Harness step boundaries directly, so a new approximate step begins when model output resumes after one or more tool results. Unknown control events are ignored; malformed complete JSONL or UTF-8 lines are reported in warnings, while an unfinished JSON or UTF-8 tail is tolerated during active writes. See the interface reference.
The viewer's Token details panel separates input, cache reads, uncached input, output, and reasoning output. It also shows cache-hit rate and per-turn totals in a collapsed section. Large totals, including tens or hundreds of billions of tokens, are displayed in full with responsive numeric sizing. Cache and reasoning counters are subsets of input and output respectively, not additional tokens.
The event ledger expands only the latest loaded turn by default. When an earlier page exists, Load earlier records prepends the next 500-record page, deduplicates it by stable record index, and preserves the current ledger viewport; repeat it to load the complete task. Every turn header shows its model plus separate uncached-input, cache-read, and output totals, and the entire summary strip—including all three token totals—toggles that turn. An expanded turn owns its column header, which stays pinned only while that turn's records are in view, so collapsed turns never separate a global header from the records it describes. Since the turn is already identified by that header, record rows show only their approximate Step instead of repeating Turn/step. Event and Content use compact proportional columns so all three token columns remain visible without horizontal scrolling; hovering either truncated field reveals its complete value, and focusing a record exposes both values together. Earlier turns and the Token details per-turn table are rendered lazily when opened, reducing DOM work for large tasks. Search, type filters, timeline selection, and direct record selection reveal matching collapsed turns automatically.
Click Live window to keep the current task visible without launching a standalone app. Inside Codex, the component uses the host's supported fullscreen presentation to fill its side panel; a frozen header shows the whole task's cumulative Token breakdown and current turn/step/record cursor, while the remaining height is a separately scrollable safe-summary event stream. Each event shows its status, duration, and record-level Token delta as a three-row Total/Input/Output breakdown: Input separates uncached input from cache reads, while Output separates visible output from reasoning. The newest record stays at the bottom with automatic follow-latest behavior. A compact transparent 32-frame mining mascot stays fully inside that newest card's upper-left corner and plays one cycle only when the latest record identity changes; unchanged polls leave it idle, and reduced-motion preferences disable the animation. The component never requests the unsupported host pip mode. In a regular Chromium page without the Codex display bridge, it falls back to browser-native video picture-in-picture. Full tool input, output, and raw metadata stay out of both live surfaces. The window checks for changes serially every second, pauses while hidden or after exit, and backs off after errors. Its mounted side-panel shell is updated in place, so unchanged polls do not recreate or move the status row. The app-only refresh helper compares an opaque lineage revision first; unchanged tasks are not reparsed, while changed tasks return only a 50-record safe-summary tail. Entry still requires an explicit click.
Session logs are parsed incrementally. Only the requested record page and a bounded turn/warning/call state are retained in memory, while aggregate statistics still describe the complete parsed task. JSON objects must be unambiguous and interoperable: duplicate keys, non-finite numbers, excessively large integers, and complete lines over 16 MiB are rejected or reported. Repeated cumulative Token snapshots are deduplicated, partial valid snapshots preserve the last valid counters, and unchanged session overviews are cached using every lineage file's metadata. Discovery is restricted to regular, single-link files under the configured session roots; symlinks, hardlinks, and path-like session selectors are rejected. Full-view refreshes start from the bounded 500-record tail instead of requesting the 1,000-record maximum, while earlier pages are loaded only on request.
uv sync --group dev
uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest --cov --cov-report=term-missingThe runtime has no third-party Python dependencies. Development and tests are locked in uv.lock. See CONTRIBUTING.md.
Portions of the event-ledger, timeline, selection, and inspector implementation are adapted from @deepseek-ai/dsh-client-ui-trajectory, copyright (c) 2026 DeepSeek, under the MIT License. The complete upstream license is included in LICENSES/DeepSeek-Harness.txt, with additional details in NOTICE.
Codex Trajectory is an independent project and is not affiliated with or endorsed by DeepSeek. Codex uses a different persisted event vocabulary, and this repository bundles no DeepSeek Harness package, Cordis runtime, React runtime, TanStack Virtual package, or diff package.
Friendly Links