Hamsterrädli (research-loop)
Usage: research-loop <new|cycle|run|status> [loop-name] [seed...] (Claude Code:
/research-loop ...; Codex: $research-loop ...). With no op, run status.
Converted from BitWonka's loop-engine commands
(/research-new, /research-cycle, /run-loop, /research-status, commit 8c133a7, MIT;
see LICENSE) and adapted to a local setup with Claude Code and Codex.
Where loops live
A loop is one folder, and optionally its own Obsidian vault:
- A loop that serves a campaign lives in that campaign's knowledge repo, at
<repo>/loops/<loop-name>, so its notes are committed with the lane's journal.
- Any other loop lives under
LOOPS="${RESEARCH_LOOPS_ROOT:-$HOME/research-loops}".
<loop>/
├── Engine/Config.md # seed, caps, status (frontmatter); the Research method section
├── Engine/Queue.md # `- [ ] [d=N] question (parent:: [[Note]])` items
├── Engine/Log.md # one table row per researched topic
├── Engine/Map.md # `- [[Title]] · d<n> · <date>` index of notes
├── Findings.md # the digest: the one file a human reads
└── Research/ # one note per researched question
Below, <loop> is that folder: for a loop name, <repo>/loops/<name> in the campaign repo you
are working in when it exists, else $LOOPS/<name>. <scratch> is
${TMPDIR:-/tmp}/research-loop/<loop-name> (create it with mkdir -p; it is disposable), the
only place for downloads and other working files. Take timestamps from
date "+%Y-%m-%d %H:%M" (set TZ once per machine); dates are +%Y-%m-%d. Obsidian
is optional; read and write the files directly. Each loop gets its own vault, so a personal
vault stays untouched.
Research methods available here
The Research method section of Engine/Config.md names one method; follow it, with any
instructions the user gives for this run taking precedence. These are the tools a
method can use:
| Method |
Tool |
| Web pages |
Find pages with web search (Claude Code: WebSearch, loaded via ToolSearch select:WebSearch when deferred; Codex: its built-in search). Read them with defuddle parse <url> --md (kepano's defuddle CLI, MIT). Use WebFetch or curl -sL for .md, raw, JSON and PDF URLs, and the built-in browser for signed-in pages |
| GitHub repos |
gh api repos/<owner>/<repo>/contents/<path> or a shallow clone into <scratch>; gh is authenticated, the anonymous API is rate-limited |
| Papers |
the elicit-research skill: python3 <elicit-research>/scripts/elicit.py POST /search/papers --body req.json --out resp.json. It reads ~/.config/elicit/api-key. Check GET /usage before a large job |
| Local code or a knowledge repo |
read-only reads of the named folder; git log/git show for history |
| First principles |
reason with no external sources, then self-question to deepen |
| Typed triage |
the jev-second-perspective skill (TypeSafe Jev) to rank a long queue or citation-check the digest against the notes |
Keys stay where they already live (~/.config/<service>/, mode 600) or in the loop's own
.env inside the loop folder. Notes, logs, digests and reports carry no keys or tokens.
new: scaffold a loop
- Pick
<loop> per "Where loops live". If it exists, say so, point at cycle, and stop.
With no name, ask for one (kebab-case; it is also the vault name).
- Copy the template from this skill's base directory:
mkdir -p "$(dirname "<loop>")" && cp -R "<skill-dir>/assets/template" "<loop>".
- When a seed was given, set it in
Engine/Config.md frontmatter as a double-quoted
string (escape " and \) and add it to Engine/Queue.md under ## Queue as
- [ ] [d=0] <seed> (parent:: seed).
- When the user described how to research, replace the body of the Research method
section with their description; otherwise keep the default web method.
- Only when the user wants Obsidian:
open -a Obsidian "<loop>".
- Report the path, seed and method, and how to run it: one cycle with
research-loop cycle <loop-name>; continuously with /loop /research-loop cycle <loop-name> in
Claude Code. Codex has no /loop: each invocation runs one cycle.
cycle: one queue-expanding cycle
Do exactly one cycle, then stop; under /loop it is re-invoked.
Load config. Read Engine/Config.md: seed, notes_per_run (default 1),
max_depth (default 3), max_breadth (default 3), continuous (default false), digest (default
Findings.md), status, and the Research method section (the section only; the
"Method examples" section after it is editing help). status: paused → print
⏸ paused and stop. A seed passed in the arguments replaces the configured one: write
it to the frontmatter and queue it as in new step 3.
Build the worklist of up to notes_per_run items, taken top-down from the lines
under ## Queue in Engine/Queue.md that start with - [ ]:
- Mark pending items deeper than
max_depth as skipped: - [-].
- When the queue holds no items at all, add the seed as
- [ ] [d=0] <seed> (parent:: seed).
The first cycle therefore researches the seed alone; later cycles fill up from its
follow-ups.
- Still short, with
continuous: true: skim Map.md and the notes, then add fresh
[d=0] directions toward the seed that existing notes do not cover.
- Still empty, with
continuous: false: print
✅ research complete: queue drained; stop the /loop and stop.
Done when the worklist holds the items this cycle will research.
Fan out, one researcher per worklist item. In Claude Code, launch them in a single
message as general-purpose Agent subagents (so they can Write). In Codex, or anywhere
without a subagent tool, research the items yourself one after another. Each researcher
gets the loop path, the Research method, its one question with its depth, the other
worklist questions of this cycle (to avoid overlapping them), and these instructions:
- When a note in
Research/ already covers the question well, write nothing and return
skipped: [[<that note>]].
- Research it per the method and cite every source. A method with no external sources
writes
1. none (first principles) under Sources. Downloads and working files go to
<scratch> only, and notes never link into it.
- Write exactly one note,
<loop>/Research/<title>.md, in the shape below. Choose a
title without ? : / \ # | [ ] ^, so the file name, the title: line and every
[[link]] are identical. If the Write tool refuses the file, write it with a shell
heredoc. Touch no other file in the loop and no external repository.
- Return the note title and at most
max_breadth follow-up questions.
---
title: "<clear, specific title; equals the file name>"
created: <TZ=Europe/Zurich date "+%Y-%m-%d %H:%M">
tags: [research, depth/<n>]
depth: <n>
parent: "<[[Parent Note]], or seed for a d=0 question>"
status: complete
---
# <title>
> [!summary] TL;DR
> 2-4 sentences.
## Key findings
- ...with inline source refs; mark each as measured, cited or inferred
## Details
## Open questions
- <the follow-ups it raises>
## Sources
1. [title](url or DOI): note (abstract-only or full text)
## Related
- [[Parent Note]] / siblings
Collect and refill, as the orchestrator, serially (you alone write the Engine files
and the digest, so researchers never race on them). For every returned result:
- a skip: mark its item
- [-] and move on;
- mark its item
[x] in Queue.md;
- append its follow-ups as
- [ ] [d=<depth+1>] <question> (parent:: [[<title>]]) when
depth+1 ≤ max_depth, deduplicated against existing notes and queue items; deeper
follow-ups go to the digest's Open questions instead;
- append
- [[<title>]] · d<depth> · <date> to Map.md;
- append
| <n> | <timestamp now> | <depth> | <question, with | replaced by /> | [[<title>]] | <k> queued |
to Log.md, numbering rows from 1.
Done when every written note appears in Map.md and Log.md.
Rewrite the digest (digest, default Findings.md, shipped in the template): a
ranked, deduplicated living summary that folds in this cycle's notes, drops stale items
and links the [[notes]]. Follow the digest structure the Research method names;
otherwise a ranked "Key findings" list plus "Open questions". Skimmable in about 30
seconds. When the top finding is about to drive a decision (kill a route, spend money,
submit), have Claude Fable try to refute it first (Claude Code: an Agent call with
model: fable; Codex: the send-to-claude-fable skill) and record the verdict in the
digest.
Report in 3-5 lines: the loop, notes written this cycle, follow-ups queued, total
notes, and whether it continues on the next tick or is complete.
When a cycle runs inside a subagent, Claude Code's Write tool can refuse loop files as
"report files"; update them with Edit, or write them with a shell heredoc. They are loop
state, not reports.
run: one tool-assisted cycle
For loops whose Research method names a private data tool kept in the loop folder (for
example <loop>/scan.py: a leaderboard fetch and diff, an API poll). The tool supplies cheap
raw data; the analysis is yours.
- Read
Engine/Config.md; status: paused → print ⏸ paused and stop.
- Follow the Research method literally. Typically run the helper from the loop folder with
its own env, so only its compact digest enters your context:
(cd "<loop>" || exit 1; set -a; if [ -f .env ]; then . ./.env; fi; set +a; python3 scan.py).
- Find the signal (the largest changes, anything new; ignore noise), research the items no
note in
Research/ covers yet, and write analytical notes with [[wikilinks]] plus any
thesis or index file the method names. Interpret the data; a pasted digest is not a note.
- Append a heartbeat row to
Engine/Log.md.
- Report in 3-5 lines: the key moves, what you researched and concluded, the notes written.
Keep it running with /loop 15m /research-loop run <loop-name> in Claude Code.
status: overview of all loops
Read from disk. Loops are the folders under $LOOPS plus any loops/* folder in the
campaign repo you are working in. For each loop read Config.md frontmatter; count the lines
under ## Queue in Queue.md that start with - [ ] (pending), - [x] (done) and - [-]
(skipped); count the .md notes in Research/; take the deepest depth: among them; and
take the When of the last Log.md row.
- No loop name: one table
| Loop | Status | Notes | Pending | Done | Skipped | Deepest/max | Last activity | Seed |,
with Deepest - when there are no notes and the seed without its quotes.
- With a loop name: its seed, the caps (
max_depth, max_breadth, notes_per_run,
continuous), a method summary, the pending items with depths, and the last few log rows.
- No loops: say so and suggest
research-loop new <name> <seed>.
Running loops
A loop occupies the session it runs in. Run each one in a background agent or its own
session so the main session stays responsive; loops are independent, so several can run at
once. Pause one with status: paused in its Config.md, or by stopping its /loop.
1---2name: research-loop3description: "Run a self-expanding research loop. Each cycle sends parallel researcher agents after open questions, each writes one linked Markdown note, and their follow-up questions refill the queue. Use to start a loop on a seed question, run a cycle, run a tool-assisted monitor cycle, or report loop status. Adapted from BitWonka's loop-engine (MIT)."4license: MIT (adapted from BitWonka/loop-engine; see LICENSE)5metadata:6 source: https://skillmd.com/skills/odinfree/research-loop7---89# Hamsterrädli (research-loop)1011Usage: `research-loop <new|cycle|run|status> [loop-name] [seed...]` (Claude Code:12`/research-loop ...`; Codex: `$research-loop ...`). With no op, run `status`.1314Converted from BitWonka's [loop-engine](https://github.com/BitWonka/loop-engine) commands15(`/research-new`, `/research-cycle`, `/run-loop`, `/research-status`, commit 8c133a7, MIT;16see `LICENSE`) and adapted to a local setup with Claude Code and Codex.1718## Where loops live1920A **loop** is one folder, and optionally its own Obsidian vault:2122- A loop that serves a campaign lives in that campaign's knowledge repo, at23 `<repo>/loops/<loop-name>`, so its notes are committed with the lane's journal.24- Any other loop lives under `LOOPS="${RESEARCH_LOOPS_ROOT:-$HOME/research-loops}"`.2526```27<loop>/28├── Engine/Config.md # seed, caps, status (frontmatter); the Research method section29├── Engine/Queue.md # `- [ ] [d=N] question (parent:: [[Note]])` items30├── Engine/Log.md # one table row per researched topic31├── Engine/Map.md # `- [[Title]] · d<n> · <date>` index of notes32├── Findings.md # the digest: the one file a human reads33└── Research/ # one note per researched question34```3536Below, `<loop>` is that folder: for a loop name, `<repo>/loops/<name>` in the campaign repo you37are working in when it exists, else `$LOOPS/<name>`. `<scratch>` is38`${TMPDIR:-/tmp}/research-loop/<loop-name>` (create it with `mkdir -p`; it is disposable), the39only place for downloads and other working files. Take timestamps from40`date "+%Y-%m-%d %H:%M"` (set `TZ` once per machine); dates are `+%Y-%m-%d`. Obsidian41is optional; read and write the files directly. Each loop gets its own vault, so a personal42vault stays untouched.4344## Research methods available here4546The **Research method** section of `Engine/Config.md` names one method; follow it, with any47instructions the user gives for this run taking precedence. These are the tools a48method can use:4950| Method | Tool |51|---|---|52| Web pages | Find pages with web search (Claude Code: `WebSearch`, loaded via ToolSearch `select:WebSearch` when deferred; Codex: its built-in search). Read them with `defuddle parse <url> --md` (kepano's [defuddle](https://github.com/kepano/defuddle) CLI, MIT). Use WebFetch or `curl -sL` for `.md`, raw, JSON and PDF URLs, and the built-in browser for signed-in pages |53| GitHub repos | `gh api repos/<owner>/<repo>/contents/<path>` or a shallow clone into `<scratch>`; `gh` is authenticated, the anonymous API is rate-limited |54| Papers | the `elicit-research` skill: `python3 <elicit-research>/scripts/elicit.py POST /search/papers --body req.json --out resp.json`. It reads `~/.config/elicit/api-key`. Check `GET /usage` before a large job |55| Local code or a knowledge repo | read-only reads of the named folder; `git log`/`git show` for history |56| First principles | reason with no external sources, then self-question to deepen |57| Typed triage | the jev-second-perspective skill (TypeSafe Jev) to rank a long queue or citation-check the digest against the notes |5859Keys stay where they already live (`~/.config/<service>/`, mode 600) or in the loop's own60`.env` inside the loop folder. Notes, logs, digests and reports carry no keys or tokens.6162## `new`: scaffold a loop63641. Pick `<loop>` per "Where loops live". If it exists, say so, point at `cycle`, and stop.65 With no name, ask for one (kebab-case; it is also the vault name).662. Copy the template from this skill's base directory:67 `mkdir -p "$(dirname "<loop>")" && cp -R "<skill-dir>/assets/template" "<loop>"`.683. When a seed was given, set it in `Engine/Config.md` frontmatter as a double-quoted69 string (escape `"` and `\`) and add it to `Engine/Queue.md` under `## Queue` as70 `- [ ] [d=0] <seed> (parent:: seed)`.714. When the user described how to research, replace the body of the **Research method**72 section with their description; otherwise keep the default web method.735. Only when the user wants Obsidian: `open -a Obsidian "<loop>"`.746. Report the path, seed and method, and how to run it: one cycle with `research-loop75 cycle <loop-name>`; continuously with `/loop /research-loop cycle <loop-name>` in76 Claude Code. Codex has no `/loop`: each invocation runs one cycle.7778## `cycle`: one queue-expanding cycle7980Do exactly one cycle, then stop; under `/loop` it is re-invoked.81821. **Load config.** Read `Engine/Config.md`: `seed`, `notes_per_run` (default 1),83 `max_depth` (default 3), `max_breadth` (default 3), `continuous` (default false), `digest` (default84 `Findings.md`), `status`, and the **Research method** section (the section only; the85 "Method examples" section after it is editing help). `status: paused` → print86 `⏸ paused` and stop. A seed passed in the arguments replaces the configured one: write87 it to the frontmatter and queue it as in `new` step 3.882. **Build the worklist** of up to `notes_per_run` items, taken top-down from the lines89 under `## Queue` in `Engine/Queue.md` that start with `- [ ]`:90 - Mark pending items deeper than `max_depth` as skipped: `- [-]`.91 - When the queue holds no items at all, add the seed as `- [ ] [d=0] <seed> (parent:: seed)`.92 The first cycle therefore researches the seed alone; later cycles fill up from its93 follow-ups.94 - Still short, with `continuous: true`: skim `Map.md` and the notes, then add fresh95 `[d=0]` directions toward the seed that existing notes do not cover.96 - Still empty, with `continuous: false`: print97 `✅ research complete: queue drained; stop the /loop` and stop.98 Done when the worklist holds the items this cycle will research.993. **Fan out**, one researcher per worklist item. In Claude Code, launch them in a single100 message as `general-purpose` Agent subagents (so they can Write). In Codex, or anywhere101 without a subagent tool, research the items yourself one after another. Each researcher102 gets the loop path, the Research method, its one question with its depth, the other103 worklist questions of this cycle (to avoid overlapping them), and these instructions:104 - When a note in `Research/` already covers the question well, write nothing and return105 `skipped: [[<that note>]]`.106 - Research it per the method and cite every source. A method with no external sources107 writes `1. none (first principles)` under Sources. Downloads and working files go to108 `<scratch>` only, and notes never link into it.109 - Write exactly one note, `<loop>/Research/<title>.md`, in the shape below. Choose a110 title without `? : / \ # | [ ] ^`, so the file name, the `title:` line and every111 `[[link]]` are identical. If the Write tool refuses the file, write it with a shell112 heredoc. Touch no other file in the loop and no external repository.113 - Return the note title and at most `max_breadth` follow-up questions.114115 ```markdown116 ---117 title: "<clear, specific title; equals the file name>"118 created: <TZ=Europe/Zurich date "+%Y-%m-%d %H:%M">119 tags: [research, depth/<n>]120 depth: <n>121 parent: "<[[Parent Note]], or seed for a d=0 question>"122 status: complete123 ---124 # <title>125 > [!summary] TL;DR126 > 2-4 sentences.127 ## Key findings128 - ...with inline source refs; mark each as measured, cited or inferred129 ## Details130 ## Open questions131 - <the follow-ups it raises>132 ## Sources133 1. [title](url or DOI): note (abstract-only or full text)134 ## Related135 - [[Parent Note]] / siblings136 ```1374. **Collect and refill**, as the orchestrator, serially (you alone write the Engine files138 and the digest, so researchers never race on them). For every returned result:139 - a skip: mark its item `- [-]` and move on;140 - mark its item `[x]` in `Queue.md`;141 - append its follow-ups as `- [ ] [d=<depth+1>] <question> (parent:: [[<title>]])` when142 `depth+1` ≤ `max_depth`, deduplicated against existing notes and queue items; deeper143 follow-ups go to the digest's Open questions instead;144 - append `- [[<title>]] · d<depth> · <date>` to `Map.md`;145 - append `| <n> | <timestamp now> | <depth> | <question, with | replaced by /> | [[<title>]] | <k> queued |`146 to `Log.md`, numbering rows from 1.147 Done when every written note appears in `Map.md` and `Log.md`.1485. **Rewrite the digest** (`digest`, default `Findings.md`, shipped in the template): a149 ranked, deduplicated living summary that folds in this cycle's notes, drops stale items150 and links the `[[notes]]`. Follow the digest structure the Research method names;151 otherwise a ranked "Key findings" list plus "Open questions". Skimmable in about 30152 seconds. When the top finding is about to drive a decision (kill a route, spend money,153 submit), have Claude Fable try to refute it first (Claude Code: an Agent call with154 `model: fable`; Codex: the send-to-claude-fable skill) and record the verdict in the155 digest.1566. **Report** in 3-5 lines: the loop, notes written this cycle, follow-ups queued, total157 notes, and whether it continues on the next tick or is complete.158159When a cycle runs inside a subagent, Claude Code's Write tool can refuse loop files as160"report files"; update them with Edit, or write them with a shell heredoc. They are loop161state, not reports.162163## `run`: one tool-assisted cycle164165For loops whose Research method names a private data tool kept in the loop folder (for166example `<loop>/scan.py`: a leaderboard fetch and diff, an API poll). The tool supplies cheap167raw data; the analysis is yours.1681691. Read `Engine/Config.md`; `status: paused` → print `⏸ paused` and stop.1702. Follow the Research method literally. Typically run the helper from the loop folder with171 its own env, so only its compact digest enters your context:172 `(cd "<loop>" || exit 1; set -a; if [ -f .env ]; then . ./.env; fi; set +a; python3 scan.py)`.1733. Find the signal (the largest changes, anything new; ignore noise), research the items no174 note in `Research/` covers yet, and write analytical notes with `[[wikilinks]]` plus any175 thesis or index file the method names. Interpret the data; a pasted digest is not a note.1764. Append a heartbeat row to `Engine/Log.md`.1775. Report in 3-5 lines: the key moves, what you researched and concluded, the notes written.178179Keep it running with `/loop 15m /research-loop run <loop-name>` in Claude Code.180181## `status`: overview of all loops182183Read from disk. Loops are the folders under `$LOOPS` plus any `loops/*` folder in the184campaign repo you are working in. For each loop read `Config.md` frontmatter; count the lines185under `## Queue` in `Queue.md` that start with `- [ ]` (pending), `- [x]` (done) and `- [-]`186(skipped); count the `.md` notes in `Research/`; take the deepest `depth:` among them; and187take the When of the last `Log.md` row.188189- No loop name: one table190 `| Loop | Status | Notes | Pending | Done | Skipped | Deepest/max | Last activity | Seed |`,191 with Deepest `-` when there are no notes and the seed without its quotes.192- With a loop name: its seed, the caps (`max_depth`, `max_breadth`, `notes_per_run`,193 `continuous`), a method summary, the pending items with depths, and the last few log rows.194- No loops: say so and suggest `research-loop new <name> <seed>`.195196## Running loops197198A loop occupies the session it runs in. Run each one in a background agent or its own199session so the main session stays responsive; loops are independent, so several can run at200once. Pause one with `status: paused` in its `Config.md`, or by stopping its `/loop`.