Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 22 additions & 58 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,92 +6,56 @@

**English** · [简体中文](README.zh-CN.md)

**Version 1.0.0** · October 2, 2026 · [Changelog](CHANGELOG.md#100---2026-10-02)
See what a Codex task did, where time went, and how many tokens it used. Codex Trajectory turns local task logs into a searchable timeline and event ledger.

See what happened in a Codex task, where time went, and how many tokens it used.
- **Replay tasks:** inspect messages, saved reasoning summaries, tool calls, failures, subagent activity, and context compaction.
- **Find slow work:** see durations and percentages for tools, estimated model time, and unattributed time in the selected task.
- **Track usage:** view tokens, cache usage, and estimated costs, including all descendant subagents in task totals. Turn details show the selected agent only.
- **Follow live activity:** watch new events, token totals, and the latest local quota sample.

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.
![Task timing, token usage, timeline, and event details](plugins/codex-trajectory/assets/screenshots/overview-en.png)

![Codex Trajectory: English viewer](plugins/codex-trajectory/assets/screenshots/overview-en.png)

*Captured from the current viewer on October 2, 2026, using synthetic demo data.*

## What you can see

- **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 totals include the main agent and all descendant subagents, with cache usage and estimated cost; turn details show the selected agent's own usage.
- **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.

Task token and cost totals recursively include related active and archived subagent logs, counting each agent once. Each agent uses its recorded model and Fast mode for pricing. Live totals refresh when a subagent changes, even if the main agent is idle. Missing or unreadable subagent logs produce a warning that totals are incomplete; an oversized related log requires a larger explicit read budget. The event ledger, turn details, timing distribution, context window, and quota sample remain scoped to the selected agent or account as labeled.
*Current viewer, captured October 22, 2026 with synthetic demo data.*

## Install

You need **Codex** and **[uv](https://docs.astral.sh/uv/getting-started/installation/)**. The plugin runs on macOS, Linux, and Windows.
Requires **Codex desktop** and **[uv](https://docs.astral.sh/uv/getting-started/installation/)**. Supports macOS, Linux, and Windows.

```sh
codex plugin marketplace add icesixgod/codex-trajectory
codex plugin add codex-trajectory@icesixgod
```

Open a new Codex task to load the plugin. After updating an existing installation, fully quit and reopen Codex.

Startup does not scan or prewarm task history. Logs are loaded when a viewer or tool requests them. Metadata discovery streams only bounded headers from compressed archives without creating decompression temporary files; viewing a selected compressed task still validates its complete history within the chosen read budget.
After installing, open a new Codex task. After updating, fully quit and reopen Codex.

## Use

1. 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`.
2. Browse the timeline and event ledger. Use search and filters to find a record; select it to inspect it.
3. Click **Live window** to follow activity, or **Load earlier records** to browse history.
4. 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.
1. In the task's right panel, select **+ → More tools… → Plugins and MCPs → Codex Trajectory**. This opens the current task without a model turn; if task context is unavailable, choose a local task.
2. Search or filter the event ledger, then click a record to inspect it. Use **Load earlier records** for more history.
3. Click **Calculate task timing** for the timing breakdown, or **Live window** to follow new activity.

You can also ask Codex:
You can also open the viewer through `show_codex_trajectory` by asking 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.
For MCP calls, pass an explicit `sessionId` to select a task. Without it, read/show tools use the most recently modified active task.

## Privacy

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](PRIVACY.md) for the complete privacy model.
Timing excludes gaps between turns and counts overlapping tools once. Model time includes network and queueing waits. Costs use bundled API prices and are estimates, not subscription charges; local quota samples may lag.

## MCP tools
If a log exceeds **512 MiB**, raise **Read limit (GB)** in the error panel and click **Enable and retry**. The limit applies only to that task in the current panel.

| 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. |
## Privacy

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](docs/interface.md) for arguments, pagination, and schemas.
Logs are read locally and remain unchanged. **Safe summary** hides tool inputs, outputs, and raw metadata; **Load full details** requires confirmation and can remember your choice. Live views always use safe summaries.

## Development
Data returned through Codex may enter the active conversation. See the [privacy policy](PRIVACY.md) for details.

```sh
uv sync --group dev
uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest
```
## Documentation

See [CONTRIBUTING.md](CONTRIBUTING.md) for browser tests and release checks, [the native viewer guide](docs/native-viewer.md) for migration and troubleshooting, and [CHANGELOG.md](CHANGELOG.md) for changes.
[MCP tools and API](docs/interface.md) · [Troubleshooting](docs/native-viewer.md) · [Development](CONTRIBUTING.md) · [Changelog](CHANGELOG.md)

## License and credits

[MIT](LICENSE). Parts of the ledger, timeline, and inspector are adapted from DeepSeek's MIT-licensed [DeepSeek Harness trajectory UI](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/client/ui-trajectory), copyright © 2026 DeepSeek. See [NOTICE](NOTICE) and the [upstream license](LICENSES/DeepSeek-Harness.txt). This is an independent project, not affiliated with or endorsed by DeepSeek.
[MIT](LICENSE). Parts of the UI are adapted from [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/client/ui-trajectory), © 2026 DeepSeek. See [NOTICE](NOTICE) and the [upstream license](LICENSES/DeepSeek-Harness.txt). Independently maintained; not affiliated with DeepSeek.

Friendly link: [Linux.do](https://linux.do/)
80 changes: 22 additions & 58 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,92 +6,56 @@

[English](README.md) · **简体中文**

**版本 1.0.0** · 2026 年 10 月 2 日 · [更新日志](CHANGELOG.md#100---2026-10-02)
看清 Codex 任务做了什么、时间花在哪里、用了多少 Token。Codex Trajectory 将本地任务日志整理成可搜索的时间轴和事件账本。

看清 Codex 任务做了什么、时间花在哪里、用了多少 Token。
- **回看过程:**查看消息、已保存的推理摘要、工具调用、失败、子代理活动和上下文压缩。
- **定位耗时:**展示当前任务中工具执行、模型估算和未归因时间的时长与占比。
- **统计用量:**查看 Token、缓存命中和估算费用;任务总量包含所有层级子代理,轮次明细仅显示当前代理。
- **跟随实时活动:**查看新增事件、Token 总量和本地最新额度采样。

Codex Trajectory 将本地 Codex 日志整理成可搜索的事件账本和交互时间轴,可从任务右侧插件面板打开,也可通过 `show_codex_trajectory` MCP 工具打开。
![当前任务的耗时分布、Token 用量、时间轴与事件详情](plugins/codex-trajectory/assets/screenshots/desktop-zh-CN.png)

![Codex Trajectory 中文查看器](plugins/codex-trajectory/assets/screenshots/desktop-zh-CN.png)

*2026 年 10 月 2 日使用当前查看器截取,内容为演示数据。*

## 能看到什么

- **任务过程:**消息、日志中保存的推理摘要、工具调用、子代理活动和上下文压缩。
- **耗时与失败:**事件耗时、执行状态,以及帮助定位慢调用的时间轴。
- **当前任务耗时分布:**统计当前打开任务的活跃耗时,展示本地/工具执行、模型/Token 估算、未归因时间及占比。
- **Token 与费用:**任务总量包含主代理及所有层级子代理,展示缓存使用情况和估算费用;轮次明细保留当前代理自身的用量。
- **实时活动:**滚动事件流、Token 总量、估算费用,以及本地最新可用的额度采样。
- **历史浏览:**搜索、事件筛选、任务切换和更早记录,支持压缩日志与分页历史。

步骤划分是近似值,推理摘要仅在日志保存了摘要时显示。费用按内置 API 价格估算,不等于 Codex 订阅账单;本地额度采样也可能滞后于账户实际状态。

任务 Token 和费用会递归汇总有关联的活跃及已归档子代理日志,每个代理只计一次,分别按其记录的模型及 Fast 模式估算费用。子代理用量变化时,即使主代理空闲,实时总量也会更新。缺失或不可读的子代理日志会提示总量不完整;关联日志超过读取上限时,需要显式提高读取预算。事件账本、轮次明细、耗时分布、上下文窗口与额度采样继续按页面标注展示当前代理或账户的数据。
*2026 年 10 月 22 日截取当前界面,使用合成演示数据。*

## 安装

需要 **Codex** 和 **[uv](https://docs.astral.sh/uv/getting-started/installation/)**,支持 macOS、Linux 和 Windows。
需要 **Codex 桌面版**和 **[uv](https://docs.astral.sh/uv/getting-started/installation/)**,支持 macOS、Linux 和 Windows。

```sh
codex plugin marketplace add icesixgod/codex-trajectory
codex plugin add codex-trajectory@icesixgod
```

安装后新建一个 Codex 任务以加载插件。更新已有安装后,请完整退出并重新打开 Codex。

启动时不扫描或预热任务历史,打开查看器或调用工具后才加载日志。查找任务元数据时,压缩归档仅读取有上限的头部,不创建解压临时文件;查看选定压缩任务时,仍在所选读取预算内完整校验其历史。
安装后新建一个 Codex 任务。更新插件后,请完整退出并重新打开 Codex。

## 使用

1. 在任务右侧面板中选择 **+ → More tools… → Plugins and MCPs → Codex Trajectory**,或让 Codex 使用 `show_codex_trajectory` 展示任务轨迹。
2. 浏览时间轴和事件账本,用搜索与筛选定位记录,点击记录查看详情。
3. 点击 **实时小窗**跟随任务活动,或点击**加载更早记录**浏览历史。
4. 两种方式打开的页面均在顶部统计卡片下方提供**当前任务耗时分布**。点击**统计当前任务耗时**,即可查看本任务的耗时与占比;点击**重新统计**获取最新快照。

耗时统计仅读取当前任务的完整历史,不受当前已加载分页影响,并优先复用已加载的摘要索引。统计排除轮次间空档,并行工具的重叠时间只计算一次。工具侧包括本地命令、外部工具及调用等待。模型/Token 耗时是估算,包含网络、排队和调度等待,不能代表纯 Token 生成时间。工具计时区分缺失、无效、零值和低于 1 毫秒;缺失或无效计时只将可能执行区间保留为未归因,其余时间继续估算。零值和低于精度的耗时在分布中按 0 毫秒处理,不再阻塞整轮估算。

原生任务面板入口不触发模型对话。有有效任务上下文时,查看器精确打开该任务;任务上下文不可用时,显示本地任务选择器。插件面板与 MCP 展示工具使用相同页面,均包含当前任务耗时统计。
1. 在任务右侧面板选择 **+ → More tools… → Plugins and MCPs → Codex Trajectory**,直接打开当前任务,无需触发模型对话;无法获取任务上下文时,手动选择本地任务。
2. 搜索或筛选事件,点击记录查看详情;点击**加载更早记录**浏览历史。
3. 点击**统计当前任务耗时**查看耗时分布,或点击**实时小窗**跟随新增活动。

也可以直接对 Codex 说:
也可以让 Codex 通过 `show_codex_trajectory` 打开查看器:

> 展示当前 Codex 任务的安全轨迹摘要。

日志超过默认 **512 MiB** 读取上限时,设置足够的**读取上限(GB)**并点击**启用并重试**。提高后的上限仅对当前面板中的该任务生效;大日志首次扫描需要更长时间。
通过 MCP 调用时,请传入 `sessionId` 指定任务;未指定时,读取和展示工具默认选择最近修改的活跃任务。

## 隐私

查看器默认显示**安全摘要**,隐藏工具输入、输出和原始元数据。点击**加载完整详情**后,需要确认才会向当前对话提供有长度限制的详情。确认框中的选项可以为本机所有任务记住这一选择;**恢复安全摘要默认值**可清除偏好。实时视图始终使用安全摘要。

插件不修改源日志,也不返回基础指令或加密推理。Python 运行时不含遥测、不发起应用网络请求;首次配置时,`uv` 可能下载 Python 和依赖。

完整隐私说明见 [PRIVACY.md](PRIVACY.md)。
耗时统计排除轮次间空档,并行工具重叠时间只计一次;模型时间包含网络和排队等待。费用按内置 API 价格估算,不等于订阅账单;本地额度采样可能滞后。

## MCP 工具
日志超过 **512 MiB** 时,可在错误提示中提高**读取上限(GB)**并点击**启用并重试**,仅对当前面板中的该任务生效。

| 工具 | 用途 |
| --- | --- |
| `list_codex_sessions` | 查找近期本地任务。 |
| `get_codex_project_timing` | 仅读取选定任务的耗时分布;保留原工具名以兼容已有调用。 |
| `get_codex_trajectory` | 读取结构化轨迹数据。 |
| `show_codex_trajectory` | 打开交互查看器。 |
## 隐私

读取指定任务时,请明确传入 `sessionId`。公共读取和展示工具未指定 ID 时,会选择最近修改的活跃任务,可能与当前任务不同。参数、分页和数据结构见[接口文档](docs/interface.md)。
日志在本地读取,源文件保持不变。默认的**安全摘要**隐藏工具输入、输出和原始元数据;**加载完整详情**需要确认,也可记住这一选择。实时视图始终使用安全摘要。

## 开发
通过 Codex 返回的数据可能进入当前对话,详见[隐私说明](PRIVACY.md)。

```sh
uv sync --group dev
uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest
```
## 文档

浏览器测试与发布检查见 [CONTRIBUTING.md](CONTRIBUTING.md),迁移和故障排查见[原生查看器指南](docs/native-viewer.md),版本变化见 [CHANGELOG.md](CHANGELOG.md)。
[MCP 工具与接口](docs/interface.md) · [故障排查](docs/native-viewer.md) · [开发指南](CONTRIBUTING.md) · [更新日志](CHANGELOG.md)

## 许可与致谢

采用 [MIT 许可证](LICENSE)。事件账本、时间轴和检查器的部分实现改编自 DeepSeek 的 MIT 许可项目 [DeepSeek Harness trajectory UI](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/client/ui-trajectory),版权为 © 2026 DeepSeek。详见 [NOTICE](NOTICE) 和[上游许可证](LICENSES/DeepSeek-Harness.txt)。本项目独立维护,与 DeepSeek 不存在隶属或背书关系。
采用 [MIT 许可证](LICENSE)。部分界面改编自 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/client/ui-trajectory),© 2026 DeepSeek,详见 [NOTICE](NOTICE) 和[上游许可证](LICENSES/DeepSeek-Harness.txt)。本项目独立维护,与 DeepSeek 无隶属关系。

友情链接:[Linux.do](https://linux.do/)
Loading
Loading