xURL

xURL is a client for AI agent URLs.

Also known as Xuanwo's URL.

What xURL Can Do

• Read an agent conversation as markdown.
• Query recent threads and keyword matches for a provider.
• Query conversations by local path across providers.
• Query role-scoped threads with agents://<provider>/<role>.
• Discover subagent/branch navigation targets.
• Start a new conversation with agents.
• Continue an existing conversation with follow-up prompts.

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

Providers

Usage

Read an agent conversation:

xurl agents://codex/019c871c-b1f9-7f60-9c4f-87ed09f13592
# equivalent shorthand:
xurl codex/019c871c-b1f9-7f60-9c4f-87ed09f13592

Query provider threads:

xurl agents://codex
xurl 'agents://codex?q=spawn_agent'
xurl 'agents://claude?q=agent&limit=5'
# equivalent shorthand:
xurl codex
xurl 'codex?q=spawn_agent'

Query conversations by 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'

Query role-scoped threads:

xurl agents://codex/reviewer
# equivalent shorthand:
xurl codex/reviewer

Query results include the same reduced thread metadata used by --head when it is available, so you can inspect fields like payload.git.branch without opening each thread individually.

Discover child targets:

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

Frontmatter includes the first provider metadata record flattened into readable key-value lines such as 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

Start a new agent conversation:

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

Start a new conversation with role URI:

xurl agents://codex/reviewer -d "Review this patch"

Continue an existing conversation:

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

Create with query parameters:

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

Save output:

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

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.

URI Reference

Agents URI

[agents://]<provider>[/<token>[/<child_id>]][?<query>]
|------|  |--------|  |---------------------------|  |------|
 optional   provider         optional path parts        query
 scheme

• scheme: optional agents:// prefix. If omitted, xurl treats input as an agents URI shorthand.
• provider: target provider name, such as codex, claude, gemini, amp, pi, opencode.
• token: main conversation identifier or role name.
• child_id: child/subagent identifier under a main conversation.
• query: optional key-value parameters, interpreted by context.

Path-Scoped Query URI

agents:///abs/path[?<query>]
agents://.[?<query>]
agents://./subdir[?<query>]
agents://..[?<query>]
agents://../repo[?<query>]
agents://~[?<query>]
agents://~/repo[?<query>]

• 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.
• path-scoped query always returns a conversation list.

Agents Query

• q=<keyword>: filters discovery results by keyword. Use when you want to find conversations by topic.
• limit=<n>: limits discovery result count (default 10). Use when you need a shorter or longer result list.
• providers=<name[,name...]>: restricts a path-scoped query to selected providers.
• <key>=<value>: in write mode (-d), xurl forwards as --<key> <value> to the provider CLI.
• <flag>: in write mode (-d), xurl forwards as --<flag> 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/threads/<conversation_id>
agents://codex/reviewer
agents://codex?cd=%2FUsers%2Falice%2Frepo&add-dir=%2FUsers%2Falice%2Fshared