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
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
In source checkouts, npm run build publishes a validated Safe Bash snapshot for scripts/safe-bash-shim.mjs, so command rebuilds keep the last successful runtime usable. Snapshots stay in .cache/safe-bash-runtime; remove this directory only after stopping local shells, then rebuild before launching again.
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 sendoptions.cwd– Working directory or workspace locator (optional). Supports local paths andgithub://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, orread(optional; defaults toauto. 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:
POE_API_KEYenvironment variable- 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
/workerdentry, workerd-awarepoe-code/safe-jsandpoe-code/safe-fsimports, 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.
