Litmus — Run a Parallel Autonomous ML Research Organization on your OpenClaw instance.

Litmus is an OpenClaw skill that turns your always-on GPU machine into a self-directing ML research lab. Multiple native subagents run experiments overnight, each on their own git branch. A Director steers them every two hours. A Synthesizer distills collective knowledge into a reusable skills library at 04:00. A circadian rhythm shifts agents into creative thinking at 03:00. A research narrative lands in your chat by 08:00.

Built on Karpathy's autoresearch. Everything is a native sessions_spawn subagent — no external CLI processes, no PID files.

Website · Docs · ClawHub

Install by asking your OpenClaw agent:

"Install https://clawhub.ai/kuberwastaken/litmus and set it up for my machine"

Your agent checks your GPU, pitches a full schedule (with timing presets), spawns workers, and registers cron jobs — all in one conversation.

What Litmus does that autoresearch doesn't

| Feature | autoresearch | Litmus | |---|---|---| | Parallel agents | 1 | 2–8 workers, each on their own git branch | | Experiment history | Per-run log | Full git tree — every experiment a commit, cherry-pick across agents | | Cross-agent learning | — | Shared discoveries.md, anomalies.md, structured notes/ | | Knowledge accumulation | — | Skills library — validated techniques agents build on, never re-discover | | Knowledge distillation | — | Synthesizer — nightly agent that reads all results and writes reusable skills | | Active direction | — | Director cron every 2h | | Stagnation response | — | Compass Reset — Director reads skills gap + git history, steers to unexplored combos | | Dead-end pruning | — | Two-phase budget — 90s quick check before full run, abandon early | | Structured results | — | JSON attempt record per experiment in shared/attempts/ | | Creative thinking | — | Leisure mode 03:00–06:00, paper reading, moonshot hypotheses | | Paper-grounded ideas | — | arxiv scan → experiment queue | | Morning briefing | — | Digest to your chat at 08:00 | | Setup | Manual | Conversational — pitches defaults, asks for changes |

Architecture

YOU ──▶ OpenClaw agent
             │
             ├── sessions_spawn ──▶ worker-arch-1 ──┐  each on its own git branch
             ├── sessions_spawn ──▶ worker-opt-2  ──┤  in ~/.litmus/repo/
             ├── sessions_spawn ──▶ worker-gen-3  ──┘
             └── sessions_yield
                                        │
                               ~/.litmus/shared/
                                  attempts/       ← JSON record per experiment
                                  notes/          ← structured YAML-frontmatter notes
                                  skills/         ← validated reusable techniques
                                  discoveries.md
                                  anomalies.md

Director (cron · every 2h during research hours)
  └── reads shared/attempts/ → computes improvement rates
  └── Compass Reset on ≥6 experiments without improvement
  └── cross-pollinates discoveries across agents
  └── assigns anomaly investigation

03:00 ── litmus-leisure   ── arxiv scan · contradiction analysis · writes notes/moonshots/
04:00 ── litmus-synthesizer ── distills notes + attempts → skills/ + research agenda
06:00 ── litmus-dawn      ── reads synthesizer output · queues experiments · wakes workers
08:00 ── litmus-digest    ────────────────────────────────────────────────▶ YOUR CHAT

The shared git repo at ~/.litmus/repo/ holds every agent's branch. Browse the full experiment tree any time:

git -C ~/.litmus/repo log --all --oneline --graph

Cron Layer

All times are defaults — configurable during onboarding.

| Job | Default schedule | Role | |---|---|---| | litmus-director | Every 2h during research hours | Reviews results, Compass Reset on stagnation, cross-pollination | | litmus-leisure | 03:00 daily | Switches workers to thinking mode; reads arxiv; writes structured notes | | litmus-synthesizer | 04:00 daily | Distills notes + attempts into skills library; writes research agenda | | litmus-dawn | 06:00 daily | Reads synthesizer output; queues today's experiments; wakes workers | | litmus-watchdog | Every 30 min | Liveness check, disk check, escape mode on zero improvements | | litmus-digest | 08:00 daily | Morning research narrative → delivered to your chat | | litmus-archive | Every 3 days | Cleanup old attempts + multi-day research checkpoint |

