xuanwo-xurl 0.0.13

Locate and read local code-agent thread files

xURL

xURL is a client for AI agent URLs.

Also known as Xuanwo's URL.

Features

• Multi-agent thread resolution:
  • Amp
  • Codex
  • Claude
  • Gemini
  • Pi
• OpenCode
• Unified URI scheme: agents://<provider>/<thread_path> is the primary format.
• Default output is markdown with YAML frontmatter header plus provider-specific body.
• -I, --head outputs frontmatter only.
• For Codex/Claude/Pi main URIs, head output includes discovery fields (subagents / entries) that replace list-mode aggregation.
• Subagent markdown views print full parent/subagent URIs in agents://... format.
• Non-fatal diagnostics are kept internal; only fatal errors are printed to stderr.
• Automatically respects official environment variables and default local data roots for each supported agent.

Install

Install from PyPI via uv:

uv tool install xuanwo-xurl
xurl --help

Or install from PyPI via pipx:

pipx install xuanwo-xurl
xurl --help

Or run directly from npm with npx:

npx @xuanwo/xurl --help

Or install globally via npm:

npm install -g @xuanwo/xurl
xurl --help

Install as a Codex skill:

npx skills add Xuanwo/xurl

URL Format

Primary URI format:

agents://<provider>/<thread_path>

ASCII breakdown:

agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592/019c87fb-38b9-7843-92b1-832f02598495
^^^^^^   ^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
scheme   provider thread_path (provider-specific: main thread, optional child thread)

Agents

Amp

• Supported URIs:
  • agents://amp/<thread_id>
• Thread id format:
  • T-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• Resolution:
  • XDG_DATA_HOME/amp/threads/<thread_id>.json
  • fallback: ~/.local/share/amp/threads/<thread_id>.json
• Example:

xurl agents://amp/T-019c0797-c402-7389-bd80-d785c98df295

Codex

• Supported URIs:
  • agents://codex/<session_id>
  • agents://codex/threads/<session_id>
  • agents://codex/<main_session_id>/<agent_id>
• Subagent modes:
  • Aggregate header only: xurl -I agents://codex/<main_session_id>
  • Drill-down: xurl agents://codex/<main_session_id>/<agent_id>
• Resolution order:
  • SQLite thread index under CODEX_HOME (state_<version>.sqlite first, then state.sqlite) via threads(id, rollout_path, archived).
  • Filesystem fallback under sessions/ and archived_sessions/ for rollout-*.jsonl.
• Examples:

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

Claude

• Supported URIs:
  • agents://claude/<session_id>
  • agents://claude/<main_session_id>/<agent_id>
• Subagent modes:
  • Aggregate header only: xurl -I agents://claude/<main_session_id>
  • Drill-down: xurl agents://claude/<main_session_id>/<agent_id>
• Example:

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

OpenCode

• Supported URIs:
  • agents://opencode/<session_id>
• Example:

xurl agents://opencode/ses_43a90e3adffejRgrTdlJa48CtE

Gemini

• Supported URI:
  • agents://gemini/<session_id>
• Session id format:
  • xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• Resolution:
  • GEMINI_CLI_HOME/.gemini/tmp/*/chats/session-*.json
  • fallback: ~/.gemini/tmp/*/chats/session-*.json
• Example:

xurl agents://gemini/29d207db-ca7e-40ba-87f7-e14c9de60613

Pi

• Supported URIs:
  • agents://pi/<session_id>
  • agents://pi/<session_id>/<entry_id>
• Session id format:
  • xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• Resolution:
  • PI_CODING_AGENT_DIR/sessions/**/*.jsonl
  • fallback: ~/.pi/agent/sessions/**/*.jsonl
• Rendering:
  • agents://pi/<session_id> renders the latest leaf branch in the session tree.
  • agents://pi/<session_id>/<entry_id> renders the branch ending at the specified entry id.
  • xurl -I agents://pi/<session_id> outputs entries in frontmatter for drill-down discovery.
• Example:

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