<div align="center">
  <h1>Poe Code ⚡</h1>

<a href="https://poe.com"><img src="https://img.shields.io/badge/Poe-Sign up-purple?logo=poe&logoColor=white&color=5D5CDE&style=for-the-badge" alt="Discord"></a>
<a href="https://www.npmjs.com/package/poe-code"><img alt="NPM version" src="https://img.shields.io/npm/v/poe-code.svg?&style=for-the-badge&color=09B16B"></a>
<a href="https://discord.gg/joinpoe"><img src="https://img.shields.io/badge/Discord-Join-purple?logo=discord&logoColor=white&color=FF44D3&style=for-the-badge" alt="Discord"></a>

</div>

Power your favorite coding agents (Claude Code, Codex, OpenCode, and more) with your Poe subscription—**no need to handle multiple providers/accounts.** Poe Code routes everything through the [Poe API](https://poe.com/api) .

Use it on a single session (`npx poe-code@latest wrap claude`) or configure it as your default and use your tools normally.

## Quickstart

Start a coding session routing all your `claude` calls to Poe

```bash
npx poe-code@latest wrap claude
# Also available: codex, opencode, kimi, goose
```

or

## Set it as your default (works with CLIs and desktop apps)

This updates the provider’s config files and continue using your tools normally.

```bash
# Start the interactive setup
npx poe-code@latest configure

# Setup a specific agent
npx poe-code@latest configure codex # (or claude, opencode, kimi, goose)
```

### Unconfigure (remove overrides)

```bash
npx poe-code@latest unconfigure claude
```

## Authentication

Poe Code uses your [Poe API key](https://poe.com/api) for authentication. On first run, you'll be prompted to log in via your browser (OAuth). You can also provide your key directly:

```bash
# Interactive login (opens browser)
npx poe-code@latest login

# Or pass your API key directly
npx poe-code@latest login --api-key <your-key>

# Or set it as an environment variable
export POE_API_KEY=<your-key>
```

Credentials are stored locally in `~/.poe-code/`. Use `poe-code auth status` to check your login state.

```bash
# Remove all configuration and credentials
npx poe-code@latest logout
```

## Quick links

- [Utilities](#utilities)
- [Usage and Billing](#usage--billing)
- [Models](#models)
- [MCP Server](#poe-mcp-server)
- [SDK](#sdk)
- [Research Preview](#research-preview)
- [Poe API](https://poe.com/api)

## Utilities

Utilities are especially useful for scripting and CI/CD.

#### Spawn a one-off prompt

```bash
npx poe-code@latest spawn codex "Say hello"
```

#### Spawn against a GitHub repository

```bash
npx poe-code@latest spawn codex "Fix the failing tests" --cwd github://owner/repo
npx poe-code@latest spawn codex "Review the auth module" --cwd github://owner/repo#main:packages/auth
```

#### Spawn a prompt via stdin

```bash
echo "Say hello" | npx poe-code@latest spawn codex
```

#### Review a GitHub pull request

```bash
npx poe-code@latest code-review install
npx poe-code@latest code-review run "https://github.com/owner/repo/pull/123"
npx poe-code@latest code-review commit "https://github.com/owner/repo/pull/123" --dry-run
```

#### Test a configured service

```bash
npx poe-code@latest test codex
```

### Install agent CLIs

```bash
# Claude Code
npx poe-code@latest install claude-code

# Codex
npx poe-code@latest install codex

# OpenCode
npx poe-code@latest install opencode

# Kimi
npx poe-code@latest install kimi

# Goose
npx poe-code@latest install goose
```

### Optional flags

- `--dry-run` – show every mutation without touching disk.
- `--yes` – accept defaults for prompts.

## Development

Running `npm install` in a clone also installs Poe Code skill templates into supported user skill directories such as `~/.claude/skills/` and `~/.codex/skills/`. Set `SKIP_SYNC_SKILLS=1` to opt out:

```bash
SKIP_SYNC_SKILLS=1 npm install
```

## Usage & Billing

Check your compute points balance and review usage history.

```bash
# Show current balance
poe-code usage

# Show usage history (paginated, 20 entries per page)
poe-code usage list

# Auto-load multiple pages
poe-code usage list --pages 5

# Filter by model name
poe-code usage list --filter claude
```

## Models

List available Poe API models and filter them by provider, capabilities, modalities, and supported API endpoint.

```bash
# List all models
poe-code models

# Show only models that support the Responses API
poe-code models --endpoint /v1/responses

# Show only models that support Chat Completions
poe-code models --endpoint /v1/chat/completions

# Search by provider or model id
poe-code models --search claude
```

## Poe MCP Server

Give any agent access to all Poe models including latest image, video, and audio models.

```bash
# Show configuration JSON and available tools
npx poe-code@latest mcp --help

# Configure an MCP client to use poe-code
npx poe-code@latest mcp configure claude-code

# Remove poe-code from an MCP client
npx poe-code@latest mcp unconfigure claude-code
```

### Available tools

- `generate_text` – Query any bot on Poe.
- `generate_image` – Generate images
- `generate_video` – Generate videos
- `generate_audio` – Convert text to audio

## SDK

Use `poe-code` programmatically in your own code:

```typescript
import { spawn, getPoeApiKey, getPoeAuthIdentity } from "poe-code";

// Get stored API key
const apiKey = await getPoeApiKey();

// Fetch the authenticated Poe account identity
const identity = await getPoeAuthIdentity();

// Run a prompt through a provider
const result = await spawn("claude-code", {
  prompt: "Fix the bug in auth.ts",
  cwd: "/path/to/project",
  model: "claude-sonnet-4-6"
});

// Spawn against a GitHub repository
const { events, result: ghResult } = spawn("codex", {
  prompt: "Review the auth module",
  cwd: "github://owner/repo#main:packages/auth"
});

console.log(result.stdout);
```

For plugin-first agent composition, import the public agent builder from the
`poe-code/agent` subpath:

```typescript
import { agent, openaiResponsesPlugin, systemPromptPlugin } from "poe-code/agent";

const run = await agent()
  .model("gpt-5.5")
  .use(openaiResponsesPlugin())
  .use(systemPromptPlugin())
  .run("Summarize the current repository", {
    cwd: process.cwd()
  });

console.log(run.output);
```

### `spawn(service, options)`

Runs a single prompt through a configured service CLI.

- `service` – Service identifier (`claude-code`, `codex`, `opencode`, `kimi`, `goose`)
- `options.prompt` – The prompt to send
- `options.cwd` – Working directory or workspace locator (optional). Supports local paths and `github://owner/repo[#ref[:subdir]]` locators. See [@poe-code/workspace-resolver](packages/workspace-resolver/) for the full locator syntax.
- `options.model` – Model identifier override (optional)
- `options.mode` – Permission mode: `yolo`, `edit`, or `read` (optional)
- `options.args` – Additional arguments forwarded to the CLI (optional)

Returns `{ stdout, stderr, exitCode }`.

### `spawn.pretty(service, options)`

Same as `spawn()`, but renders the ACP event stream to stdout with colored, formatted output — matching the CLI's visual style.

```typescript
import { spawn } from "poe-code"

const result = await spawn.pretty("codex", "Fix the bug in auth.ts")
console.log(result.exitCode)
```

Returns `Promise<{ stdout, stderr, exitCode }>`.

### `getPoeApiKey()`

Reads the Poe API key with the following priority:

1. `POE_API_KEY` environment variable
2. Credentials file (`~/.poe-code/credentials.enc`)

Throws if no credentials found.

### `getPoeAuthIdentity()`

Fetches the Poe account identity for the resolved API key.

```typescript
import { getPoeAuthIdentity } from "poe-code";

const identity = await getPoeAuthIdentity();
console.log(identity.name, identity.handle);
```

Uses `POE_API_KEY` or the stored credential and honors `POE_BASE_URL`. Throws an API error when Poe rejects the credential.

## Research Preview

These features are available but subject to breaking changes.

- **[Pipeline](packages/pipeline/)** — Run YAML task plans through agents with configurable steps
- **[Ralph](packages/ralph/)** — Agentic build loop that iterates on a markdown doc
- **[Experiment loop](packages/experiment-loop/)** — Karpathy-style optimize loop: agent changes code, eval script scores it, keep or discard via git, repeat.
- **[Poe Agent](packages/poe-agent/)** — Composable agent runtime
