xurl

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

xurl

Use this skill when you need to read AI agent thread content by URI.

当你需要通过URI读取AI agent线程内容时，可使用此工具。

Installation

安装

Install

xurl

from npm:

bash

npx @xuanwo/xurl --help

Or install

xurl

from package

xuanwo-xurl

via

uv

bash

uv tool install xuanwo-xurl
xurl --version

从npm安装

xurl

：

bash

npx @xuanwo/xurl --help

或者通过

uv

从

xuanwo-xurl

包安装

xurl

：

bash

uv tool install xuanwo-xurl
xurl --version

When to Use

使用场景

The user gives an

agents://...

URI for

amp

codex

claude

gemini

pi

, or

opencode

The user gives legacy URIs like

codex://...

claude://...

pi://...

amp://...

gemini://...

, or

opencode://...

The user asks to inspect, view, or fetch thread content.
You need to quote or reuse prior context in workflows like compact, handoff, or delegate.
You need to find subagent or branch targets before drilling into a specific child thread.

用户提供针对

amp

、

codex

、

claude

、

gemini

、

pi

或

opencode

的

agents://...

URI。

用户提供旧版URI，例如

codex://...

、

claude://...

、

pi://...

、

amp://...

、

gemini://...

或

opencode://...

。

用户要求检查、查看或获取线程内容。
在精简（compact）、移交（handoff）或委托（delegate）等工作流中，你需要引用或复用先前的上下文。
在深入特定子线程之前，你需要查找子agent或分支目标。

URI Construction Playbook

URI构建指南

Identify provider and id source.

Provider usually comes from context (
```
codex
```
,
```
claude
```
,
```
amp
```
,
```
gemini
```
,
```
pi
```
,
```
opencode
```
).
Prefer ids copied from existing links, list output, or known session metadata.

Build the canonical URI.

Main thread:

agents://codex/<session_id>

(or deep-link

agents://codex/threads/<session_id>

)

```
agents://claude/<session_id>
```
```
agents://amp/<thread_id>
```
```
agents://gemini/<session_id>
```
```
agents://pi/<session_id>
```
```
agents://opencode/<session_id>
```

Child target:

agents://codex/<main_session_id>/<agent_id>

agents://claude/<main_session_id>/<agent_id>

```
agents://pi/<session_id>/<entry_id>
```

Validate mode constraints.

```
--list
```
must be used with a main thread URI, not with a child URI.
```
amp
```
,
```
gemini
```
, and
```
opencode
```
do not support child path segments.

If child id is unknown, discover first.

Use
```
xurl <main_uri> --list
```
to get valid child targets (Codex/Claude subagents, Pi entries).
Copy URI/id from the list output instead of guessing.

确定提供商和ID来源。

提供商通常来自上下文（
```
codex
```
、
```
claude
```
、
```
amp
```
、
```
gemini
```
、
```
pi
```
、
```
opencode
```
）。
优先使用从现有链接、列表输出或已知会话元数据中复制的ID。

构建标准URI。

主线程：

agents://codex/<session_id>

（或深层链接

agents://codex/threads/<session_id>

）

```
agents://claude/<session_id>
```
```
agents://amp/<thread_id>
```
```
agents://gemini/<session_id>
```
```
agents://pi/<session_id>
```
```
agents://opencode/<session_id>
```

子目标：

agents://codex/<main_session_id>/<agent_id>

agents://claude/<main_session_id>/<agent_id>

```
agents://pi/<session_id>/<entry_id>
```

验证模式约束。

```
--list
```
必须与主线程URI一起使用，不能与子URI搭配。
```
amp
```
、
```
gemini
```
和
```
opencode
```
不支持子路径段。

若子ID未知，先进行发现。

使用
```
xurl <main_uri> --list
```
获取有效的子目标（Codex/Claude子agent、Pi条目）。
从列表输出中复制URI/ID，而非猜测。

Supported URI Forms

支持的URI格式

Canonical:

```
agents://codex/<session_id>
```
```
agents://codex/threads/<session_id>
```

agents://codex/<main_session_id>/<agent_id>

```
agents://amp/<thread_id>
```
```
agents://claude/<session_id>
```

agents://claude/<main_session_id>/<agent_id>

```
agents://gemini/<session_id>
```
```
agents://pi/<session_id>
```
```
agents://pi/<session_id>/<entry_id>
```
```
agents://opencode/<session_id>
```

