1---
2name: researching-with-rumilo
3description: Dispatches AI research subagents via rumilo to search the web or explore git repositories. Use when the user asks to research a topic, look up library usage, explore a codebase, read documentation from the web, or when you need information from an external repository or website to complete a task.
4user-invocable: true
5license: LicenseRef-MutuaL-1.2
6metadata:
7 author: Amolith <amolith@secluded.site>
8---
9
10`rumilo` spawns disposable AI subagents for two kinds of research: **web search** and **repo exploration**. Each mode runs in isolation and returns a synthesised answer on stdout.
11
12## Important: timeouts
13
14Rúmilo is an LLM-based subagent that may take multiple turns to complete its research. _Never_ impose a timeout.
15
16## Modes
17
18### Web mode
19
20Search the internet or ask questions about a specific page.
21
22```bash
23# Open-ended search (no URL)
24rumilo web "what is the current stable version of Zig"
25
26# Question about a specific page (URL pre-fetched into context)
27rumilo web "how does the slog package handle log levels" -u "https://pkg.go.dev/log/slog"
28```
29
30- Without `-u`, the agent searches the web on its own.
31- With `-u`, the URL is fetched first and injected into the agent's context alongside the query, so it can answer questions _about_ that page.
32
33### Repo mode
34
35Clone a git repository into a temp directory, spawn an agent inside it, and let it explore the source to answer questions.
36
37```bash
38# Public repo
39rumilo repo -u "https://github.com/owner/repo" "How does the routing system work?"
40
41# Private repo (works with any clonable URI — SSH, HTTPS with auth, etc.)
42rumilo repo -u "git@git.sr.ht:~user/repo" "What does the Config struct look like?"
43```
44
45The `-u` flag is **required** in repo mode — it needs something to clone.
46
47## Flags
48
49| Flag | Modes | Effect |
50| -------------------------- | ----- | ----------------------------------------------------------------- |
51| `-u <url>` | both | Seed URL (web) or clone URI (repo) |
52| `--model <provider:model>` | both | Override the configured default model |
53| `--ref <ref>` | repo | Checkout a branch, tag, or commit after cloning (requires --full) |
54| `--full` | repo | Full clone instead of shallow (depth 1) |
55| `--no-cleanup` | both | Keep the temp workspace after exit |
56| `--verbose` | both | Print tool calls and results to stderr |
57
58## Crafting queries
59
60Rumilo works best with focused queries. Think about **scope** and **coupling** when deciding what to ask and how many questions to include.
61
62- **Tightly coupled, narrow scope** — multiple simple questions in one call is fine when they're about the same small surface area (a single file, one struct, one API endpoint).
63- **Broad scope or loose coupling** — one question per invocation. If answering requires exploring many files or pages, keep it to a single clear question so the agent can focus.
64- **Write natural questions, not keyword lists.** Rumilo is an LLM, not a search index.
65- **Sequence calls when later questions depend on earlier answers.** Get the overview first, then drill in. Rumilo is amnesic — each invocation starts fresh. If a later query depends on an earlier answer (repo URL, version number, file paths), you must include that context explicitly in the prompt.
66- **Run independent queries in parallel** (e.g. via separate tmux windows or backgrounded commands), but keep dependent queries sequential.
67
68### Bad
69
70Overloaded — five loosely-coupled questions spanning an entire diff, each requiring different context:
71
72```bash
73rumilo web "In this diff, find: 1. What files are modified and created \
742. What config options each channel exposes 3. How messages are formatted \
754. The architecture for adding a new channel 5. What UI components exist" \
76 -u "https://example.com/commit/abc123.diff"
77```
78
79### Good
80
81Sequenced calls, each with a clear scope. Later calls include non-obvious context from earlier results — file paths, symbol names, patterns — so rumilo can go straight to the answer instead of searching.
82
83```bash
84# 1. Lay of the land — broad overview first
85rumilo web "What files were modified or created, and what's the broad shape of the change?" \
86 -u "https://example.com/commit/abc123.diff"
87
88# 2a and 2b can run in parallel — neither depends on the other,
89# but both benefit from context learned in step 1.
90
91# 2a. Architecture deep-dive, pointing to the key file discovered in step 1
92rumilo web "How is the notification system in pkg/notify/ architected? \
93 Each channel seems to implement a Sender interface — what's the process \
94 for adding a new one?" \
95 -u "https://example.com/commit/abc123.diff"
96
97# 2b. Config drill-down, referencing the settings struct found in step 1
98rumilo web "What configuration options does each channel expose in \
99 ChannelSettings? Can message content be customised?" \
100 -u "https://example.com/commit/abc123.diff"
101
102# 3. UI specifics, narrowed by what steps 1–2 revealed about the component tree
103rumilo web "The channel config UI lives in web/src/components/settings/channels/. \
104 Do the per-channel forms follow a shared pattern or component?" \
105 -u "https://example.com/commit/abc123.diff"
106```
107
108Don't include context that's obvious or redundant — telling rumilo to "search for notif" when asking about notifications wastes tokens. Focus on non-obvious anchors: exact file paths, struct names, interface signatures.
109
110Tightly coupled questions in a single call are fine when the scope is small:
111
112```bash
113rumilo repo -u "https://github.com/owner/repo" \
114 "What fields does the Config struct have and which are optional?"
115```
116
117## Choosing a mode
118
119- Need to find or learn about a library? **Web** to locate it, then **repo** to explore its source.
120- Need to understand how a dependency works in detail? **Repo** with the dependency's clone URL.
121- Need current docs, release notes, or general knowledge? **Web**, optionally with the URL of a relevant page.