# Parallel Search

> AI-powered web search via Parallel API. Returns ranked results with LLM-optimized excerpts. Use for up-to-date research, fact-checking, and domain-scoped searching. Use when this capability is needed.

- Skill: `tomevault-io/parallel-search` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/parallel-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/parallel-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/parallel-search

---


# Parallel Search

High-accuracy web search built for AI agents. Returns ranked results with intelligent excerpts optimized for LLM consumption.

## Preflight (Required)

Before running this skill:

1. Prefer native OpenClaw tools first:
   - `web_search` (if configured)
   - `browser` (for interactive browsing)
   - `web_fetch` (for direct URL retrieval)
2. Use `parallel-cli` only when:
   - the user explicitly asks for Parallel search, or
   - native tools are unavailable **and** `parallel-cli` exists on PATH.
3. If `parallel-cli` is missing, do not block the user on installation by default.
   Continue with native OpenClaw tools or local docs.

## When to Use

Trigger this skill when the user asks for:

- "search the web", "web search", "look up", "find online"
- "current news about...", "latest updates on..."
- "research [topic]", "what's happening with..."
- Fact-checking with citations needed
- Domain-specific searches (e.g., "search GitHub for...", "find on Reddit...")

## Quick Start

```bash
command -v parallel-cli >/dev/null && parallel-cli search "your query" --json --max-results 5
```

## CLI Reference

### Basic Usage

```bash
parallel-cli search "<objective>" [options]
```

### Common Flags

| Flag                           | Description                                      |
| ------------------------------ | ------------------------------------------------ |
| `-q, --query "<keyword>"`      | Add keyword filter (repeatable, 3-8 recommended) |
| `--max-results N`              | Number of results (1-20, default: 10)            |
| `--json`                       | Output as JSON                                   |
| `--after-date YYYY-MM-DD`      | Filter for recent content                        |
| `--include-domains domain.com` | Limit to specific domains (repeatable, max 10)   |
| `--exclude-domains domain.com` | Exclude domains (repeatable, max 10)             |
| `--excerpt-max-chars-total N`  | Limit total excerpt size (default: 8000)         |

### Examples

**Basic search:**

```bash
parallel-cli search "When was the United Nations founded?" --json --max-results 5
```

**With keyword filters:**

```bash
parallel-cli search "Latest developments in quantum computing" \
  -q "quantum" -q "computing" -q "2026" \
  --json --max-results 10
```

**Domain-scoped search:**

```bash
parallel-cli search "React hooks best practices" \
  --include-domains react.dev --include-domains github.com \
  --json --max-results 5
```

**Recent news only:**

```bash
parallel-cli search "AI regulation news" \
  --after-date 2026-01-01 \
  --json --max-results 10
```

## Best-Practice Prompting

### Objective

Write 1-3 sentences describing:

- The real task context (why you need the info)
- Freshness constraints ("prefer 2026+", "latest docs")
- Preferred sources ("official docs", "news sites")

### Keyword Queries

Add 3-8 keyword queries including:

- Specific terms, version numbers, error strings
- Common synonyms
- Date terms if relevant ("2026", "Jan 2026")

## Response Format

Returns structured JSON with:

- `search_id` — unique identifier
- `results[]` — array of results:
  - `url` — source URL
  - `title` — page title
  - `excerpts[]` — relevant text excerpts
  - `publish_date` — when available

## Output Handling

When turning results into a user-facing answer:

- Prefer **official/primary sources** when possible
- Quote or paraphrase **only** the relevant extracted text
- Include **URL + publish_date** for transparency
- If results disagree, present both and note the discrepancy

## Running Out of Context?

For long conversations, save results and use `sessions_spawn`:

```bash
parallel-cli search "<query>" --json -o /tmp/search-<topic>.json
```

Then spawn a sub-agent:

```json
{
  "tool": "sessions_spawn",
  "task": "Read /tmp/search-<topic>.json and synthesize a summary with sources.",
  "label": "search-summary"
}
```

## Error Handling

| Exit Code | Meaning                           |
| --------- | --------------------------------- |
| 0         | Success                           |
| 1         | Unexpected error (network, parse) |
| 2         | Invalid arguments                 |
| 3         | API error (non-2xx)               |

## Prerequisites

1. Get an API key at [parallel.ai](https://parallel.ai)
2. Install the CLI:

```bash
curl -fsSL https://parallel.ai/install.sh | bash
export PARALLEL_API_KEY=your-key
```

## References

- [API Docs](https://docs.parallel.ai)
- [Search API Reference](https://docs.parallel.ai/api-reference/search)

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/gagan114662) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->