xuanwo-xurl 0.0.24

Locate and read local code-agent thread files

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

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