searchwave — Claude Code plugin: fast web research in your terminal

# Searchwave

Searchwave is a context agent for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) that gets you (and Claude) up to speed on anything in about 60 seconds. 

Think native Claude Code search, but better and more comprehensive. Think Deep Research, but more concise, useful, and right in your terminal and Claude Code workflow.

## How it works

Searchwave works best when configured as a /command in Claude Code, to easily invoke the different modes.

`/wave` runs 3 parallel web searches, selects the best sources, fetches their content, and synthesizes a cited summary. The whole process takes about 60 seconds with no configuration or follow-up questions.

`/deepwave` adds depth control. Before running, it asks how deep (Quick / Standard / Max) and what angle matters most. All tiers use Opus for synthesis. Max mode dispatches 3 parallel research agents, evaluates source quality, and supports iterative follow-up.

Output is structured for terminals: inline citations, survey voice, hard-wrapped at 80 columns.

### Use cases

- Check how a framework or library works before adopting it
- Compare tools or approaches with real data
- Verify technical requirements or compatibility
- Get up to speed on an unfamiliar topic mid-task
- A general web search replacement
- A skill for other agents to use when additional context is necessary outside of pre-trained data

## Installation

### Claude Code (via Plugin Marketplace)

Register the marketplace:

```
/plugin marketplace add rowbradley/searchwave-marketplace
```

Install the plugin:

```
/plugin install searchwave@searchwave-marketplace
```

Restart Claude Code after installing. Commands will be available as `/searchwave:wave` and `/searchwave:deepwave`.

### Shorter Command Names (Recommended)

For `/wave` and `/deepwave` without the namespace prefix, copy the command files locally:

```bash
git clone https://github.com/rowbradley/searchwave.git
cp searchwave/commands/wave.md ~/.claude/commands/
cp searchwave/commands/deepwave.md ~/.claude/commands/
```

Local commands take priority over plugin commands and give you the shorter names.

### Verify Installation

```
/help
```

You should see `/wave` and `/deepwave` in your available commands.

### Manual Install

```bash
git clone https://github.com/rowbradley/searchwave.git
cp -r searchwave/skills/wave ~/.claude/skills/
cp -r searchwave/skills/deepwave ~/.claude/skills/
```

## Commands

| Command | Time | Use when |
|---------|------|----------|
| `/wave [topic]` | ~60s | Quick context — get up to speed fast |
| `/deepwave [topic]` | 70s–10min | Deep evaluation — make a decision with real data |

Start with `/wave`. If you need more depth, it'll be obvious.

## /wave — Quick Context

3 parallel searches → 3 best sources fetched → Sonnet synthesis. No questions asked. You type, it runs.

**What you get:** 300–400 words, inline citations, survey voice. Hard-wrapped at 80 columns for terminal readability.

## /deepwave — Deep Evaluation

Asks two things before running: how deep, and what angle matters most.

| Tier | Time | Architecture |
|------|------|--------------|
| Quick | ~70s | 3 searches, Opus synthesis |
| Standard | ~90s | 6 searches, Opus synthesis |
| Max | ~5–10min | 3 parallel research agents → Opus evaluation → follow-up loop |

**What you get:** Survey-style report with inline citations, source quality notes, and confidence assessment. Max mode adds a "Go Deeper?" loop for iterative exploration.

### How Max Mode Works

```
┌─────────────────────────────────────────┐
│  /deepwave "topic" → Max mode           │
├─────────────────────────────────────────┤
│                                         │
│  Wave 1: 3 parallel research agents     │
│  ┌──────────┬──────────┬──────────┐     │
│  │ Agent A  │ Agent B  │ Agent C  │     │
│  │ Facts    │ How-to   │ Why      │     │
│  │ (what)   │ (how)    │ (why)    │     │
│  └────┬─────┴────┬─────┴────┬─────┘     │
│       └──────────┼──────────┘           │
│                  ▼                      │
│  Opus Evaluation (quality signals)      │
│       │                                 │
│       ├─ SUFFICIENT → Synthesize        │
│       └─ NEEDS_MORE → Wave 2 → Synth    │
│                                         │
│  Final: Opus synthesis with confidence  │
│  assessment + "Go Deeper?" loop         │
└─────────────────────────────────────────┘
```

## Design Principles

- **Survey voice** — reports what was found, doesn't editorialize
- **Inline citations** — every claim attributed to its source
- **Source quality awareness** — vendor reports flagged, limitations noted
- **No AI writing patterns** — no hyperbole, no reframes, numbers first
- **Terminal-native** — hard-wrapped at 80 columns

## Requirements

- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) with WebSearch access
- Works best with Sonnet 4 or Opus 4.5

## Variants

### Sonnet (Token-Efficient)

[searchwave-sonnet](https://github.com/rowbradley/searchwave-sonnet) — Same search and fetch architecture, all synthesis uses Sonnet explicitly. Lower token cost.

```
/plugin install searchwave-sonnet@searchwave-marketplace
```

### X10 (Experimental)

[searchwave-x10](https://github.com/rowbradley/searchwave-x10) — 10-search variant of Standard mode. Opus synthesis.

```
/plugin install searchwave-x10@searchwave-marketplace
```

## Bash Hardening for Skill Authors

If your skills run parallel Bash calls (via Claude Code's tool system), these rules prevent cascade failures where one failed call kills all siblings:

### `|| true` on every grep/filter
`grep` returns exit code 1 when zero matches, which cascades to kill sibling tool calls.
```bash
# Bad — exit 1 on no matches kills siblings
ps aux | grep -E 'node|next' | grep -v grep

# Good — neutralizes exit code
ps aux | grep -E 'node|next' | grep -v grep || true
```

### Avoid zsh reserved variable names
zsh treats `status`, `pipestatus`, `MATCH`, `match` as read-only. Assigning to them throws a hard error.
```bash
# Bad — zsh read-only variable
status=$(git status --porcelain)

# Good — prefixed name
gstatus=$(git status --porcelain)
```

### Newlines over `&&` for echo+pipe chains
`&&` makes each segment dependent on the previous. Use newlines so echo failures don't kill pipes.
```bash
# Bad — echo failure kills grep
echo "===SECTION===" && ps aux | grep pattern

# Good — independent statements
echo "===SECTION==="
ps aux | grep pattern || true
```

These patterns are documented in detail in Claude Code's [parallel tool protocol](https://docs.anthropic.com/en/docs/claude-code).

## License

MIT