🦈 The Shark Pattern#

A shark that stops swimming dies. An agent that waits for tools wastes compute.

Works with: Claude Code · Codex · Gemini CLI · Cursor · Windsurf · Aider · OpenClaw · any LLM agent

When to Use This Skill#

Trigger this skill when the user says:

• "use the shark pattern"
• "non-blocking agent"
• "never wait for tools"
• "spawn background workers"
• "parallel subagents"
• "keep the main agent moving"
• or when you notice you're about to block on a slow tool (web fetch, SSH, build, test run, API call)

The Rule#

Every LLM turn must complete in under 30 seconds.

If any operation would take longer:

1. Spawn a remora ( sessions_spawn with mode: "run")
2. Continue reasoning immediately
3. Incorporate remora results when they arrive

You are never in I/O wait. You are always reasoning about something.

Lifecycle#

text

┌─────────────┐
│  DECOMPOSE  │  Break task into N independent subtasks
└──────┬──────┘
       │ spawn N remoras (+ 1 pilot fish when first completes early)
       ▼
┌─────────────┐
│    SPAWN    │  sessions_spawn × N, all parallel, record session IDs
└──────┬──────┘
       │ main agent keeps reasoning (never waits)
       ▼
┌─────────────┐     timeout/crash
│   MONITOR   │ ──────────────────► MARK ⏱/❌ (partial still useful)
└──────┬──────┘
       │ all done OR deadline hit
       ▼
┌─────────────┐
│  AGGREGATE  │  Collect results, note failures, merge pilot fish draft
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   REPORT    │  Single coherent response with failure count noted
└─────────────┘

No nested remoras. If a remora is running, it executes inline — remoras cannot spawn their own remoras. Only the main shark spawns.

The Pattern#

Bad (Ralph-style blocking):#

text

think → call slow tool → WAIT 60s → think → call slow tool → WAIT 45s → ...

Good (Shark-style non-blocking):#

text

think → spawn remora(slow tool) → think about something else
     → spawn remora(another tool) → synthesize partial results
     → receive remora result → incorporate → swim on

Implementation#

When applying the Shark Pattern, structure your work like this:

1. Identify blocking operations#

Before calling any tool, ask: "Will this take more than 20-30 seconds?"

Slow tools (always spawn):

• Web searches / page fetches
• SSH commands on remote machines
• Build / test / CI runs
• File system scans over large directories
• API calls with unknown latency
• LLM inference calls (coding agents)

Fast tools (run inline, never spawn):

• Reading local files
• Simple calculations
• String manipulation
• Memory lookups

2. Spawn remoras#

text

sessions_spawn({
  task: "Do the slow thing and return the result",
  mode: "run",
  runtime: "subagent",
  streamTo: "parent"  // optional: stream output back
})

Spawn multiple remoras in parallel when possible — don't serialize unless there's a data dependency.

3. Keep the main fin moving#

After spawning, immediately continue:

• Plan the next step
• Work on a different part of the task
• Summarize what you know so far
• Prepare to incorporate results

4. Incorporate results#

When remora results arrive, weave them in and continue. Never re-do work a remora already completed.

If your runtime keeps subagents alive after completion, close them once you've incorporated their result. In Codex that means: wait for the remora, use its output, then close_agent(id) unless you intentionally plan to reuse that same agent.

Timing Budget#

OperationBudgetActionFile read< 2sInlineWeb search5-30sSpawnSSH command10-120sSpawnBuild/test30-300sSpawnCoding agent60-600sSpawnMemory search< 3sInline

Example: Multi-Step Research Task#

Without Shark (blocking):

text

1. Search web for X        [wait 15s]
2. Search web for Y        [wait 12s]
3. Fetch page Z            [wait 8s]
4. SSH check server        [wait 30s]
Total: ~65 seconds blocked

With Shark (non-blocking):

text

1. Spawn: search X         [0s - spawned]
2. Spawn: search Y         [0s - spawned]
3. Spawn: fetch Z          [0s - spawned]
4. Spawn: SSH check        [0s - spawned]
5. Plan synthesis while waiting [15s of actual thinking]
6. All results arrive → synthesize
Total: ~15s of thinking + max(tool times) in parallel

