| name | inspect-codex-trajectory |
| description | Inspect or show a local Codex task trajectory, including turns, approximate model steps, assistant messages, reasoning summaries, tool calls, failures, compaction, token usage, and timing. Use when the user asks for a trajectory, execution trace, task timeline, slow-tool analysis, visual event ledger, or live picture-in-picture tracker for Codex work. |
Inspect Codex Trajectory
Use the plugin's read-only MCP tools instead of opening raw files under the Codex home directory.
- For the active task or the most recently updated task, call
show_codex_trajectory without a session ID. Keep the default detailLevel: summary; this renders the interactive trajectory UI without tool inputs or outputs.
- For a historical task, call
list_codex_sessions, choose the exact session ID, then call show_codex_trajectory with that ID.
- Use
get_codex_trajectory when the user wants analysis without the interactive UI. Cite turn numbers and record indexes from its structured result. If the requested evidence predates the returned page, call it again with the response's pagination.nextBeforeRecord as beforeRecord; continue only as far back as the request requires.
- When the user wants a live or picture-in-picture view, call
show_codex_trajectory in summary mode. The user can then click Live window in the rendered viewer. Inside Codex it fills the supported host side-panel presentation with frozen whole-task Token totals, a remaining-quota badge when official windows are present, one-click and opt-in threshold stop controls, and a chronological per-record Token stream; a regular Chromium page uses native video PiP without stop controls. Stop controls require the user's explicit experimental loopback CDP opt-in. The standard Apps surface uses an app-private direct-stop tool that pauses an active Goal before turn/interrupt, never posts a follow-up message or enters the steering queue, and fails closed while CDP is unavailable. Manual Stop rearms for later turns; automatic Stop remains latched throughout the same quota cycle, including /goal continuations, and rearms only after quota recovery, a window reset, or a guard configuration change. A rejected stale turn is rebound once and transient failures retry without consuming the latch. Selecting another trajectory disables stopping. On macOS and Windows, the token-bearing View trajectory Browser shortcut additionally requires per-connection operating-system authentication of the Codex desktop peer; failures and unsupported platforms keep it unavailable without disabling direct stop. The live window does not launch a standalone app or touch composer drafts and attachments. Do not call the app-only live-update, toolbar-setting, or direct-stop helpers directly.
- Use
detailLevel: full only after the user explicitly asks to inspect full tool input or output. Treat those values as potentially sensitive and quote no more than the task requires. Never expose session_meta.base_instructions, encrypted reasoning, credentials, or environment variables.
- Explain that Codex logs do not expose DeepSeek Harness step boundaries directly. The plugin starts a new approximate step when model output resumes after one or more tool results.
- Treat read warnings as evidence of skipped malformed records. If a paginated lineage fails validation, report that the local task history is inconsistent; do not bypass the plugin by opening inherited rollout files directly.
The user-facing trajectory tools are read-only. They read local sessions/ and, when requested, archived_sessions/ beneath CODEX_HOME or ~/.codex. The viewer alone may use its private CDP setting and direct-stop helpers after the user changes the experimental switch or activates an enabled stop control.
