# Your agents have expensive taste.

Connect your agents to Phantom AI. Route models, control spending and pay from your terminal.

**pai** by [Phantom AI](https://phantom.codes) · [Docs](https://connortessaro.github.io/pai/) · [npm](https://www.npmjs.com/package/@connortessaro/pai)

Use Phantom AI's router to send requests to cheaper models when your rules allow
it, or choose a model yourself. Connect the coding agents you already use, fund
their inference and pay per request—all from your terminal.

## Install the agent skill

Teach your agent how to use pai:

```bash
npx skills add connortessaro/pai --skill phantom-ai
```

Choose your agent when prompted. The skill covers workspace setup, funding,
spending controls and model routing. Install the pai CLI separately using the
quickstart below. [Skill docs](docs/guides/agent-skill.md) · [Vercel Skills](https://skills.sh/connortessaro/pai/phantom-ai)

## Let your agent set it up

Copy this into Claude Code, Codex, Cursor or another agent with terminal access:

```text
Help me set up pai for AI inference through Phantom AI.

Read https://raw.githubusercontent.com/connortessaro/pai/main/skills/phantom-ai/SKILL.md first.
Check that I have Node 24 or newer, then install @connortessaro/pai if needed.
Check for an existing workspace and saved keys before changing anything.
If I need to connect, start pai login and let me complete the device approval.
Check the workspace balance. Ask which coding agent I use and what budget I want,
then create a named workspace key with that cap, or help me choose MPP payments.
Ask whether I want to connect my existing agent for future runs or use a temporary
connection for one run. For saved setup, preview the changes with pai setup --dry-run
and show them to me before applying the setup I approve. Make sure any spending cap
is on the key my agent will actually use. Ask before adding funds or starting paid
inference. Keep keys and recovery credentials out of chat. Finish with the command
to launch my agent, and explain how to undo any saved setup.
```

For agents that can fetch instructions directly:

```bash
curl -fsSL https://raw.githubusercontent.com/connortessaro/pai/main/skills/phantom-ai/SKILL.md
```

This reads the same instructions pai installs as its agent skill. It does not
install software or make a payment.

## Connect your existing agents

Keep using your coding agent, with Phantom AI handling its inference and model
routing. Connect it using your saved key:

```bash
npm i -g @connortessaro/pai
pai login
pai setup
```

Pai detects supported agents, previews the configuration changes, then asks before
applying them. It connects their model calls to Phantom AI and wires up the saved
key. Restart your agent, or open a new terminal, to use the connection.

Codex, Claude Code, opencode, Continue, Goose, Aider, GitHub Copilot CLI and Cline
support saved setup. Cursor gets instructions for its settings screen; pi gets
the agent skill. [Agent-specific setup](docs/guides/agent-setup.md).

Preview without changing files with `pai setup --dry-run`. Pai keeps backups;
undo the changes with `pai setup --restore`.

## Connect for one run

```bash
npm i -g @connortessaro/pai
pai login
pai workspace fund --amount 10 --card
pai workspace status
pai codex
```

Both setup options require **Node 24+** and your coding agent installed. Connect, fund your
workspace, then launch **Codex** (`pai codex`), **Claude Code** (`pai claude`),
**pi** (`pai pi`), or **any other compatible agent**.
[Set up other agents](docs/guides/agent-setup.md).

Login opens a device approval page and saves a key privately. Funding opens
checkout; check your workspace balance after payment. Agent runs use temporary
configuration and print spending afterward. Your existing agent configuration
stays in place.

Already have a Phantom key? Use `pai login --paste` to save it locally.

## Pay for inference

### Pay from your wallet

Use MPP to pay for inference from a Tempo wallet as your agent runs:

```bash
pai codex --mpp --limit 10
```

Pai asks for wallet approval when needed. `--limit 10` sets the maximum session
deposit; it does not cap the cost of the whole run. For a fixed spending cap,
use a workspace key below. [How wallet limits work](docs/guides/running-agents.md#mpp-agent-sessions-on-tempo).

### Fund a workspace

Add credit first, then let your agents spend from the shared balance.
With a configured [pay.sh](https://pay.sh) wallet, add $10 of Solana USDC using x402:

```bash
pai workspace fund --amount 10 --pay --x402
pai workspace payment --id <payment-id>
```

Credit is available after the payment is verified. If a payment is pending,
check the payment ID pai printed before sending another payment.
x402 funding must be enabled on the Phantom server.

You can also fund a workspace by card or Solana crypto. Workspace funding is
separate from paying directly through Tempo MPP sessions.
[Funding and payment details](docs/guides/running-agents.md#workspace-funding-through-paysh).

## Give each agent a budget

Create a key with its own cap, sharing your workspace balance:

```bash
pai keys create --save coding --limit 5
pai claude --key coding
pai keys list
pai keys set --id <key-id> --limit 10
```

Workspace key controls include total limits, periodic budgets and spending
rates. Use the full key ID from `pai keys list` when changing or revoking a key.
Revoking a workspace key preserves workspace funds.

## Choose what answers

Let the router choose a model for `auto` requests. Your policy can prefer cheaper
models and change the choice for tool use, reasoning or spending limits:

```bash
PHANTOM_KEY_NAME=coding pai route set --models <model-a>,<model-b>
PHANTOM_KEY_NAME=coding pai route test --table
```

Prefer a specific model? Select it in your agent. Policies that apply only to
`auto` leave explicit model choices alone.
[Routing](docs/guides/routing.md) covers conditions, fallback and conversation affinity.

## Commands

| Task | Commands |
| --- | --- |
| Connect | `pai login`, `pai logout` |
| Connect existing agents | `pai setup`, `pai setup --dry-run`, `pai setup --restore` |
| Run inference | `pai claude`, `pai codex`, `pai pi` |
| Fund and check spending | `pai workspace fund`, `pai workspace status`, `pai balance` |
| Manage workspace keys | `pai keys create`, `pai keys set`, `pai keys rotate`, `pai keys revoke` |
| Manage local copies | `pai keys saved`, `pai keys save`, `pai keys rm` |
| Route models | `pai route` |

Put pai flags before agent arguments; use `--` to separate them:

```bash
pai codex --key coding -- exec "explain this repository"
```

Commands print JSON; `--table` renders supported results for people. Agent
commands inherit the terminal and print a spending summary on stderr.
Exit codes: 0 success, 1 error, 2 rejected key; agent runs return the agent's exit code.

<details>
<summary><strong>Advanced tools, integrations and legacy commands</strong></summary>

`pai --help` shows the main workflows. `pai --help --all` and the
[interface reference](docs/reference.md) cover every command.

- [Signed receipts](docs/guides/receipts.md): check which model answered with `pai verify`.
- [MCP tools](docs/reference.md#mcp-tools): `pai mcp` for clients that need a stdio server.
- [Direct-key purchases](docs/guides/buying-credit.md): existing `pai buy` and `pai payment` workflows remain supported.
- [Saved secrets](docs/guides/saved-secrets.md): macOS Keychain or private files; guest recovery uses `pai workspace export` and `pai workspace import`.
- [Key selection](docs/guides/which-key.md) and [API address](docs/guides/base-url.md): environment overrides and shell integration.

The historical `pai key` commands and `phantom-key` executable still work.
`pai keys list` reads the workspace; `pai keys saved` lists local copies.
`pai keys show` prints a secret for shell integration; keep it out of chat and logs.

</details>

<details>
<summary><strong>Development and contributing</strong></summary>

```bash
npm ci
npm run typecheck
npm run build
npm run coverage
npm run docs
node scripts/gen-docs.mjs --check
```

See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).

</details>

---

The CLI is [MIT licensed](LICENSE); Phantom AI is the hosted API it calls.