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 .

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

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.

# 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)

npx poe-code@latest unconfigure claude

Authentication

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

# 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.

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

Quick links

• Utilities
• Usage and Billing
• Models
• MCP Server
• SDK
• Research Preview
• Poe API

Utilities

Utilities are especially useful for scripting and CI/CD.

Spawn a one-off prompt

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

Spawn against a GitHub repository

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

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

Test a configured service

npx poe-code@latest test codex

Install agent CLIs

# 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:

SKIP_SYNC_SKILLS=1 npm install

Usage & Billing

Check your compute points balance and review usage history.

# 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.

# 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.

# 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:

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

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

// 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);

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 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.

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.json)

Throws if no credentials found.

Research Preview

These features are available but subject to breaking changes.

• Pipeline — Run YAML task plans through agents with configurable steps
• Ralph — Agentic build loop that iterates on a markdown doc
• Experiment loop — Karpathy-style optimize loop: agent changes code, eval script scores it, keep or discard via git, repeat.
• Poe Agent — Composable agent runtime