Poe Auth

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 .

Configure an agent once and use its normal CLI or desktop app, or spawn one-off prompts through Poe.

Quickstart

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, 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
• 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" --mode read

--mode is the permission mode: yolo | auto | edit | read.

Spawn against a GitHub repository

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

Spawn a prompt via stdin

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

Stdin is piped here, so there is no TTY to prompt on — --mode is required.

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

# Goose
npx poe-code@latest install goose

Optional flags

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

Usage & Billing

Check your compute points balance and review usage history.

# Show current balance
poe-code usage

# Show usage history (20 entries, then prompts to load more)
poe-code usage list

# Show a specific number of entries without prompting
poe-code usage list --limit 100

# 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

SDK

Safe Bash supports noncapturing SDK execution with captureOutput: false and streams CLI output without retaining a full result. Sips PDF conversion and detailed image inspection keep input and rendered pixels in caller-backed storage. Pandoc RTF conversions use caller-backed parsing and Lua filters, including streamed HTML image embedding. ZIP reads and TAR mutations use caller-backed staging and range reads; large archives require suitable external filesystem storage. It also provides Graphviz rendering through poe-code/safe-bash/graphviz, local audio/video inspection and WAV editing through poe-code/safe-bash/commands/audio, recursive file search with rgrep, and structural code search and rewrites with ast-grep / sg.

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

Agent spawn activity timeouts and parallel concurrency limits are optional; set activityTimeoutMs or maxConcurrent explicitly when needed. Autonomous spawn retries have no ceiling unless maxTimeoutRetries is supplied.

For plugin-first agent composition, import the public agent builder from the poe-code/agent subpath. In Cloudflare Workers, pass agent({ fs, cwd, homeDir }) with a SafeFS provider and configure an explicit API key or model. The agent and poe-code/memory exports support Workers without nodejs_compat; host subprocesses require an injected runner where supported:

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, 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, auto, edit, or read (optional; defaults to auto. Agents without an auto mode fail clearly)
• 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.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.

• SafeJS — A JavaScript interpreter with explicit host capabilities, portable browser/Worker root exports, a /workerd entry, workerd-aware poe-code/safe-js and poe-code/safe-fs imports, filesystem adapters, explicit Worker host-context capture, configurable unlimited resource budgets, and resumable checkpoints.
• Pipeline — Run task plans with configurable steps, live task progress, queued follow-up messages, and plans you can add while the TUI is running.
• 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 with shared safe-fs access

Update Poe Code

npx poe-code@latest update
npx poe-code@latest update --package-manager pnpm

For version checks, dry runs, and managed worktrees, see the reference.