Legacy compatibility:

```
codex://<session_id>
```
```
codex://threads/<session_id>
```
```
codex://<main_session_id>/<agent_id>
```
```
amp://<thread_id>
```
```
claude://<session_id>
```
```
claude://<main_session_id>/<agent_id>
```
```
gemini://<session_id>
```
```
pi://<session_id>
```
```
pi://<session_id>/<entry_id>
```
```
opencode://<session_id>
```

标准格式：

```
agents://codex/<session_id>
```
```
agents://codex/threads/<session_id>
```

agents://codex/<main_session_id>/<agent_id>

```
agents://amp/<thread_id>
```
```
agents://claude/<session_id>
```

agents://claude/<main_session_id>/<agent_id>

```
agents://gemini/<session_id>
```
```
agents://pi/<session_id>
```
```
agents://pi/<session_id>/<entry_id>
```
```
agents://opencode/<session_id>
```

旧版兼容格式：

```
codex://<session_id>
```
```
codex://threads/<session_id>
```
```
codex://<main_session_id>/<agent_id>
```
```
amp://<thread_id>
```
```
claude://<session_id>
```
```
claude://<main_session_id>/<agent_id>
```
```
gemini://<session_id>
```
```
pi://<session_id>
```
```
pi://<session_id>/<entry_id>
```
```
opencode://<session_id>
```

Input-to-URI Examples

输入转URI示例

Provider + main id:

input:

provider=codex

session_id=019c871c-b1f9-7f60-9c4f-87ed09f13592

uri:

agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592

Codex deep-link from UI:

input:

codex://threads/019c871c-b1f9-7f60-9c4f-87ed09f13592

uri:

agents://codex/threads/019c871c-b1f9-7f60-9c4f-87ed09f13592

Main uri + child id:

input:

agents://claude/2823d1df-720a-4c31-ac55-ae8ba726721f

acompact-69d537

uri:

agents://claude/2823d1df-720a-4c31-ac55-ae8ba726721f/acompact-69d537

Pi branch drill-down:

input:

agents://pi/12cb4c19-2774-4de4-a0d0-9fa32fbae29f --list

output entry

d1b2c3d4

uri:

agents://pi/12cb4c19-2774-4de4-a0d0-9fa32fbae29f/d1b2c3d4

提供商+主ID：

输入：

provider=codex

，

session_id=019c871c-b1f9-7f60-9c4f-87ed09f13592

URI：

agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592

来自UI的Codex深层链接：

输入：

codex://threads/019c871c-b1f9-7f60-9c4f-87ed09f13592

URI：

agents://codex/threads/019c871c-b1f9-7f60-9c4f-87ed09f13592

主URI+子ID：

输入：

agents://claude/2823d1df-720a-4c31-ac55-ae8ba726721f

acompact-69d537

URI：

agents://claude/2823d1df-720a-4c31-ac55-ae8ba726721f/acompact-69d537

Pi分支深入：

输入：

agents://pi/12cb4c19-2774-4de4-a0d0-9fa32fbae29f --list

输出条目

d1b2c3d4

URI：

agents://pi/12cb4c19-2774-4de4-a0d0-9fa32fbae29f/d1b2c3d4

Commands

命令

Default output (timeline markdown with user/assistant messages and compact markers):

bash

xurl agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592

Raw JSONL output:

bash

xurl agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592 --raw

Discover child targets first:

bash

xurl agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592 --list
xurl agents://claude/2823d1df-720a-4c31-ac55-ae8ba726721f --list
xurl agents://pi/12cb4c19-2774-4de4-a0d0-9fa32fbae29f --list

Codex subagent drill-down:

bash

xurl agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592/019c87fb-38b9-7843-92b1-832f02598495

Claude thread and subagent examples:

bash

xurl agents://claude/2823d1df-720a-4c31-ac55-ae8ba726721f
xurl agents://claude/2823d1df-720a-4c31-ac55-ae8ba726721f/acompact-69d537

Codex deep-link example:

bash

xurl agents://codex/threads/019c871c-b1f9-7f60-9c4f-87ed09f13592

Other providers:

bash

xurl agents://opencode/ses_43a90e3adffejRgrTdlJa48CtE
xurl agents://gemini/29d207db-ca7e-40ba-87f7-e14c9de60613
xurl agents://amp/T-019c0797-c402-7389-bd80-d785c98df295
xurl agents://pi/12cb4c19-2774-4de4-a0d0-9fa32fbae29f
xurl agents://pi/12cb4c19-2774-4de4-a0d0-9fa32fbae29f/d1b2c3d4

