xurl

xURL

xURL is a CLI that reads, queries, and writes AI agent conversations through a unified agents:// URI scheme.

Also known as Xuanwo's URL.

What xURL Can Do

xURL gives you one URI scheme (agents://) to read, query, discover, and write conversations across multiple AI agent CLIs.

• Read a conversation as markdown — xurl agents://codex/<id>
• Query threads by provider, keyword, local path, or role — xurl 'agents://codex?q=refactor'
• Discover child targets and metadata before drilling down — xurl -I agents://codex/<id>
• Write to start or continue a conversation — xurl agents://codex -d "hello"

Providers

agents://amp	agents://claude	agents://codex	agents://copilot	agents://cursor
agents://gemini	agents://kimi	agents://opencode	agents://pi

Installation

Install as an agent skill:

npx skills add Xuanwo/xurl

Or install the standalone CLI:

brew tap xuanwo/tap && brew install xurl   # Homebrew
cargo install xurl-cli                      # Cargo
uv tool install xuanwo-xurl                 # Python / uv
npm install -g @xuanwo/xurl                 # npm

Quick Start

Ask your agent to summarize a thread:

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

Usage

Note: The agents:// scheme prefix is optional — codex/... is equivalent to agents://codex/....

Read

xurl agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592
xurl agents://copilot/688628a1-407a-4b4e-b24a-1a250ebf864f

Save output to a file:

xurl -o /tmp/conversation.md agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592

Query

By provider:

xurl agents://codex
xurl 'agents://codex?q=spawn_agent'
xurl 'agents://claude?q=agent&limit=5'
xurl 'agents://copilot?q=resume&limit=5'

By local path:

xurl agents:///Users/alice/work/xurl
xurl 'agents:///Users/alice/work/xurl?q=refactor&limit=5'
xurl 'agents://.?q=refactor&providers=codex,claude'
xurl 'agents://~/work/xurl?providers=opencode'

By role:

xurl agents://codex/reviewer

Query results include reduced thread metadata when available, so you can inspect fields like payload.git.branch without opening each thread individually.

Discover

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

Frontmatter includes provider metadata flattened into readable key-value lines (e.g. payload.git.branch = ...), and skips oversized instruction-like fields.

Drill down into a discovered child target:

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

Write

Start a new conversation:

xurl agents://codex -d "Draft a migration plan"

Start with a role URI:

xurl agents://codex/reviewer -d "Review this patch"
xurl agents://copilot/research -d "Investigate the failing integration test"

Continue an existing conversation:

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

Pass extra parameters to the provider CLI via query string:

xurl "agents://codex?cd=%2FUsers%2Falice%2Frepo&add-dir=%2FUsers%2Falice%2Fshared&model=gpt-5" -d "Review this patch"

Command Reference

xurl [OPTIONS] <URI>

• -I, --head: output frontmatter/discovery info only, including the first provider metadata record flattened into key-value lines when available.
• -d, --data <DATA>: write payload (repeatable).
  • text: -d "hello"
  • file: -d @prompt.txt
  • stdin: -d @-
• -o, --output <PATH>: write command output to file.

Error Output