Shark

🦈 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:

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

┌─────────────┐
│  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):

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

Good (Shark-style non-blocking):

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

Slow tools (always spawn):

Fast tools (run inline, never spawn):

2. Spawn remoras

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:

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

| Operation | Budget | Action | |-----------|--------|--------| | File read | < 2s | Inline | | Web search | 5-30s | Spawn | | SSH command | 10-120s | Spawn | | Build/test | 30-300s | Spawn | | Coding agent | 60-600s | Spawn | | Memory search | < 3s | Inline |

Example: Multi-Step Research Task

Without Shark (blocking):

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):

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

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.

🦈 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:

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

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

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

Example

// 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?"

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

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

remora crash / error

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

Partial results (most common)

>50% remoras failed

All remoras failed

Forgetting to spawn the pilot fish (most common mistake)

Pilot fish killed mid-run

Terminology

runTimeoutSeconds — confirmed real

Pilot Fish Sizing Formula

pilotFishTimeout = min(estimatedRemaining * 0.8, 25)

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

Hard Limits

Enforcing the 30-Second Timeout

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

OpenClaw subagents

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

exec calls (shell, SSH, scripts)

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
})

Gemini CLI via exec

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

Pilot fish — always use runTimeoutSeconds

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

What happens when timeout fires

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

The LLM turn itself

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)

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

Codex

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

Codex-specific lifecycle:

Gemini CLI

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
})

Mixed fleets

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 type | Best runtime | |-----------|-------------| | Code generation / editing | Codex | | Web search / summarise | Gemini CLI | | Multi-step reasoning | Claude subagent | | File ops / SSH / shell | exec (background) | | Pre-analysis / drafting | Claude subagent (pilot fish) |

shark-exec Sub-Skill

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

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:

./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 case | Approach | |----------|----------| | Single fast task (<30s total) | claude --print "..." directly | | Multi-step task, slow tools | ./shark.sh "..." loop | | CI/build watching | shark-exec (background + cron) | | Interactive chat | OpenClaw main session |

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | SHARK_MAX_LOOPS | 50 | Maximum iterations before giving up | | SHARK_LOOP_TIMEOUT | 25 | Per-turn timeout in seconds (hard kill) |

Completion protocol

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

TASK_COMPLETE

Commands

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

/shark

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 [--max-loops N] [--timeout S]

Run the external shark loop enforcer. Execute:

$env:SHARK_MAX_LOOPS = ""
$env:SHARK_LOOP_TIMEOUT = ""
powershell.exe -ExecutionPolicy Bypass -File "/shark.ps1" ""

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

   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
   

// 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