enne2/pi-perplexity
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrite README for GitHub

Browse Source
This commit is contained in:
Ivan Pereira
2026-02-23 11:06:24 +00:00
parent 043c83a722
commit 560ff5df75
1 changed files with 71 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+71 -81
View File
@@ -1,6 +1,13 @@
# pi-perplexity # pi-perplexity
A [pi](https://github.com/nickarrow/pi-coding-agent) extension that provides web search via a Perplexity Pro/Max subscription. Uses your existing subscription — no API credits consumed. A [pi](https://github.com/badlogic/pi-mono) extension that gives your coding agent real-time web search powered by your **Perplexity Pro or Max subscription** — no API key, no extra credits, just your existing plan.
## Requirements
- [pi](https://github.com/badlogic/pi-mono) coding agent
- [Bun](https://bun.sh) runtime (available on `PATH`)
- A **Perplexity Pro** or **Max** subscription
- macOS (for zero-interaction auth) _or_ an interactive terminal (for email OTP)
## Installation ## Installation
@@ -8,129 +15,112 @@ A [pi](https://github.com/nickarrow/pi-coding-agent) extension that provides web
pi install pi-perplexity pi install pi-perplexity
``` ```
## Usage Or add to your `~/.pi/agent/settings.json` (global) or `.pi/settings.json` (project):
Once installed, the agent gains a `perplexity_search` tool it can call automatically when it needs to look something up. You can also trigger a search by asking the agent to search for something. ```json
{
### Tool Parameters "packages": ["pi-perplexity"]
}
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | yes | Search query |
| `recency` | string | no | Filter by age: `hour`, `day`, `week`, `month`, `year` |
| `limit` | number | no | Max sources to return (1–50) |
### Slash Command
```
/perplexity-login # Authenticate and save token
/perplexity-login --force # Clear cached token and re-authenticate
``` ```
## Authentication ## Authentication
The extension tries two auth methods in order: Run the login command once to cache your token:
1. **macOS Desktop App** (automatic) — Borrows the JWT from the Perplexity macOS app if installed and signed in. Zero interaction required. ```
/perplexity-login
```
2. **Email OTP** (interactive fallback) — Prompts for your Perplexity email, sends a one-time code, and prompts for the code. The extension tries two methods in order:
The token is cached at `~/.config/pi-perplexity/auth.json` (permissions `0600`). On HTTP 401/403, the cached token is automatically cleared so the next search re-authenticates. 1. **macOS Desktop App** _(zero interaction)_ — borrows the JWT directly from the Perplexity macOS app if it's installed and signed in. Nothing to type.
2. **Email OTP** _(interactive fallback)_ — prompts for your Perplexity email, sends a one-time code, and prompts for the code.
### Environment Variables The token is saved to `~/.config/pi-perplexity/auth.json` (mode `0600`) and reused across sessions. On auth failure, run `/perplexity-login --force` to clear and re-authenticate.
### Environment variables
| Variable | Description | | Variable | Description |
|----------|-------------| |---|---|
| `PI_AUTH_NO_BORROW=1` | Skip macOS desktop app token extraction | | `PI_AUTH_NO_BORROW=1` | Skip macOS desktop app extraction and go straight to email OTP |
| `PI_PERPLEXITY_EMAIL` | Email for OTP auth (skips interactive prompt) | | `PI_PERPLEXITY_EMAIL` | Pre-fill the email prompt (useful for non-interactive setups) |
| `PI_PERPLEXITY_OTP` | OTP code for non-interactive auth | | `PI_PERPLEXITY_OTP` | Pre-fill the OTP prompt |
## How It Works ## Usage
The extension calls Perplexity's internal SSE endpoint (`perplexity_ask`) with your subscription credentials. Responses stream as incremental events that are merged into a final result containing an answer and sources. Once installed, the agent automatically calls `perplexity_search` whenever it needs current information. You can also ask it directly:
All queries use `is_incognito: true` — nothing appears in your Perplexity search history. > "Search Perplexity for the latest React 19 release notes"
### Output Format ### Tool parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | ✅ | The search query |
| `recency` | string | — | Filter by age: `hour` · `day` · `week` · `month` · `year` |
| `limit` | number | — | Max sources to include (1–50) |
### Output format
The tool returns structured text the agent can reason over: The tool returns structured text the agent can reason over:
``` ```
## Answer ## Answer
<synthesized answer with inline citations> React 19 introduces Actions, use() hook, and improved Server Components...
## Sources ## Sources
3 sources 3 sources
[1] Example Article (2d ago) [1] React 19 Release Notes (1d ago)
https://example.com/article https://react.dev/blog/2024/12/05/react-19
Brief snippet of the source content... React 19 is now stable. This release includes Actions for async...
[2] Another Source (5h ago) [2] What's New in React 19 (3d ago)
https://example.com/other https://vercel.com/blog/react-19
Another snippet preview... A deep dive into the new primitives landing in React 19...
## Meta ## Meta
Provider: perplexity (oauth) Provider: perplexity (oauth)
Model: pplx_pro_upgraded Model: pplx_pro_upgraded
``` ```
All queries use `is_incognito: true` — nothing shows up in your Perplexity history.
## How It Works
The extension calls Perplexity's internal SSE endpoint (`perplexity_ask`) using your subscription credentials obtained from the macOS app or via email OTP. Responses stream as incremental events that are merged into a final result.
When pi loads extensions under Node/jiti, direct `fetch` to Perplexity gets Cloudflare-challenged, so the search client shells out to a Bun subprocess — that's the only reason Bun is required.
## Development ## Development
### Prerequisites
- [Bun](https://bun.sh) runtime
- pi coding agent (`@mariozechner/pi-coding-agent`)
### Commands
```bash ```bash
bun install # Install dev dependencies bun install # Install dev dependencies
bun test # Run tests (30 tests across 6 files) bun test # Run tests
bunx tsc --noEmit # Type check bunx tsc --noEmit # Type check
``` ```
### Project Structure ### Project structure
``` ```
src/ src/
index.ts # Extension entry — registers tool and commands index.ts # Extension entry — registers tool and commands
constants.ts # Shared constants (User-Agent, API version)
auth/ auth/
login.ts # macOS app extraction + email OTP flow login.ts # macOS app extraction + email OTP flow
storage.ts # Token persistence (~/.config/pi-perplexity/auth.json) storage.ts # Token persistence (~/.config/pi-perplexity/auth.json)
commands/ commands/
login.ts # /perplexity-login slash command login.ts # /perplexity-login slash command handler
search/ search/
types.ts # Type definitions (StreamEvent, SearchResult, errors) types.ts # Type definitions (StreamEvent, SearchResult, errors)
client.ts # HTTP POST to SSE endpoint, event merging, result extraction client.ts # POST to SSE endpoint, event merging, result extraction
stream.ts # SSE line parser + incremental event merging stream.ts # SSE line parser + incremental event merging
format.ts # SearchResult → LLM-readable text output format.ts # SearchResult → LLM-readable text
render/ render/
call.ts # TUI component for tool call display call.ts # TUI component for tool call display
result.ts # TUI component for tool result display result.ts # TUI component for tool result display
util.ts # Shared render utilities util.ts # Shared render utilities
``` ```
### Runtime Dependencies
This extension depends on the `bun` runtime package at execution time.
Why: when pi loads extensions under Node/jiti, direct `fetch` to Perplexity is Cloudflare-challenged, so searches are executed through a Bun subprocess.
Everything else uses platform globals:
- `fetch` — HTTP requests
- `crypto.randomUUID()` — request IDs
- `ReadableStream` — SSE parsing
- `Intl.DateTimeFormat` — timezone detection
Peer dependencies (`@sinclair/typebox`, `@mariozechner/pi-tui`, `@mariozechner/pi-ai`) are provided by pi at runtime.
## Requirements
- Perplexity **Pro** or **Max** subscription
- Bun installed and available on `PATH` (used by the search client when running under Node/jiti)
- macOS (for desktop app token extraction) or interactive terminal (for email OTP)
## License ## License
Private — not published. MIT — see [LICENSE](LICENSE) for details.