默认输出（包含用户/助手消息和精简标记的时间线markdown）：

bash

xurl agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592

原始JSONL输出：

bash

xurl agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592 --raw

先发现子目标：

bash

xurl agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592 --list
xurl agents://claude/2823d1df-720a-4c31-ac55-ae8ba726721f --list
xurl agents://pi/12cb4c19-2774-4de4-a0d0-9fa32fbae29f --list

Codex子agent深入：

bash

xurl agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592/019c87fb-38b9-7843-92b1-832f02598495

Claude线程和子agent示例：

bash

xurl agents://claude/2823d1df-720a-4c31-ac55-ae8ba726721f
xurl agents://claude/2823d1df-720a-4c31-ac55-ae8ba726721f/acompact-69d537

Codex深层链接示例：

bash

xurl agents://codex/threads/019c871c-b1f9-7f60-9c4f-87ed09f13592

其他提供商：

bash

xurl agents://opencode/ses_43a90e3adffejRgrTdlJa48CtE
xurl agents://gemini/29d207db-ca7e-40ba-87f7-e14c9de60613
xurl agents://amp/T-019c0797-c402-7389-bd80-d785c98df295
xurl agents://pi/12cb4c19-2774-4de4-a0d0-9fa32fbae29f
xurl agents://pi/12cb4c19-2774-4de4-a0d0-9fa32fbae29f/d1b2c3d4

Construction Examples for Common Agent Tasks

常见Agent任务的构建示例

Compact (Claude child thread from known main + agent id):

bash

xurl agents://claude/2823d1df-720a-4c31-ac55-ae8ba726721f/acompact-69d537

Handoff (Codex deep-link shared by another agent):

bash

xurl agents://codex/threads/019c871c-b1f9-7f60-9c4f-87ed09f13592

Delegate follow-up (discover child first, then drill down):

bash

xurl agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592 --list
xurl agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592/019c87fb-38b9-7843-92b1-832f02598495

精简（已知主线程+agent ID的Claude子线程）：

bash

xurl agents://claude/2823d1df-720a-4c31-ac55-ae8ba726721f/acompact-69d537

移交（由其他agent共享的Codex深层链接）：

bash

xurl agents://codex/threads/019c871c-b1f9-7f60-9c4f-87ed09f13592

委托跟进（先发现子目标，再深入）：

bash

xurl agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592 --list
xurl agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592/019c87fb-38b9-7843-92b1-832f02598495

Agent Behavior

Agent行为规范

Prefer canonical
```
agents://
```
URIs when constructing links or commands.
Legacy provider schemes are accepted, so keep workflows compatible with existing links.
If the user does not request
```
--raw
```
, use default markdown output first.
If the user asks for subagent aggregation, use
```
--list
```
with the parent thread URI.
If the user asks for Pi session navigation targets, use
```
--list
```
with
```
agents://pi/<session_id>
```
.
If the user requests exact records, rerun with
```
--raw
```
.
If the output is long, redirect to a temp file and grep/summarize based on the user request.
Do not infer or reinterpret thread meaning unless the user explicitly asks for analysis.

构建链接或命令时，优先使用标准
```
agents://
```
URI。
接受旧版提供商协议，确保工作流与现有链接兼容。
若用户未请求
```
--raw
```
，优先使用默认markdown输出。
若用户要求子agent聚合，将
```
--list
```
与父线程URI搭配使用。
若用户要求Pi会话导航目标，将
```
--list
```
与
```
agents://pi/<session_id>
```
搭配使用。
若用户要求精确记录，使用
```
--raw
```
重新运行。
若输出内容过长，重定向到临时文件并根据用户请求进行过滤或总结。
除非用户明确要求分析，否则不要推断或重新解释线程含义。

Failure Handling

故障处理

Common failures include invalid URI format, invalid mode combinations, and missing thread files.

Typical invalid mode example:

--list

with

agents://<provider>/<main_thread_id>/<agent_id>

常见故障包括无效URI格式、无效模式组合和线程文件缺失。

典型的无效模式示例：将

--list

与

agents://<provider>/<main_thread_id>/<agent_id>

搭配使用。