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
