poe-code

Poe Code is a tool that routes your favorite coding agents (Claude Code, Codex, OpenCode, Goose, etc.) through the Poe API, so you only need one Poe subscription instead of managing multiple providers or accounts. It works with the agents' normal CLIs or desktop apps after a one-time configuration, and also supports spawning one-off prompts for scripting and CI/CD. ## Quickstart Set Poe Code as the default provider for an agent (updates config files): ```bash npx poe-code@latest configure npx poe-code@latest configure codex # or claude, opencode, goose ``` Remove overrides with `unconfigure`: ```bash npx poe-code@latest unconfigure claude ``` ## Authentication Uses your Poe API key. On first run, you'll be prompted to log in via browser (OAuth). You can also provide the key directly: ```bash npx poe-code@latest login npx poe-code@latest login --api-key <your-key> export POE_API_KEY=<your-key> ``` Credentials are stored in `~/.poe-code/`. Check status with `poe-code auth status`, remove with `logout`. ## Utilities - **Spawn a one-off prompt**: `npx poe-code@latest spawn codex "Say hello" --mode read` (modes: yolo, auto, edit, read; required in CI without TTY). - **Spawn against a GitHub repo**: `--cwd github://owner/repo` or with ref/subdir like `github://owner/repo#main:packages/auth`. - **Pipe prompt via stdin**: `echo "Say hello" | npx poe-code@latest spawn codex --mode read`. - **Review a GitHub PR**: `code-review install`, `code-review run <url>`, `code-review commit <url> --dry-run`. - **Test a configured service**: `npx poe-code@latest test codex`. - **Install agent CLIs**: `install claude-code`, `install codex`, `install opencode`, `install goose`. - **Optional flags**: `--dry-run` (show mutations without touching disk), `--yes` (accept defaults). ## Usage & Billing Check compute points balance and usage history: ```bash poe-code usage poe-code usage list poe-code usage list --limit 100 poe-code usage list --filter claude ``` ## Models List available Poe API models, filter by endpoint, provider, or search: ```bash poe-code models poe-code models --endpoint /v1/responses poe-code models --endpoint /v1/chat/completions poe-code models --search claude ``` ## SDK Use Poe Code programmatically in your own code: ```typescript import { spawn, getPoeApiKey, getPoeAuthIdentity } from "poe-code"; const apiKey = await getPoeApiKey(); const identity = await getPoeAuthIdentity(); const result = await spawn("claude-code", { prompt: "Fix the bug in auth.ts", cwd: "/path/to/project", model: "claude-sonnet-4-6" }); console.log(result.stdout); ``` - `spawn(service, options)` – runs a single prompt; options include `prompt`, `cwd` (local path or `github://` locator), `model`, `mode`, `args`. Returns `{ stdout, stderr, exitCode }`. - `spawn.pretty(service, options)` – same but renders colored ACP event stream. - `getPoeApiKey()` – reads `POE_API_KEY` env var or credentials file. - `getPoeAuthIdentity()` – fetches Poe account identity. For plugin-first composition, use the `poe-code/agent` subpath with `agent()`, `openaiResponsesPlugin()`, `systemPromptPlugin()`. ## Research Preview Features subject to breaking changes: - **SafeJS** – JavaScript interpreter with explicit host capabilities, execution budgets, resumable checkpoints. Published as `@poe-platform/safe-js`. Full conformance not established. - **Pipeline** – Run task plans with configurable steps, live progress, queued follow-ups. - **Ralph** – Agentic build loop iterating on a markdown doc. - **Experiment loop** – Karpathy-style optimize loop (agent changes code, eval scores, keep/discard via git). - **Poe Agent** – Composable agent runtime. ## Update ```sh npx poe-code@latest update npx poe-code@latest update --package-manager pnpm ``` For version checks, dry runs, and managed worktrees, see the full reference.