codepoet-edgar

Edgar Allen Code — the execution runner for Codepoet.

Edgar runs on your machine and uses your Claude Code subscription to execute stories planned in Codepoet. It connects outbound to the Codepoet backend via WebSocket — no port forwarding or firewall changes needed.

Quick start

# Install globally
npm install -g codepoet-edgar

# Authenticate with your Codepoet account (one-time)
edgar login

# Connect to Codepoet (leave running)
edgar connect

Requirements

• Node.js 20+
• Claude Code subscription (Max plan)

No native build tools needed — Edgar ships with prebuilt PTY binaries via @homebridge/node-pty-prebuilt-multiarch.

Commands

| Command | Description | |---------|-------------| | edgar login | Authenticate with your Codepoet account (opens browser) | | edgar connect | Connect to Codepoet backend (bridge mode) | | edgar start | Start Edgar as a standalone local server | | edgar status | Check if Edgar is running | | edgar help | Show usage info |

How it works

When you run edgar connect, Edgar:

1. Loads your saved token from ~/.edgar/config.json (from edgar login)
2. Connects outbound to wss://api.buildwithcodepoet.com/ws/runner
3. Receives JSON-RPC execution commands from the Codepoet backend
4. Spawns Claude Code sessions in isolated git worktrees on your machine
5. Streams PTY output and session events back to the Codepoet UI in real time

Your code never leaves your machine. Codepoet orchestrates, Edgar executes.

Architecture

Frontend (Codepoet UI)
    ↓ SSE events / REST API
Backend (FastAPI)
    ↓ WebSocket (JSON-RPC)
Edgar (your machine)
    ↓ PTY
Claude Code (your subscription)

The backend's /ws/runner endpoint authenticates Edgar via JWT, then sends commands (createSession, sendInput, getOutput, etc.) over the WebSocket. Edgar dispatches these to its session manager, PTY manager, and git handler, then sends back results and push events (pty:data, session:status, etc.).

Local development

# Run against a local backend
edgar login --url http://localhost:8000
edgar connect --url http://localhost:8000

# Or use the local build directly (no npm publish needed)
node dist/cli.js connect --url http://localhost:8000

The --url flag accepts a base URL (e.g. http://localhost:8000) — Edgar automatically appends /ws/runner and converts http:// to ws://.

The saved backend_url from edgar login is reused by edgar connect, so you only need --url on the first command.

Environment variables

| Variable | Description | Default | |----------|-------------|---------| | EDGAR_PORT | Local debug server port | 3100 | | EDGAR_DATA_DIR | Data directory | ~/.edgar | | EDGAR_RUNNER_TOKEN | Runner auth token (alternative to edgar login) | — | | EDGAR_BACKEND_URL | Backend WebSocket URL | wss://api.buildwithcodepoet.com/ws/runner | | EDGAR_MAX_SESSIONS | Max concurrent sessions | 20 | | ANTHROPIC_API_KEY | For Claude Code agent | — |

Known Limitations

• Runner JWT lifetime: Runner tokens are valid for 30 days with no server-side revocation. If a token is compromised, it cannot be invalidated until expiry. A future release will add a token denylist or DB-backed tracking.