Skip to content

README.md

Latest commit

 

History

History
312 lines (212 loc) · 8.86 KB

README.md

File metadata and controls

312 lines (212 loc) · 8.86 KB
Raw

Poe Code ⚡

Discord NPM version Discord

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

Utilities are especially useful for scripting and CI/CD.

Spawn a one-off prompt

npx poe-code@latest spawn codex "Say hello"
npx poe-code@latest spawn cursor "Say hello from Cursor"

Cursor spawns use the authenticated cursor-agent installation and your Cursor account; Poe Code does not inject Poe credentials into Cursor.

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

Review a GitHub pull request

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

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

# Cursor
npx poe-code@latest install cursor

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

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, cursor, 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)
  • options.env – Per-invocation child environment overrides (optional)
  • options.mcpServers – Spawn-time MCP servers serialized into the agent-specific flags or environment (optional)
  • options.runtime, options.runtimeImage, options.runtimeTemplate, options.detach, options.mountPoeCode, options.runnerSync – Runtime overrides for agents with CLI spawn support (optional). ACP-only agents reject these options instead of running locally.

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

Throws if no credentials found.

getPoeAuthIdentity()

Fetches the Poe account identity for the resolved API key.

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