xURL: Client for AI Agents URLs
xURL is a CLI that reads, queries, and writes AI agent conversations through a unified agents:// URI scheme.
Also known as Xuanwo's URL.
xURL gives you one URI scheme (agents://) to read, query, discover, and write conversations across multiple AI agent CLIs.
xurl agents://codex/xurl 'agents://codex?q=refactor'xurl -I agents://codex/xurl agents://codex -d "hello"agents://amp
agents://claude
agents://codex
agents://copilot
agents://cursor
agents://gemini
agents://kimi
agents://opencode
agents://pi
Install as an agent skill:
npx skills add Xuanwo/xurlOr 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 # npmAsk your agent to summarize a thread:
Please summarize this thread: agents://codex/xxx_threadNote: The
agents://scheme prefix is optional —codex/...is equivalent toagents://codex/....
xurl agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592
xurl agents://copilot/688628a1-407a-4b4e-b24a-1a250ebf864fSave output to a file:
xurl -o /tmp/conversation.md agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592By 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/reviewerQuery results include reduced thread metadata when available, so you can inspect fields like payload.git.branch without opening each thread individually.
xurl -I agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592Frontmatter 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-832f02598495Start 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"xurl [OPTIONS] -I, --head: output frontmatter/discovery info only, including the first provider metadata record flattened into key-value lines when available.-d, --data : write payload (repeatable).-d "hello"-d @prompt.txt-d @--o, --output : write command output to file.xurl writes actionable stderr errors for agents:
requested_uri, suggested next_steps, and the GitHub issue link for requesting supportsearched_roots so the next recovery step is explicit[agents://][/[/]][?]
|------| |--------| |---------------------------| |------|
optional provider optional path parts query
schemescheme: optional agents:// prefix. If omitted, xurl treats input as an agents URI shorthand.provider: target provider name, such as amp, claude, codex, copilot, cursor, gemini, kimi, opencode, pi.token: main conversation identifier or role name.child_id: child/subagent identifier under a main conversation.query: optional key-value parameters, interpreted by context.agents:///abs/path[?]
agents://.[?]
agents://./subdir[?]
agents://..[?]
agents://../repo[?]
agents://~[?]
agents://~/repo[?]agents:///abs/path: canonical local path query form.agents://. / agents://./subdir: query relative to the current working directory.agents://.. / agents://../repo: query relative to the parent of the current working directory.agents://~ / agents://~/repo: query relative to the home directory.q=: filters discovery results by keyword. Use when you want to find conversations by topic.limit=: limits discovery result count (default 10). Use when you need a shorter or longer result list.providers=: restricts a path-scoped query to selected providers.=: in write mode (-d), xurl forwards as -- to the provider CLI.-d), xurl forwards as -- to the provider CLI.Examples:
agents://codex?q=spawn_agent&limit=10
agents:///Users/alice/work/xurl?q=refactor&providers=codex,claude
agents://.?q=refactor&providers=codex
agents://codex/
agents://codex/reviewer
agents://codex?cd=%2FUsers%2Falice%2Frepo&add-dir=%2FUsers%2Falice%2FsharedNo open issues yet, or sync has not completed.