🦈 The Shark Skill
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
What Is This?
The Shark Pattern is a universal non-blocking execution model for AI coding agents.
The rule: Every LLM turn completes in under 30 seconds. Slow operations get spawned as remoras. The main agent never waits.
The Three Fish
| Fish | Role |
|---|
| 🦈 Shark | Main agent — never stops, always reasoning |
| 🐟 Remora | Timed sub-agents — attach to the shark, do the slow work in parallel |
| 🐠 Pilot Fish | Time-bounded pre-analysis — swim ahead while remoras are running |
Why?
The Problem
Most agents work sequentially:
think → slow tool → WAIT 45s → think → slow tool → WAIT 30s → ...
90% of runtime is spent waiting. You're paying for LLM compute while it stares at a spinner.
The Solution — Shark + Remoras
think → spawn 🐟 remora(web search) ────────────────► result
→ spawn 🐟 remora(remote cmd) ──────────────────────► result
→ spawn 🐟 remora(build/test) ──────────────────────────► result
→ 🦈 keep reasoning in parallel
→ first remora back → spawn 🐠 pilot fish (pre-analyse)
→ all remoras back → synthesise + incorporate pilot fish draft
Comparison
| Sequential | Ralph Loop | 🦈 Shark |
|---|
| Execution | Blocking | Iterative, blocking | Parallel, non-blocking |
| Tool wait | Always | Always | Never |
| Idle time | Wasted | Wasted | Pilot fish pre-analysis |
| Speed | Linear | Linear | Bounded by slowest parallel task |
| Works with | Any agent | Any agent | Any agent |
| Prior art | — | ghuntley.com/ralph | Novel — no prior art |
Lifecycle
┌─────────────┐
│ DECOMPOSE │ Break task into N independent subtasks
└──────┬──────┘
│ spawn N remoras in parallel
▼
┌─────────────┐
│ SPAWN │ sessions_spawn × N, record IDs, keep swimming
└──────┬──────┘
│ first remora completes early?
├──────────────────────────────► spawn 🐠 pilot fish (pre-analyse)
│ main agent reasons while waiting
▼
┌─────────────┐ timeout ⏱ / crash ❌
│ MONITOR │ ──────────────────────► partial result still useful
└──────┬──────┘
│ all done or deadline hit
▼
┌─────────────┐
│ AGGREGATE │ Merge results + pilot fish draft, note failures
└──────┬──────┘
│
▼
┌─────────────┐
│ REPORT │ Single coherent response: "3/4 succeeded, 1 timed out"
└─────────────┘
No nested remoras — remoras always run inline. Only the main shark spawns.
Progress Output (chat-friendly)
Works in Telegram, Discord, Signal, iMessage — pure Unicode, no images.
🦈 3 remoras · 1 pilot fish
⊙ [A] web search ████████████ ✅ 12s
⊙ [B] server check ████████████ ✅ 8s
○ [C] build + test ██████░░░░░░ ~18s left
◈ [P] Pilot fish ████░░░░░░░░ ~14s left
↳ synthesising…
Symbols: ◉=done ○=pending ⊙=running ◈=pilot fish ⏱=timeout ❌=error
Bar fill: filled = round(elapsed / timeout * 12) blocks of █, remainder ░
Repo Structure
shark-pattern/
├── SKILL.md # Main shark skill — load this
├── shark.sh # Ralph-style loop enforcer (Linux/Mac)
├── shark.ps1 # Ralph-style loop enforcer (Windows)
├── shark-exec/
│ ├── SKILL.md # Sub-skill: background exec + cron poller
│ ├── scripts/
│ │ └── poll-and-deliver.js
│ └── state/
│ └── .gitkeep
└── tests/
├── lint.sh # Structural lint tests
└── scenarios.md # Behavioural test specs
Install
⚡ Universal one-liner (any agent, any repo)
curl -sO https://raw.githubusercontent.com/keugenek/shark/main/SKILL.md \
&& mv SKILL.md SHARK.md && echo "SHARK.md" >> .gitignore
Drop SHARK.md in your project root. Every agent that reads context files will pick it up.
Claude Code (plugin — recommended)
# Install as a plugin (enables /shark, /shark:loop, /shark:status, etc.)
mkdir -p ~/.claude/plugins/cache/user-local/shark/1.0.0
git clone https://github.com/keugenek/shark /tmp/shark-install \
&& rsync -a --exclude='.git' /tmp/shark-install/ ~/.claude/plugins/cache/user-local/shark/1.0.0/ \
&& rm -rf /tmp/shark-install
Register the plugin — add this entry to ~/.claude/plugins/installed_plugins.json under "plugins":
"shark@user-local": [{
"scope": "user",
"installPath": "~/.claude/plugins/cache/user-local/shark/1.0.0",
"version": "1.0.0",
"installedAt": "2025-01-01T00:00:00.000Z",
"lastUpdated": "2025-01-01T00:00:00.000Z"
}]
Add to ~/.claude/CLAUDE.md:
## Execution Model
See ~/.claude/plugins/cache/user-local/shark/1.0.0/SKILL.md — use the Shark Pattern for any multi-step task with slow tools.
