web-scout

Live Web Search (Perplexity Sonar API)

You are the Lead Engineer. You have access to the Perplexity API to search the live internet for information beyond your training data.

CRITICAL BUDGET RULES

Unlike Gemini CLI (free, flat-rate) and Codex CLI (free, flat-rate), this API costs hard currency per token. The user has $5/month in API credit. A single careless query can burn $0.50+.

You MUST obey these rules:

1. NEVER use this for general knowledge. If Claude already knows the answer (even approximately), do NOT verify it with Perplexity. Trust your training data.
2. NEVER pass code blocks, file contents, or large context into the query. Queries must be short — under 100 words.
3. NEVER retry on failure. If the API returns an error (401, 429, 500, timeout), stop. Make your best guess from training data. Log the failure and move on.
4. NEVER use in a loop. One query per knowledge gap. No "let me try a different phrasing" — that's two queries.
5. NEVER use for research that WebSearch can handle. The built-in WebSearch tool is free. Only use Perplexity when you need search-grounded synthesis (not just links).

Valid use cases (sniper shots):

• "What breaking changes did Next.js 15.2 introduce for App Router caching?" — specific, time-sensitive
• "Stripe API 2026-03 changelog: what changed in checkout sessions?" — can't find in training data
• "Supabase pg_net extension: how to make async HTTP calls from triggers?" — niche technical docs
• "Error: NEXT_REDIRECT_ERROR in server component after Next.js upgrade" — specific error code

Invalid use cases (machine gun — DO NOT USE):

• "How does React work?" — Claude knows this
• "Best practices for TypeScript" — Claude knows this
• "Explain this code: [500 lines of code]" — too expensive, Claude can analyze code natively
• "What is Supabase?" — Claude knows this
• General market research — use WebSearch instead

Multi-LLM Mode Check

1. Read .claude/llm-mode.json — if mode is "multi", Perplexity is available
2. If mode is "single" or file doesn't exist, use WebSearch or your training data instead
3. Even in multi mode, apply all budget rules above

IMMEDIATE ACTION

Step 1: Qualify the Query

Before making ANY API call, answer these three questions:

1. Do I already know this? If yes → stop, use training data
2. Can WebSearch answer this? If yes → use WebSearch (free)
3. Is this specific and time-sensitive enough to justify $0.10-0.50? If no → stop

Only proceed if all three answers point to Perplexity.

Step 2: Formulate the Query

Write the shortest possible query that will get you the answer. Aim for 10-30 words.

Good: "Next.js 15 App Router caching breaking changes 2026" Bad: "I am building a Next.js application and I noticed that after upgrading to version 15 the caching behavior seems different from what I expected based on the documentation for version 14, can you help me understand what changed and how to migrate my existing cache configuration?"

Step 3: Execute the API Call

START_TIME=$(date +%s)
PPLX_RESPONSE=$(curl -s --max-time 15 \
  --request POST \
  --url https://api.perplexity.ai/chat/completions \
  --header "Authorization: Bearer $PERPLEXITY_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{
    \"model\": \"sonar-pro\",
    \"messages\": [
      {
        \"role\": \"system\",
        \"content\": \"You are a senior developer. Search the web and return a concise, factual answer with code snippets if relevant. Cite your sources. No conversational filler.\"
      },
      {
        \"role\": \"user\",
        \"content\": \"[YOUR_SHORT_QUERY]\"
      }
    ],
    \"max_tokens\": 1000,
    \"temperature\": 0.1
  }" 2>/dev/null)
PPLX_EXIT=$?
DURATION=$(($(date +%s) - START_TIME))

echo "$PPLX_RESPONSE"

Hardcoded safety limits:

• max_tokens: 1000 — caps response cost regardless of how much Perplexity finds
• temperature: 0.1 — factual, not creative
• --max-time 15 — timeout after 15 seconds (prevents hanging)
• sonar-pro — search-grounded model with citations

Step 4: Parse and Validate

Check the response:

# Check for API errors
echo "$PPLX_RESPONSE" | python3 -c "
import sys, json
try:
    d = json.load(sys.stdin)
    if 'error' in d:
        print(f'API_ERROR: {d[\"error\"].get(\"message\", \"unknown\")}')
    elif 'choices' in d:
        msg = d['choices'][0]['message']['content']
        print(msg)
        # Print citations if available
        citations = d.get('citations', [])
        if citations:
            print('\n--- Sources ---')
            for i, c in enumerate(citations, 1):
                print(f'{i}. {c}')
    else:
        print('UNEXPECTED_FORMAT')
except:
    print('PARSE_ERROR')
" 2>/dev/null

On any error (API_ERROR, PARSE_ERROR, timeout, non-zero exit code):

• Do NOT retry. Log the failure and fall back to training data or WebSearch.

Step 5: Log the Query

Always log, even on failure. This tracks API credit consumption.

Append to .claude/delegation.log:

YYYY-MM-DDTHH:MM:SSZ | web-scout | ok | Ns | Query: [short query summary]

Then update stats:

python3 -c "
import json, datetime
f='.claude/llm-mode.json'
try:
  with open(f) as fh: d=json.load(fh)
  d['stats']['delegations_total'] = d['stats'].get('delegations_total',0) + 1
  d['stats']['last_delegation'] = datetime.datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%SZ')
  with open(f,'w') as fh: json.dump(d, fh, indent=2)
except: pass
"

Or on failure:

YYYY-MM-DDTHH:MM:SSZ | web-scout | fail | Ns | [error type]: [short description]

Then update stats:

python3 -c "
import json, datetime
f='.claude/llm-mode.json'
try:
  with open(f) as fh: d=json.load(fh)
  d['stats']['delegations_failed'] = d['stats'].get('delegations_failed',0) + 1
  d['stats']['last_delegation'] = datetime.datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%SZ')
  with open(f,'w') as fh: json.dump(d, fh, indent=2)
except: pass
"

Step 6: Apply the Knowledge

Read the response and apply it to the current task. Do NOT include raw Perplexity output in user-facing deliverables — synthesize it into your own analysis.

Cost Estimation

Query Type	Estimated Cost
Short factual query (10-20 words)	$0.05-0.10
Technical query with code response	$0.10-0.25
Complex multi-source synthesis	$0.25-0.50
Monthly budget	$5.00
Safe queries per month	~20-50
Queries per session (guideline)	0-2

Integration Points

• With /plan Phase 1.5: When external research is needed for high-risk topics (security, payments, new framework features), /web-scout provides current info
• With /brief: When briefing surface competitive intel or market data that's more recent than training data
• With /codex-write: Before delegating to Codex, if the task uses a library/API that may have changed since training data

Troubleshooting

401 Unauthorized:

• API key is expired or invalid. User needs to regenerate at https://www.perplexity.ai/settings/api
• Do NOT retry. Fall back to WebSearch.

429 Rate Limited:

• Monthly credit exhausted. Do NOT retry until next billing cycle.
• Fall back to WebSearch for the rest of the month.

Empty or irrelevant response:

• Query was too vague. Do NOT retry with a "better" query — that's two queries.
• Use your training data or WebSearch instead.

$5 credit running low:

• Reduce to 0-1 queries per session
• Prefer WebSearch for everything except truly critical, time-sensitive lookups