https://github.com/poe-platform/poe-code
Use Poe to power your favorite coding agents (Claude Code, Codex, OpenCode, etc). No need for multiple subscriptions.
https://github.com/poe-platform/poe-code
claude code codex opencode
Last synced: 8 days ago
JSON representation
Use Poe to power your favorite coding agents (Claude Code, Codex, OpenCode, etc). No need for multiple subscriptions.
- Host: GitHub
- URL: https://github.com/poe-platform/poe-code
- Owner: poe-platform
- Created: 2025-10-17T20:26:49.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-06-07T19:54:05.000Z (15 days ago)
- Last Synced: 2026-06-07T20:19:09.479Z (15 days ago)
- Topics: claude, code, codex, opencode
- Language: TypeScript
- Homepage:
- Size: 23 MB
- Stars: 83
- Watchers: 1
- Forks: 9
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Roadmap: ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
Poe Code ⚡
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](https://poe.com/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
```bash
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.
```bash
# 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)
```bash
npx poe-code@latest unconfigure claude
```
## Authentication
Poe Code uses your [Poe API key](https://poe.com/api) for authentication. On first run, you'll be prompted to log in via your browser (OAuth). You can also provide your key directly:
```bash
# Interactive login (opens browser)
npx poe-code@latest login
# Or pass your API key directly
npx poe-code@latest login --api-key
# Or set it as an environment variable
export POE_API_KEY=
```
Credentials are stored locally in `~/.poe-code/`. Use `poe-code auth status` to check your login state.
```bash
# Remove all configuration and credentials
npx poe-code@latest logout
```
## Quick links
- [Utilities](#utilities)
- [Usage and Billing](#usage--billing)
- [Models](#models)
- [MCP Server](#poe-mcp-server)
- [SDK](#sdk)
- [Research Preview](#research-preview)
- [Poe API](https://poe.com/api)
## Utilities
Utilities are especially useful for scripting and CI/CD.
#### Spawn a one-off prompt
```bash
npx poe-code@latest spawn codex "Say hello"
```
#### Spawn against a GitHub repository
```bash
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
```bash
echo "Say hello" | npx poe-code@latest spawn codex
```
#### Review a GitHub pull request
```bash
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
```bash
npx poe-code@latest test codex
```
### Install agent CLIs
```bash
# 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:
```bash
SKIP_SYNC_SKILLS=1 npm install
```
## Usage & Billing
Check your compute points balance and review usage history.
```bash
# 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.
```bash
# 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.
```bash
# 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:
```typescript
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:
```typescript
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`, `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](packages/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.
```typescript
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.
```typescript
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](packages/pipeline/)** — Run YAML task plans through agents with configurable steps
- **[Ralph](packages/ralph/)** — Agentic build loop that iterates on a markdown doc
- **[Experiment loop](packages/experiment-loop/)** — Karpathy-style optimize loop: agent changes code, eval script scores it, keep or discard via git, repeat.
- **[Poe Agent](packages/poe-agent/)** — Composable agent runtime