Output Format#

Announce on start#

🦈 Shark mode — spawning [N] remoras for [tasks], continuing...

Progress bar (chat-friendly, Unicode only — no images needed)#

Use this format after each remora or pilot fish completes. Works in Telegram, Discord, Signal, iMessage — anywhere.

text

🦈 3 remoras · 1 pilot fish

◉ [A] task name here    ████████████ ✅ 9s
◉ [B] task name here    ████████████ ✅ 33s
○ [C] task name here    ░░░░░░░░░░░░ pending
◈ [P] Pilot fish        ██████░░░░░░ ~14s left

↳ continuing...

Symbols:

• ◉ = remora (completed)
• ○ = remora (pending)
• ⊙ = remora (running)
• ◈ = pilot fish (time-bounded)
• ████████████ = done bar (12 blocks)
• ██████░░░░░░ = partial (filled = elapsed / total budget)
• ░░░░░░░░░░░░ = not started

Progress fill: filled = round(elapsed / timeout * 12) blocks of █, remainder ░

Only post an update when something changes (remora completes or pilot fish starts/ends). Don't spam — one update per event.

Final synthesis#

After all remoras done:

🦈 All fins in — synthesising [N] results + pilot draft

Then deliver the report.

The Pilot Fish Sub-Pattern#

Pilot fish swim alongside sharks doing prep work. When you have idle time, use it.

When one remora returns early and others are still running:

1. Spawn a pilot fish — a time-bounded analysis sub-agent
2. Give it only the partial results so far + a hard timeout equal to the estimated remaining wait
3. Let it pre-validate, pre-analyse, find patterns, draft conclusions
4. Kill it (or it self-terminates) when the last primary remora completes
5. Incorporate whatever the pilot fish produced into the final synthesis

text

remora A ──────► result (early)
remora B ────────────────────────────► result
remora C ──────────────────────────────────► result

