pl4n

Pl4n (Bun + TypeScript)

Multi-agent ensemble planning CLI. Orchestrates multiple AI agents (Claude Code, OpenAI Codex) to collaboratively create implementation plans with human-in-the-loop review.

Why Pl4n?

"A droid is only as good as its plan." Planning with multiple models produces more robust plans through:

• Diversity: Different models notice different things when exploring codebases
• Peer review: Agents critique each other's drafts before synthesis
• Iteration: Human feedback refines plans across multiple turns

Install

From source:

bun install
bun run src/index.ts --help

Quick Start

# Start a planning session (blocks until first turn is complete)
bun run src/index.ts init "Add user authentication"

# Review and edit the plan
# Edit .pl4n/sessions/<id>/turns/001.md

# Continue to next turn (blocks until agents complete)
bun run src/index.ts continue --session <session_id>

# Approve when satisfied
bun run src/index.ts approve --session <session_id>

Web Editor

Pl4n can launch a lightweight web editor for reviewing and editing plans. When init or continue completes, the server starts (if needed) and an edit_url is included in the JSON output.

# Default behavior: start server and emit edit_url
bun run src/index.ts init "Add user authentication"

# Disable web editor
PL4N_WEB=0 bun run src/index.ts init "Add user authentication"

Manual server control:

pl4n server start            # start daemon
pl4n server stop             # stop daemon
pl4n server status           # check running status
pl4n server start --restart  # kill existing server, then start
pl4n server start --foreground   # run in foreground (dev)
pl4n server start --workspace /path/to/root  # scan a specific workspace
pl4n server start --bind 127.0.0.1           # bind address

For remote access (Tailscale/VPN), override the host used in URLs:

PL4N_HOST=100.x.x.x bun run src/index.ts init "Add user authentication"

Troubleshooting:

• If the browser cannot connect, check local firewall settings and that the port is reachable.
• If port 3456 (or PL4N_PORT) is taken, the server will try the next available port.
• Clipboard copy is best-effort; the URL is always printed in JSON output.

Server configuration lives in ~/.pl4n/config.yaml:

workspaces:
  - /Users/you/code
  - /Users/you/work
bind: 0.0.0.0
port: 3456
auth:
  mode: strict

Auth modes:

• strict (default) requires a t query param token for UI and API requests (the CLI provides edit_url with tokens).
• trusted skips token checks for allowlisted client IPs; other clients still need tokens.

For LAN + Tailscale access without tokens, use trusted mode with a CIDR allowlist:

auth:
  mode: trusted
  trusted_cidrs:
    - 127.0.0.0/8
    - 10.0.0.0/8
    - 172.16.0.0/12
    - 192.168.0.0/16
    - 100.64.0.0/10

If trusted_cidrs is omitted, Pl4n defaults to the list shown above. CIDRs must be IPv4 (::1 and IPv4-mapped IPv6 are supported; other IPv6 ranges are not).

You can also set a single workspace via PL4N_WORKSPACE=/path/to/root. Server env overrides: PL4N_BIND=0.0.0.0, PL4N_HOME=/custom/.pl4n.

The server UI starts at /projects and links to project-scoped session lists and editors.

How It Works

Turn-Based Planning

Each turn follows this flow:

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   DRAFT     │ -> │ PEER REVIEW │ -> │  SYNTHESIS  │ -> │ USER REVIEW │
│             │    │             │    │             │    │             │
│ Each agent  │    │ Agents      │    │ Merge into  │    │ Human edits │
│ writes plan │    │ review peer │    │ unified     │    │ turns/001.md│
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

1. Draft: Each agent explores the codebase and writes an independent plan
2. Peer Review: Agents review each other's drafts and refine their own
3. Synthesis: Plans are merged into a unified proposal
4. User Review: Human edits turns/NNN.md, then calls continue or approve

Session Continuation

Agents maintain context across turns via CLI session continuation:

• Claude Code: --resume <session_id>
• Codex: resume <thread_id>

This means agents accumulate codebase knowledge rather than starting fresh each turn.

User Feedback as Diff

When you edit turns/001.md and call continue, agents receive your changes as a diff. They interpret your edits naturally:

• Deletions = remove this
• Additions = add this requirement
• Comments = feedback to address

Commands