wcp Documentation

Installation

Quick Install

curl -fsSL https://wcp.dev/install | bash

This installs wcp and adds the /wcp command to supported AI tools (Claude

Code, Cursor, OpenCode).

Manual Install with Deno

deno install -gAf --name wcp https://raw.githubusercontent.com/umbrellamode/wcp/main/mod.ts

Update

wcp update

Commands

wcp (no arguments)

The simplest way to use wcp. When you run wcp with no arguments, it will:

• If sessions are running: Watch all active sessions
• If no sessions but config exists: Auto-start the dev server from your

• If no sessions and no config: Show helpful guidance

wcp

This is the recommended command for users who want to monitor what the AI agent

is running.

wcp dev

Auto-detect your project type and start a dev server.

wcp dev

Detects:

• package.json → npm/pnpm/yarn/bun scripts
• deno.json → Deno tasks
• Cargo.toml → Cargo commands
• go.mod → Go commands
• Makefile → Make targets
• docker-compose.yml → Docker Compose

wcp <name> -- <command>

Create a wormhole and run a command.

# Start a Next.js dev server
wcp 3000 -- npm run dev

Start a Rust server
wcp api -- cargo run

Start any command
wcp logs -- tail -f /var/log/syslog

The name can be anything: dev, 3000, api, my-server.

wcp <name>

Connect to an existing wormhole.

# Connect to the wormhole named "dev"
wcp dev

Connect to wormhole "3000"
wcp 3000

When you connect, you'll see:

• Replay of the last 1000 lines of output
• Live streaming of new output
• Ability to send input to the process

wcp list

List all active wormholes.

wcp list

Output:

Active wcps:
  • Port dev
  • Port 3000
  • Port api (stale)

Stale wormholes are sockets that exist but the process has died.

wcp kill <name>

Terminate a wormhole.

wcp kill dev

wcp init

Generate AI agent documentation for your project.

wcp init

Creates or updates:

• CLAUDE.md - Guidance for Claude Code
• AGENTS.md - Guidance for other AI agents

wcp update

Update wcp to the latest version.

wcp update

wcp help

Show help message.

wcp help

How It Works

Architecture

┌─────────────────┐     Unix Socket      ┌─────────────────┐
│   AI Agent      │ ←─────────────────→  │    wcp daemon   │
│   (Terminal 1)  │                      │                 │
└─────────────────┘                      │  ┌───────────┐  │
                                         │  │  Child    │  │
┌─────────────────┐     Unix Socket      │  │  Process  │  │
│   You           │ ←─────────────────→  │  │ (npm dev) │  │
│   (Terminal 2)  │                      │  └───────────┘  │
└─────────────────┘                      │                 │
                                         │  Ring Buffer   │
┌─────────────────┐     Unix Socket      │  (1000 lines)  │
│   Another User  │ ←─────────────────→  │                 │
│   (Terminal 3)  │                      └─────────────────┘
└─────────────────┘

Data Flow

• Daemon starts: Creates Unix socket at ~/.wormhole/wormhole-<name>.sock
• Process spawns: Daemon runs your command, captures stdout/stderr
• Output buffered: Last 1000 lines stored in a ring buffer
• Clients connect: Receive replay of buffer, then live stream
• Bidirectional: Clients can send stdin to the child process

Message Protocol

All messages use a 4-byte big-endian length prefix followed by JSON:

┌──────────────┬─────────────────────────────┐
│ Length (4B)  │ JSON Payload                │
└──────────────┴─────────────────────────────┘

Message types:

• data - Output from the child process
• stdin - Input from a client
• replay-start - Beginning of history replay
• replay-end - End of history replay

Examples

Development Server

Start a dev server that others can monitor:

# Terminal 1 (AI Agent)
wcp dev -- npm run dev

Terminal 2 (You)
wcp dev

Named Sessions

Use descriptive names for multiple services:

# Start backend
wcp backend -- cargo run

Start frontend
wcp frontend -- npm run dev

Start database
wcp db -- docker-compose up postgres

Monitoring Logs

Watch log files through wcp:

# Terminal 1
wcp logs -- tail -f /var/log/app.log

Terminal 2
wcp logs

Configuration

Socket Location

Sockets are stored in ~/.wormhole/:

~/.wormhole/
├── wormhole-dev.sock
├── wormhole-3000.sock
└── wormhole-api.sock

Buffer Size

The ring buffer holds the last 1000 lines of output. This is currently not

configurable.

Troubleshooting

"Wormhole already exists"

A socket file exists for that name. Either:

• Connect to it: wcp <name>
• Kill it first: wcp kill <name>

"Connection refused" or "stale" socket

The daemon died but the socket file remains. Kill and restart:

wcp kill <name>
wcp <name> -- <command>

Socket permission errors

Ensure ~/.wormhole/ is writable:

chmod 700 ~/.wormhole

For AI Agents

When using wcp from an AI coding agent:

• Detect the project type before running
• Use wcp dev for auto-detection when possible
• Tell the user how to connect: "Run wcp in another terminal to watch the

• Check for existing wormholes with wcp list