main:   spawn A, B, C
        A done → spawn pilot-fish(A's result, timeout=est_remaining)
        pilot-fish: pre-analyse A, draft partial report, validate data...
        B done → pilot-fish still running, feed B's result in (or kill+reuse)
        C done → kill pilot-fish, synthesise A+B+C+pilot-fish draft

Pilot Fish Rules#

• Always time-bounded — pass runTimeoutSeconds equal to estimated remaining wait
• Never blocks — spawned async, main agent continues
• Opportunistic — if it finishes early, bonus; if killed mid-run, partial output is still useful
• One at a time — don't stack pilot fish on pilot fish
• Task: pre-validate data, find gaps, draft structure, flag anomalies, prepare questions

Example#

text

// remoras A (fast) and B (slow) both spawned
// A finishes in 10s, B will take another 30s

// Spawn pilot fish with 25s budget:
sessions_spawn({
  task: "Pre-analyse these results from remora A.
         Validate the data, note any gaps, draft the structure
         of the final report. Stop after 25 seconds.",
  runTimeoutSeconds: 25,
  mode: "run"
})

// Main agent continues doing other work
// When B finishes → kill pilot fish → synthesise A + B + pilot draft

Decision Tree — When to Spawn#

Before every tool call, ask: "Will this take more than 10 seconds?"

text

Estimated time < 10s?  → run inline
Estimated time ≥ 10s?  → spawn remora
Unknown latency?        → spawn remora (assume slow)
Data dependency on another remora? → wait, then inline
Already at 8 remoras? → queue, don't stack

Always spawn: web search/fetch, SSH, build/test, coding agents, CI triggers, API calls with unknown latency Always inline: file read, memory lookup, string ops, math, local config reads

---

Error Handling#

remoras will fail, timeout, or return garbage. Plan for it.

remora timeout#

text

◉ [A] task    ████████████ ⏱ 30s [timeout]

• Treat as partial result — use whatever was returned
• Do not re-spawn the same task (wastes time, likely to timeout again)
• Note the gap in synthesis: "A timed out — data may be incomplete"
• If A's result is critical, spawn a smaller-scoped follow-up shark

remora crash / error#

text

◉ [A] task    ████████████ ❌ [error: connection refused]

• Log the error inline in the progress bar
• Continue synthesis without that result
• Mention the failure in the final report
• Optionally file an issue / alert if it's infrastructure
• If the runtime still shows the remora as open after completion or error, clean it up immediately. In Codex, close completed remoras with close_agent(id) once their output is delivered.

Partial results (most common)#

• Most useful — a remora that timed out at 28s has 28s of work in it
• Always check if partial output is usable before discarding
• Progress bar: ⏱ = timeout with partial, ❌ = hard error with nothing

>50% remoras failed#

• Degrade gracefully — fall back to sequential for remaining work
• Note in report: "⚠️ degraded mode — N/M remoras failed"

All remoras failed#

• Fall back to sequential execution for the most critical task only
• Do not spawn another full fleet — you're likely hitting a systemic issue

Forgetting to spawn the pilot fish (most common mistake)#

• You finished a fast inline task, a remora is still running, and you just... wait
• Symptom: main agent idle, no pilot fish, time wasted
• Fix: always ask after any remora completes early — "what can I pre-draft right now?"
• Even if you have nothing obvious, draft the output structure, prepare questions, or outline the synthesis

Pilot fish killed mid-run#

• Normal and expected — whatever it produced is still useful
• Incorporate partial pilot fish output into synthesis
• Don't wait for it or re-spawn it

---

Terminology#

• remora = a sessions_spawn call with mode: "run", runtime: "subagent", and runTimeoutSeconds set. A remora is specifically a timed sub-agent — untimed subagents are not remoras.
• Pilot fish = a remora spawned after another remora completes, with a short timeout sized to the estimated remaining wait. Purpose: pre-analysis only, never primary work.
• Fleet = the full set of remoras spawned for one task
• Fin moving = the main agent is doing useful work (not waiting)
• No nested remoras = remoras always execute inline — only the main shark spawns

runTimeoutSeconds — confirmed real#

Verified against OpenClaw source: runTimeoutSeconds: z.number().int().min(0).optional() — maps to the subagent wait timeout. Use it. Hard-kills the sub-agent process after N seconds, partial output returned.

---

Pilot Fish Sizing Formula#

text

pilotFishTimeout = min(estimatedRemaining * 0.8, 25)

• estimatedRemaining = how long you think the slowest remaining remora will take
• Cap at 25s so pilot fish always finishes before the main synthesis turn
• If you don't know: use 20s as default

Example: slowest remaining remora estimated at 30s → pilot fish timeout = min(24, 25) = 24s

---

Hard Limits#

• Never use yieldMs > 30000 in exec calls — this holds the main turn hostage
• Never process(action=poll, timeout > 20000) in the main session — same reason
• Never add sleep or wait loops in the main thread
• Always set runTimeoutSeconds on remoras — unbound sub-agents are not sharks
• Always clean up completed remoras — if your runtime requires explicit teardown, do it right after incorporating the result
• Max 8 concurrent remoras — beyond this, context overhead exceeds the gain
• Never stack pilot fish — one at a time, no pilot fish spawning pilot fish
• Spawn tasks ≤ 3 sentences — longer task descriptions need decomposition first

Enforcing the 30-Second Timeout#

The 30s cap isn't just a guideline — here's how to actually enforce it per runtime.

OpenClaw subagents#

js

sessions_spawn({
  task: "...",
  mode: "run",
  runtime: "subagent",
  runTimeoutSeconds: 30   // hard kill after 30s — agent gets SIGTERM
})

runTimeoutSeconds is enforced by the OpenClaw runtime — the sub-agent process is killed if it exceeds it. Partial output is still returned.

exec calls (shell, SSH, scripts)#

js

exec({
  command: "some-slow-command",
  timeout: 30,        // hard kill in seconds
  background: true,   // don't block the main agent turn
  yieldMs: 500        // poll back quickly to check
})

timeout kills the process. background: true means the main agent doesn't wait — it gets a session handle and can check back with process(poll).

Gemini CLI via exec#

bash

timeout 30 gemini -p "task here"
# or on Windows:
Start-Process gemini -ArgumentList '-p "task"' -Wait -Timeout 30

Wrap the CLI invocation with OS-level timeout / Start-Process -Timeout.

Pilot fish — always use runTimeoutSeconds#

js

sessions_spawn({
  task: "pre-analyse partial results, draft structure, flag gaps",
  mode: "run",
  runTimeoutSeconds: estimatedRemainingMs / 1000,  // die before the last remora
})

Set it to slightly less than your estimated remaining wait — so the pilot fish always finishes before you need to synthesise.

What happens when timeout fires#

• Sub-agent/process is killed
• Whatever output was produced so far is returned
• Main agent treats it as a partial result — still useful for synthesis
• Log: [timeout] in the progress bar instead of ✅

text

⊙ [A] slow task    ████████████ ⏱ 30s [timeout — partial result]

The LLM turn itself#

You can't hard-kill an LLM mid-turn, but you can:

1. Keep prompts tight — don't ask for exhaustive analysis in one turn
2. Use thinking: "none" for fast sub-tasks that don't need deep reasoning
3. Break large tasks into smaller shark-able chunks upfront

Rule of thumb: if a task description is >3 sentences, it probably needs to be split into remoras.

Compatibility — Claude, Codex, Gemini CLI#

The Shark Pattern is runtime-agnostic. remoras can be any agent type.

OpenClaw (Claude / Sonnet / Opus)#

text

sessions_spawn({
  task: "...",
  mode: "run",
  runtime: "subagent",
  runTimeoutSeconds: 30   // hard cap for pilot fish
})

Codex#

text

sessions_spawn({
  task: "...",
  runtime: "acp",
  agentId: "codex",
  mode: "run",
  runTimeoutSeconds: 30
})

Codex-specific lifecycle:

• Spawn with spawn_agent(...) or the runtime-equivalent remora launcher
• Check completion with wait_agent(...)
• If you want to reuse the same remora, send more work with send_input(...)
• Otherwise, once the remora has completed and you've incorporated its result, call close_agent(id) so the agent does not linger in the session

Gemini CLI#

Gemini CLI is a local process — spawn via exec with a timeout:

text

exec({
  command: "gemini -p \"task description here\"",
  timeout: 30,            // hard cap in seconds
  background: true,       // don't block main agent
  yieldMs: 500            // check back quickly
})

For Gemini sub-tasks, use exec with timeout + background: true rather than sessions_spawn. Treat the process handle the same way — continue working, collect output when it lands.

Mixed fleets#

You can mix runtimes in the same shark run:

text

spawn remora A → Codex (coding task)
spawn remora B → Gemini (web search / analysis)
spawn remora C → Claude subagent (reasoning)
spawn pilot fish  → Claude subagent (pre-analysis, time-bounded)

Which to use when#

Task typeBest runtimeCode generation / editingCodexWeb search / summariseGemini CLIMulti-step reasoningClaude subagentFile ops / SSH / shellexec (background)Pre-analysis / draftingClaude subagent (pilot fish)

shark-exec Sub-Skill#

For slow shell commands (>5s), use the shark-exec companion skill:

• Located at shark-exec/SKILL.md in this repo
• Wraps any exec call in background + cron poller
• Guarantees main turn completes in <30s even for 10-minute commands
• Use it instead of inline exec whenever the command might block

Loop Enforcement (Ralph-style)#

The 30-second rule is best enforced at the shell level, not inside a turn.

Use shark.sh (or shark.ps1 on Windows) to run Claude in a bounded loop:

sh

./shark.sh "find the latest ChatterPC version, check pve3, summarise GitHub issues"

Each iteration:

1. Builds a fresh prompt: skill context + task + current state
2. Runs claude --print with a hard timeout 25s shell wrapper
3. If Claude times out → loop continues (it's expected — shark pattern means short turns)
4. If Claude writes .shark-done → loop exits

This is identical to the Ralph Loop pattern, but with the Shark Pattern as the prompt — Claude spawns remoras for slow work, keeps each turn under 25s, and the shell loop enforces the hard cut.

When to use the loop vs direct claude#

Use caseApproachSingle fast task (<30s total)claude --print "..." directlyMulti-step task, slow tools./shark.sh "..." loopCI/build watchingshark-exec (background + cron)Interactive chatOpenClaw main session

Environment variables#

VariableDefaultDescriptionSHARK_MAX_LOOPS``50Maximum iterations before giving upSHARK_LOOP_TIMEOUT``25Per-turn timeout in seconds (hard kill)

Completion protocol#

When Claude determines the task is done, it writes to .shark-done:

text

TASK_COMPLETE
<brief summary of what was accomplished>

The loop detects this file and exits cleanly.

Commands#

When the user invokes these commands, follow the instructions for each.

/shark <task>#

Apply the Shark Pattern to the given task. Decompose, spawn remoras for slow ops, keep the main fin moving. Follow all rules in this SKILL.md.

/shark-loop <task> [--max-loops N] [--timeout S]#

Run the external shark loop enforcer. Execute:

text

$env:SHARK_MAX_LOOPS = "<N>"
$env:SHARK_LOOP_TIMEOUT = "<S>"
powershell.exe -ExecutionPolicy Bypass -File "<skill_dir>/shark.ps1" "<task>"

Defaults: --max-loops 50, --timeout 25. On Linux/Mac use shark.sh instead.

/shark-status#

Check current shark state:

1. Read <skill_dir>/shark-exec/state/pending.json — report active background jobs (label, command, elapsed time, whether overdue past maxSeconds)
2. If .shark-done exists, show its contents
3. If SHARK_LOG.md exists, show the last 10 lines
4. If nothing exists, report "No active shark jobs."

/shark-clean#

Remove shark state files: .shark-done, SHARK_LOG.md, shark-exec/state/pending.json. Report what was cleaned.

/shark-autotune#

Analyse timing history and recommend optimal settings.

1. Read <skill_dir>/state/timings.jsonl — each line is: json

   {"ts":1710000000,"loop":1,"elapsed_s":12.3,"timeout_s":25,"result":"ok|timeout|done","task_hash":"abc123"}
   
   

2. If no data, report "No timing data yet. Run tasks with /shark first."

3. Compute and report:

   • Total runs (unique task_hash values) and total loops
   • Median turn time (p50) and p95 turn time
   • Timeout rate — % of turns with result "timeout"
   • Loops to completion — median and max (count loops per task_hash that has a "done" entry)
   • Wasted headroom — sum of (timeout_s - elapsed_s) for result "ok" turns
   • Optimal timeout — p95 turn time + 3s buffer, rounded up to nearest 5s
   • Optimal max_loops — p95 loops-to-completion + 2

4. Show recommendations: text

   Current:     SHARK_LOOP_TIMEOUT=25  SHARK_MAX_LOOPS=50
   Recommended: SHARK_LOOP_TIMEOUT=N   SHARK_MAX_LOOPS=M
   
   Rationale:
   

• p95 turn time is Xs, so timeout of Ns covers 95% with buffer
• p95 completion is N loops, so max_loops of M gives safe margin
• Timeout rate is X% — [>15%: consider splitting tasks | healthy]
• Wasted headroom: Xs total

5. If timeout rate > 30%: "Consider breaking tasks into smaller steps."

6. If median turn time < 5s: "Most turns complete fast. Consider lowering timeout."


## Timing Instrumentation

Both `shark.sh` and `shark.ps1` automatically record per-loop timings to `state/timings.jsonl`. Each entry includes:

- `ts` — Unix timestamp
- `loop` — loop iteration number
- `elapsed_s` — actual wall-clock seconds for this turn
- `timeout_s` — configured timeout for this run
- `result` — `"ok"` (completed), `"timeout"` (hit limit), `"done"` (task finished)
- `task_hash` — 8-char hash correlating loops within a single run

Use `/shark-autotune` to analyse this data and tune your settings.

* * *

## References

- Ralph Loop (sequential baseline): ghuntley.com/ralph/
- OpenClaw sessions\_spawn docs: spawn with `mode: "run"`, `runtime: "subagent"`
- Gemini CLI: `npm install -g @google/gemini-cli`
- The name: sharks use ram ventilation — they literally die if they stop moving