Xsearch

xsearch

Turn a natural-language question into a fan-out ledger of independent searches, then fan in to a sourced answer.

Resolve the leaf

Before searching, resolve the executable, ensure a config file exists, and verify --version exits 0. The binary download and config creation are independent: even when the binary is already present, a missing config must still be created.

macOS/Linux:

bin="${XSEARCH_BIN:-$HOME/.agents/skills/xsearch/bin/xsearch}"
test -x "$bin" || curl -fsSL https://raw.githubusercontent.com/catoncat/xsearch/main/install.sh | bash
cfg="${XSEARCH_CONFIG:-${XDG_CONFIG_HOME:-$HOME/.config}/xsearch/config.toml}"
if [ ! -f "$cfg" ] && [ -f "$(dirname "$bin")/../config.example.toml" ]; then
  mkdir -p "$(dirname "$cfg")"
  install -m 600 "$(dirname "$bin")/../config.example.toml" "$cfg"
fi
"$bin" --version

Windows PowerShell:

$bin = if ($env:XSEARCH_BIN) { $env:XSEARCH_BIN } else { "$HOME\.agents\skills\xsearch\bin\xsearch.exe" }
if (-not (Test-Path $bin)) { irm https://raw.githubusercontent.com/catoncat/xsearch/main/install.ps1 | iex }
$cfg = if ($env:XSEARCH_CONFIG) { $env:XSEARCH_CONFIG } elseif ($env:XDG_CONFIG_HOME) { Join-Path $env:XDG_CONFIG_HOME "xsearch\config.toml" } else { Join-Path $env:APPDATA "xsearch\config.toml" }
if (-not (Test-Path $cfg)) {
  $tmpl = Join-Path (Split-Path (Split-Path $bin -Parent) -Parent) "config.example.toml"
  if (Test-Path $tmpl) { New-Item -ItemType Directory -Force -Path (Split-Path $cfg) | Out-Null; Copy-Item $tmpl $cfg }
}
& $bin --version

For setup, config, artifact fields, or failures, read references/runtime.md.

Choose the role

• Parent: you own the user request. Follow the parent process below.
• Leaf: your task already contains a self-contained xsearch leaf handoff. Follow that handoff once and return its result. Leaf mode is terminal: one route, one process, one note.

Ledger invariant

N x Q means N ledger routes, each executing one independent xsearch process with plan size Q. A larger Q is deeper retrieval inside one route; it never replaces another route.

Each route maps to one host child ID or tool-call ID. Keep route commands separate: shell separators, chained commands, and multi-route shell scripts are not fan-out.

Every ledger entry has route_id, round, query, Q, host_call_id, status, and eventually manifest_path or error. A round is complete when all N entries are terminal. It is fully successful only when all N have distinct host call IDs and receipts/manifests.

Parent process

1. Form the question

Rewrite the request as a self-contained goal: entity + current time boundary + dimension. Resolve an X-Y mismatch when the stated query differs from the likely goal. Keep unverified user claims neutral.

Ask one short preference question only when different answers would materially change what gets searched. “Just search” waives the question, not fan-out. Explicit “one call”, “do not split”, or “return the raw result” selects direct mode.

Complete when: the goal is searchable without hidden conversation context.

2. Choose scope and hypotheses

Write 2–6 competing hypotheses or evidence aspects, each with evidence that would support or weaken it.

Cap a round at 6 routes and respect runtime limits. The engine hard-caps Q at 20 and runs at most four sub-searches concurrently per process. A simple question is narrow, not automatically direct.

Complete when: scope, N, Q, and the support/weaken conditions are explicit.

3. Open the ledger

Create all route objects before dispatch. Each contains:

• route_id, route_name, round, query, Q
• target_dimension, output_goal
• targets_hypotheses, decision_value
• a compact context_pack when local context is needed

Routes differ by dimension, time window, entity set, evidence class, or decision goal. Merge paraphrase duplicates and keep at most one broad survey route. Every hypothesis/aspect must be covered by at least one route.

Complete when: the ledger contains exactly N unique, covered, dispatchable routes.

4. Dispatch the round

Read references/leaf.md. For every route, build a self-contained child task from its handoff template, including the resolved executable path, route object, command, and result contract.

Use the host's strongest available execution lane:

1. N isolated child/task agents submitted concurrently; or
2. N separate CLI tool calls submitted in the same assistant turn/batch; or
3. N separate sequential tool calls only when concurrency is unavailable.

One child or tool call owns exactly one route. Set each host call timeout to at least the runtime timeout (default 600 seconds). Submit the entire concurrent round before waiting and record each distinct host call ID as running.

Complete when: the ledger has N distinct host call IDs submitted before collection begins, or a terminal dispatch error for an unsubmitted route.

5. Close the ledger

Collect one terminal note per route. A host failure, timeout, or cancellation becomes a parent-authored failure note. For malformed child output, apply the single extraction fallback in references/leaf.md; a failed extraction becomes status: malformed and cannot seed expansion.

A completed process must provide a distinct xsearch.run.v1 receipt and manifest_path. Keep artifact bodies in their files; select only the item files needed for that route.

Complete when: all N ledger entries are terminal and successful entries have distinct host call IDs, run IDs, and manifest paths.

6. Fan in and decide

Score each usable route on information gain, conflict resolution, novelty, actionability, redundancy, and uncertainty. Merge mutually supporting claims; label single-route claims. Put genuine conflicts and unknowns in separate sections. Dedupe URLs and prefer primary/official evidence.

Open one follow-up round only when a new entity, unresolved conflict, missing mechanism, or high-value gap could change the answer. Use the best 1–3 candidates, assign new IDs (F1, F2, ...), and repeat sections 3–5 with round: 2. Failed or malformed notes do not seed follow-up routes.

Verify load-bearing claims before answering. When a conclusion rests on a specific page — a version number, date, price, quote, or a claim carried by a single route — deep-read that page with the same executable:

"${XSEARCH_BIN:-$HOME/.agents/skills/xsearch/bin/xsearch}" extract "<url>"

Use --format snippet --max-chars 500 to peek before committing to a full page. Select 1–3 URLs from deduped_urls, preferring high occurrence_count and primary sources; do not deep-read every link. extract needs no API configuration. When a page contradicts a route note, trust the page and report the conflict.

Stop when proposed routes are paraphrases, results repeat, or the question is answered. Respond with conclusions first, then important conflicts/gaps and a few useful links. Keep N/Q terminology internal unless the user asks about execution.

Complete when: the final answer is backed by the closed ledger, load-bearing claims are deep-read or explicitly labeled unverified, material conflicts/gaps are preserved, and no leaf transcripts are dumped.