GitHub - Xuanwo/xurl: xURL: Client for AI Agents URLs

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 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

Provider	Query	Create	Role Create
Amp	Yes	Yes	No
Codex	Yes	Yes	Yes
Claude	Yes	Yes	Yes
Gemini	Yes	Yes	No
Pi	Yes	Yes	No
OpenCode	Yes	Yes	Yes

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 role-scoped threads:

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

Discover child targets:

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

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

• -I, --head: output frontmatter/discovery info only.
• -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.

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.
• <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://codex/threads/<conversation_id>
agents://codex/reviewer
agents://codex?cd=%2FUsers%2Falice%2Frepo&add-dir=%2FUsers%2Falice%2Fshared