---
slug: "pi-gemini-search"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/nilskluewer/pi-gemini-search@main/README.md"
repo: "https://github.com/nilskluewer/pi-gemini-search"
source_file: "README.md"
branch: "main"
---
# pi-gemini-search

[![npm version](https://img.shields.io/npm/v/pi-gemini-search?style=for-the-badge)](https://www.npmjs.com/package/pi-gemini-search)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)

Web search & research tools for the [Pi coding agent](https://github.com/earendil-works/pi),
backed by the Gemini API with Google Search grounding. The agent can call
them autonomously to pull fresh information from the web — without dumping raw
page contents into your conversation.

The key idea: search context stays **inside the tool result**. Gemini does the
searching and reading, then returns only a synthesized answer plus source
URLs, so your main context stays lean. No headless browser, no page-scraping
noise.

## Tools

Registers two tools the model can call:

- **`web_search`** — quick fact-check / verification. Returns a concise
  synthesized answer (a few sentences) + source URLs. Use for version numbers,
  dates, single facts, a quick second opinion. Uses `url_context` too, so you
  can hand it URLs to cross-check.
- **`web_research`** — in-depth research on a complex topic. Returns a
  thorough, structured answer + source URLs. Use for multi-faceted topics,
  how-tos, architecture opinions, grounded second opinions.

Both tools:

- Ground answers with Google Search (never answer from memory alone).
- Can read specific URLs you pass via the Gemini `url_context` tool — include
  background, constraints, prior conclusions, docs URLs in the query; more
  context = better answer.
- Resolve Gemini's `vertexaisearch.cloud.google.com` redirect links to their
  pure destination URLs (via the 302 `location` header) so only clean links
  enter your context.

## API key

The extension needs a Gemini API key. Resolution order:

1. `GEMINI_API_KEY` environment variable
2. `~/.pi/agent/auth.json` with a `gemini` entry:
   ```json
   { "gemini": { "key": "..." } }
   ```

Get a key from [Google AI Studio](https://aistudio.google.com/apikey).

## Install

```bash
pi install npm:pi-gemini-search
```

Or from GitHub:

```bash
pi install git:github.com/nilskluewer/pi-gemini-search
# or pin a version:
pi install git:github.com/nilskluewer/pi-gemini-search@v0.1.0
```

Try without installing:

```bash
pi -e git:github.com/nilskluewer/pi-gemini-search
```

## How it differs from just using `curl`

You already have `bash` + `curl`. This package is for when you don't have a
specific URL, or want a *synthesized* answer rather than a verbatim page dump:

- **Quick fact / no URL / broad research** → `web_search` / `web_research`
  (synthesized, lean, lossy).
- **Specific doc page you need verbatim** → fetch the `.md` with `curl`
  (full fidelity). Many Mintlify-hosted docs serve clean Markdown when you
  append `.md` to the URL.

## License

MIT