home · docs · research

How to run it

Three entry points, same engine behind each:

carlos research "is webgpu supported in safari 17 yet?"        # headless
/research "is webgpu supported in safari 17 yet?"              # inside the TUI
# inside a /research, the engine runs as a sub-agent with the
# manage view surfacing phase progress in real time

Live progress is rendered in cmd/carlos via a bordered status panel; visual language mirrors the carlos please panel. The cited report saves to:

frames/<frame>/research/<slug>-<unix-ts>.md
# 0600 inside a 0700 dir

The six phases

Each phase fires start and done callbacks against the Engine.Run API; chat consumes them as EvtResearchPhase events and renders progress, done, and failed lines that collapse on AgentID.

1. decompose

   Model splits the question into sub-questions and an answer schema. The schema is what verify will audit coverage against later.

2. search

   web_search fans out across configured backends (Brave, SearXNG, DuckDuckGo HTML). Result list with stable sN IDs that follow each candidate through the rest of the pipeline.

3. fetch

   web_fetch resolves each candidate URL. HTML to text via golang.org/x/net/html. Refuses non-http(s), private and loopback addresses (config-gated), non-text content types, and robots-disallowed paths (override available). HEAD-then-GET; 5 MiB raw and 256 KiB extracted caps; 5-redirect ceiling; 5-minute robots cache.

4. read

   Each fetched page is chunked into Passages with stable pN IDs. These IDs are the ground truth verify will trust.

5. synthesize

   Model writes the report. Prompt forces inline [pN] citations so verify can audit coverage claim-by-claim.

6. verify

   Independent pass checks that every claim cites a real pN and that the cited passage supports the claim. The citation auditor (internal/research/citations.go) flags hallucinated or misattributed cites.

Budget

ResearchBudget caps provider calls, fetched bytes, and wall-clock time. On overrun the engine refuses cleanly with a partial Report rather than running unbounded.

Output shape

The Report is a structured artifact. Citations are stable sN and pN IDs. The final markdown is rendered with inline [pN] references for every claim. Verifiers walk the report against the raw Passages slice to catch fabricated IDs.

Backends

Configured via env at startup; NewWebSearchTool picks in order:

• BRAVE_API_KEY set: Brave.
• SEARXNG_URL set: SearXNG.
• fallback: DuckDuckGo HTML.

Where the report lives

~/.carlos/frames/<frame>/research/<slug>-<unix-ts>.md (0600). The slash variant also persists the rendered Report as one EvtAssistantMessage in the conversation transcript, so it survives the session and stays searchable.

Tail roadmap

Related

Agent loop comparison shows where research sits relative to the broader loop. Sub-agents covers spawn caps and tracker plumbing the engine inherits when invoked via /research. Tools documents web_search and web_fetch in full; slash commands covers /research.