> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valyu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code Plugin

> Use Valyu search directly in Claude Code with a zero-dependency plugin for real-time web, academic, and financial search

## Overview

<Note>
  This is a <strong>community-maintained</strong> plugin developed by{" "}
  <a href="https://github.com/GhouI">GhouI</a>. For official integrations, see{" "}
  <a href="/integrations/mcp-server">Remote MCP</a> or use the{" "}
  <a href="/api-reference/endpoint/search">Valyu API</a> directly.
</Note>

The Valyu Search Plugin for Claude Code provides direct access to Valyu's search APIs through a simple CLI interface. It enables Claude Code to perform real-time searches across web content, academic papers, financial data, and more.

**Key features:**

* **Zero dependencies** - Direct API calls using Node.js built-in fetch
* **8 search types** - Web, finance, academic, biomedical, patents, SEC, economics, and news
* **AI-powered answers** - Get answers with source citations
* **Content extraction** - Extract clean content from any URL
* **Deep research** - Async research reports for complex topics

## Installation

Install the plugin from the Claude Code marketplace:

```bash theme={null}
# Add the marketplace
/plugin marketplace add valyuAI/valyu-search-plugin

# Install the plugin
/plugin install valyu-search-plugin@valyu-marketplace
```

## API Key Setup

Get your API key from [platform.valyu.ai](https://platform.valyu.ai) with **\$10 free credits**.

### Automatic Setup (Recommended)

Just start using the plugin! On first use, Claude will:

1. Detect that no API key is configured
2. Ask you to paste your API key
3. Save it automatically to `~/.valyu/config.json`
4. Retry your search

```
You: Valyu(web, "AI news 2025")
Claude: "To use Valyu search, I need your API key. Get one free at https://platform.valyu.ai"
You: val_abc123...
Claude: [saves key and runs search]
```

### Manual Setup (Alternative)

If you prefer to set up manually:

<Tabs>
  <Tab title="Environment Variable">
    For Zsh (macOS default):

    ```bash theme={null}
    echo 'export VALYU_API_KEY="your-api-key-here"' >> ~/.zshrc
    source ~/.zshrc
    ```

    For Bash:

    ```bash theme={null}
    echo 'export VALYU_API_KEY="your-api-key-here"' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Tab>

  <Tab title="Config File">
    ```bash theme={null}
    mkdir -p ~/.valyu
    echo '{"apiKey": "your-api-key-here"}' > ~/.valyu/config.json
    ```
  </Tab>

  <Tab title="VSCode Settings">
    Add to your `settings.json`:

    ```json theme={null}
    {
      "terminal.integrated.env.osx": {
        "VALYU_API_KEY": "your-api-key-here"
      }
    }
    ```
  </Tab>
</Tabs>

**Key Lookup Priority:**

1. `VALYU_API_KEY` environment variable
2. `~/.valyu/config.json` file

## Usage

You can use the plugin with either natural language or the structured syntax:

<Tabs>
  <Tab title="Natural Language">
    Simply ask Claude to search for what you need:

    ```
    Search the web for AI developments in 2025
    Find academic papers on transformer neural networks
    Look up Apple's Q4 2024 earnings
    Search for clinical trials on cancer immunotherapy
    ```

    Claude will automatically use the appropriate Valyu search tool based on your query.
  </Tab>

  <Tab title="Structured Syntax">
    Use the explicit syntax for precise control:

    ```
    Valyu(searchType, "query", maxResults)
    ```

    **Search Types:** `web`, `finance`, `paper`, `bio`, `patent`, `sec`, `economics`, `news`
  </Tab>
</Tabs>

### Search Examples

<CodeGroup>
  ```bash Web Search theme={null}
  Valyu(web, "AI developments 2025", 10)
  ```

  ```bash Biomedical Research theme={null}
  Valyu(bio, "cancer immunotherapy clinical trials")
  ```

  ```bash Financial Data theme={null}
  Valyu(finance, "Apple Q4 2024 earnings", 8)
  ```

  ```bash Academic Papers theme={null}
  Valyu(paper, "transformer neural networks", 15)
  ```

  ```bash Patent Search theme={null}
  Valyu(patent, "renewable energy storage battery")
  ```

  ```bash SEC Filings theme={null}
  Valyu(sec, "Tesla 10-K risk factors")
  ```

  ```bash Economics Data theme={null}
  Valyu(economics, "US unemployment rate trends")
  ```

  ```bash News theme={null}
  Valyu(news, "tech industry layoffs 2025")
  ```
</CodeGroup>

### Answer

Get AI-powered answers with source citations:

```bash theme={null}
Valyu(answer, "What is quantum computing?")
Valyu(answer, "Latest AI news", --fast)
```

### Contents

Extract clean content from URLs:

```bash theme={null}
Valyu(contents, "https://example.com/article")
Valyu(contents, "https://example.com", --summary)
```

### DeepResearch

Create async research reports for complex topics:

```bash theme={null}
# Create a new research task
Valyu(deepresearch, create, "AI market trends 2025")

# Check status of a research task
Valyu(deepresearch, status, "task-id-here")
```

## Search Types

| Type            | Description            | Data Sources                             |
| --------------- | ---------------------- | ---------------------------------------- |
| **`web`**       | General web search     | Real-time web content                    |
| **`finance`**   | Financial data         | Stocks, earnings, SEC filings, crypto    |
| **`paper`**     | Academic papers        | arXiv, PubMed, scholarly journals        |
| **`bio`**       | Biomedical research    | PubMed, clinical trials, FDA drug labels |
| **`patent`**    | Patent databases       | USPTO, global patent data                |
| **`sec`**       | SEC regulatory filings | 10-K, 10-Q, 8-K documents                |
| **`economics`** | Economic indicators    | BLS, FRED, World Bank                    |
| **`news`**      | News articles          | Real-time news sources                   |

## Output Format

All commands return structured JSON results:

```json theme={null}
{
  "success": true,
  "type": "search",
  "searchType": "web",
  "query": "AI news",
  "resultCount": 10,
  "results": [
    {
      "title": "Article Title",
      "url": "https://example.com",
      "content": "Full content...",
      "source": "web",
      "relevance_score": 0.95
    }
  ],
  "cost": 0.025
}
```

## Example Queries

### Web Search

* "Who won the superbowl this year?"
* "Latest developments in quantum computing"
* "Best practices for React server components"

### Academic Research

* "Find recent papers on transformer architecture improvements"
* "CRISPR gene editing therapeutic applications"
* "Climate change mitigation strategies peer-reviewed studies"

### Financial Analysis

* "AAPL stock price and recent performance"
* "Tesla latest quarterly earnings and revenue trends"
* "Bitcoin price trends this week"

### SEC Filings

* "Tesla's latest 10-K MD\&A section"
* "Apple risk factors from FY2023 annual report"
* "Microsoft's business strategy from recent 10-K"

### Biomedical Research

* "Find clinical trials for CAR-T therapy in lymphoma"
* "Latest research on GLP-1 receptor agonists for weight loss"
* "FDA approvals for mRNA-based therapeutics"

### Patent Search

* "Find patents related to solid-state battery technology"
* "Machine learning patents filed by Google in 2024"
* "Prior art search for autonomous vehicle navigation"

### Economics Data

* "US unemployment rate trends over the past year"
* "Federal Reserve interest rate decisions"
* "World Bank GDP growth data for emerging markets"

## Requirements

* **Node.js 18+** (for built-in fetch API)
* **Valyu API key** (get \$10 free credits at [platform.valyu.ai](https://platform.valyu.ai))

## Additional Resources

<CardGroup>
  <Card title="GitHub Repository" icon="github" href="https://github.com/valyuAI/claude-search-plugin">
    View source code and contribute
  </Card>

  <Card title="Get API Key" icon="key" href="https://platform.valyu.ai">
    Sign up for free \$10 credit
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/endpoint/search">
    Complete Valyu API documentation
  </Card>

  <Card title="Remote MCP" icon="server" href="/integrations/mcp-server">
    Use Valyu with MCP protocol
  </Card>
</CardGroup>

## Support

This is a community-maintained plugin. For issues or contributions:

* **GitHub Issues**: [Report issues or request features](https://github.com/valyuAI/claude-search-plugin/issues)
* **Discord**: [Join the Valyu community](https://discord.gg/umtmSsppRY)