Configuration

Onboarding pitches all defaults and asks what you'd like to change. Common presets:

| Preset | Leisure | Synthesizer | Dawn | Digest | |---|---|---|---|---| | Standard (default) | 03:00 | 04:00 | 06:00 | 08:00 | | Night owl | 01:00 | 02:00 | 04:00 | 07:00 | | Early bird | 23:00 | 00:30 | 02:00 | 05:30 |

Full config options saved to ~/.litmus/config.json:

| Category | Setting | Default | |---|---|---| | Timing | timezone | ask | | Timing | leisure start | 03:00 | | Timing | synthesizer time | 04:00 | | Timing | dawn / research resume | 06:00 | | Timing | digest delivery | 08:00 | | Timing | director interval | every 2h | | Timing | watchdog interval | every 30 min | | Compute | agent count | GPU-based | | Compute | experiment budget | 300s (5 min) | | Compute | quick-check budget | 90s (cuts dead ends early) | | Research | templates | architecture, general | | Research | custom goal | none | | Leisure | intensity | standard (3 searches · 5 papers · 5 moonshots) | | Runtime | mode | subagents (or claude-code) |

Defaults in configs/default.json. Pass custom times to setup-cron.sh with --leisure-start, --synthesizer-time, --dawn-time, --digest-time, --director-hours, --watchdog-minutes.

Managing Agents

# Status — per-agent experiment counts, best val_bpb, stagnation flags, git tree
bash {baseDir}/scripts/status.sh

# Leaderboard — all agents, from shared/attempts/ JSON
bash {baseDir}/scripts/results.sh --top 10
bash {baseDir}/scripts/results.sh --agent arch-1   # single agent

# Full experiment history as a git tree
git -C ~/.litmus/repo log --all --oneline --graph

# Inspect any specific experiment
git -C ~/.litmus/repo show <commit-hash>
cat ~/.litmus/shared/attempts/<hash>.json

# Steer a worker mid-run (no restart needed)
subagents action:"steer" target:"litmus-worker-arch-1"
  message:"Checkout opt-2's best commit and combine their LR with DEPTH=10."

# Stop everything
subagents action:"kill" target:"all"

Or just tell your agent: "How are my Litmus agents doing?" / "Stop all Litmus agents".

What Agents Write Overnight

| Path | Written by | Contents | |---|---|---| | shared/attempts/<hash>.json | Workers | Structured record per experiment — agent, val_bpb, status, title, commit, parent | | shared/skills/<name>.md | Workers + Synthesizer | Validated reusable techniques with YAML frontmatter and evidence commits | | shared/notes/discoveries/ | Workers | Per-improvement discovery notes with frontmatter | | shared/notes/anomalies/ | Workers + Director | Unexpected result notes | | shared/notes/moonshots/ | Leisure + Workers | Speculative hypotheses from overnight thinking | | shared/notes/synthesis/ | Synthesizer | Research agenda, combination matrix, exhausted areas | | shared/discoveries.md | Workers | Cross-agent best results (flat, for quick reading) | | shared/anomalies.md | Workers + Director | Unexpected results (flat) | | shared/midnight-reflections.md | Leisure | Nightly reflection narrative | | ~/.litmus/repo/ (git) | Workers | All experiment commits on per-agent branches |

Research Templates

| Template | Focus | |---|---| | architecture | Depth, aspect ratio, head dim, WINDOW_PATTERN (SLSL/LSLS/etc) | | optimizer | Per-matrix learning rates, schedule shape, Muon vs AdamW | | regularization | Softcap, gradient clipping, weight decay, residual scaling | | general | Open-ended — combinatorial, tries anything, prefers unexplored combinations |

Requirements

OS: Linux or macOS (Windows not supported)
GPU: NVIDIA with CUDA
uv: curl -LsSf https://astral.sh/uv/install.sh | sh
git: for experiment version control and worktrees
python3: for JSON attempt records and leaderboard scripts

See INSTALL.md for full details.

License

MIT-0 — do whatever you want with it.

Litmus

Install / Use

README