xuanwo-xurl 0.0.15

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.
• -o, --output <path> writes rendered output to a file.
• 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

Homebrew:

brew tap xuanwo/tap
brew install xurl

PyPI via uv:

uv tool install xuanwo-xurl
xurl --version

npm:

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

Quick Start

1. Add xurl as an agent skill:

npx skills add Xuanwo/xurl

2. Start your agent and ask the agent to summarize a thread:

Please summarize this thread: agents://codex/xxx_thread

Repository Usage

Run xurl directly from source:

cargo run -p xurl-cli -- --help

Run the test suite:

cargo test --workspace

Run CLI integration tests only:

cargo test -p xurl-cli --test cli

Release process summary:

1. Bump crate versions in xurl-core/Cargo.toml and xurl-cli/Cargo.toml.
2. Push to main.
3. Create and push a tag like v0.0.14.
4. GitHub Actions will publish release assets, npm, PyPI, and Homebrew updates.

Projects in This Repository

• xurl-core: core URI parsing, provider resolution, thread reading, and markdown rendering.
• xurl-cli: CLI entrypoint and argument handling for xurl.
• npm: Node.js wrapper package source for @xuanwo/xurl.
• pyproject.toml: Python package metadata for xuanwo-xurl.
• homebrew-tap: Homebrew formula repository (xuanwo/tap).
• skills/xurl: Codex skill instructions for using 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 -o /tmp/codex-thread.md agents://codex/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

Release Automation

• release.yml (tag push v*) builds native binaries and publishes GitHub release assets (xurl-<version>-<target>.tar.gz + checksums + manifest).
• homebrew-publish.yml consumes release.yml metadata and updates xuanwo/tap formula.
• npm-publish.yml and pypi-publish.yml keep their original filenames for trusted publisher compatibility, but now consume artifacts from release.yml instead of rebuilding binaries.