opencode-wa

Your phone is now a Claude terminal. Message yourself on WhatsApp, talk to OpenCode.

opencode-wa turns WhatsApp into a full remote control for OpenCode — the open-source AI coding assistant. Send a message, get a reply from Claude (or any model you have configured). Switch sessions, swap agents, tune reasoning effort, send photos or PDFs — all from the chat you're already in.

Runs entirely on your own machine. No cloud bridge, no forwarding, no tokens leaving your network. The gateway spawns its own local OpenCode server on a loopback port and talks to it directly.

Install

npm install -g opencode-wa

Requires OpenCode installed and on your PATH.

Get started in 60 seconds

opencode-wa config        # interactive: link WhatsApp, set access policy
opencode-wa run           # start the gateway

Open WhatsApp → Message yourself → send /help. That's it.

Highlights

🤖 Full AI access from a chat app

Every model you've configured in OpenCode is available. Free ones tagged, paid ones shown with their provider/ID. Switch per-session. Mix and match: one conversation on Claude Opus, another on GPT-5, another on a free Zen model.

🧵 Real session management

Your OpenCode sessions — the same ones in the TUI — are browsable, pinnable, renameable, forkable from WhatsApp. Pin a session with /sess 3 and everything you send routes to it until you switch.

🧠 Reasoning variants

Models that expose variants (GPT-5, GPT-5 Nano, etc.) let you set effort from your phone: /variants high, /variants minimal. Per-session, persists across restarts.

🧑‍💻 Agent switching

Every OpenCode agent (build, plan, explore, subagents, custom ones) is selectable per session. /agent plan turns the conversation into a planner; /agent build gives it write access. Live in the same session as the TUI, stay in sync.

↩️ Undo / redo

Accidentally sent a message that poisoned context? /undo reverts it server-side — same surface as OpenCode's own revert. /redo puts it back. Chain undos to walk back through history.

📦 Media support

Send images, PDFs, audio, video, stickers. The gateway downloads from WhatsApp, converts to a base64 data URL, hands it to the model alongside your caption. The AI sees both.

Limits:

• Images (JPEG / PNG / GIF / WebP)
• Audio (MP3 / M4A / OGG / WAV)
• Documents (PDF / DOCX / TXT)
• Video (MP4 / WebM)
• Stickers (WebP)
• 50 MB per file cap

🛡️ Access control, not a free-for-all

Four policies:

• allowlist — only whitelisted numbers reach the AI
• pairing — unknown senders get a one-time code to pair
• open — anyone who messages you gets routed
• disabled — ignore all DMs; only your self-chat works

Control commands (/status, /new, etc.) only respond in your self-chat, regardless of policy.

🚨 No more infinite retry loops

opencode-wa watches the OpenCode event stream for usage-limit events and aborts cleanly. You get one ⚠️ Usage limit reached message instead of a silent hang while OpenCode retries forever.

🔌 Zero-config port

Spawns opencode serve on a random free loopback port. Never collides with anything else on your machine. Never exposed to the network.

🗜 Lightweight

~300 KB installed, zero frameworks. Baileys for WhatsApp, opencode serve for AI — that's it.

How it works

  WhatsApp phone (Linked Device)
            │
            ▼  Baileys (WhatsApp Web protocol)
  ┌──────────────────────────────┐
  │  opencode-wa gateway         │
  │  • access control             │
  │  • media download (≤50 MB)    │
  │  • per-session state          │
  │  • command dispatch           │
  └──────────────────────────────┘
            │  HTTP on 127.0.0.1:<random>
            ▼
  ┌──────────────────────────────┐
  │  opencode serve (child)      │
  │  • your configured models     │
  │  • sessions, agents, history  │
  └──────────────────────────────┘
            │
            ▼
       Claude / GPT / etc

Commands

17 commands. All available from your "Message yourself" chat.

Session

| Command | Description | |---|---| | /sesslist | List OpenCode sessions (top 20) | | /sess <n> | Pin session by index | | /sess <ses_...> | Pin session by ID | | /sess show | Show the pinned session | | /sess d <n> yes | Delete a session | | /new | Create a new session and pin it | | /title <name> | Rename the pinned session | | /history · /history <n> | Recent messages (default 10, max 50) | | /last | Re-send the most recent AI reply |

Model & agent

| Command | Description | |---|---| | /modellist | All available models, free/paid tagged | | /model | Show current override + what the session last used | | /model <n> · /model provider/id | Switch model | | /model default | Clear override; use session's own | | /agent | Show current agent + list available | | /agent <n\|name> | Switch agent | | /agent default | Clear override | | /variants | Show variants for the current model | | /variants <n\|name> | Switch reasoning variant | | /variants default | Clear variant override |

Control

| Command | Description | |---|---| | /status | Session, agent, model, last-used | | /stop | Abort running AI operation | | /undo · /redo | Revert / restore last message | | /ping | Health check | | /help | Full command list (auto-generated) | | /stats | Usage stats (sessions, tokens, cost, tool counts) — runs opencode stats | | /diag | Gateway diagnostics JSON |

Config

~/.config/opencode-wa/config.json

{
  "owner": "+1234567890",
  "dmPolicy": "allowlist",   // allowlist | pairing | open | disabled
  "allowFrom": ["+1987654321"],
  "selfChatMode": true,
  "cmdPrefix": "/bot"        // optional — only process messages with this prefix
}

Rerun opencode-wa config anytime to tweak interactively.

State (preserved across upgrades)

~/.local/state/opencode-wa/auth/default/creds.json   # WhatsApp credentials
~/.local/state/opencode-wa/pinned-session.json       # pinned session + overrides

npm i -g opencode-wa@latest never touches these.

CLI reference

opencode-wa config                 # interactive configuration
opencode-wa config init \
  --owner +1234567890 \
  --self-chat \
  --allow +1234567890,+1987654321 \
  --prefix /bot                    # non-interactive setup

opencode-wa run                    # start the gateway (spawns opencode serve)
opencode-wa run --attach http://127.0.0.1:4096
                                   # attach to an already-running OpenCode server
opencode-wa run --attach <url> --password <pw>
                                   # attach with Basic auth
opencode-wa run --bridge ./bridge.js
                                   # use a custom bridge (advanced)

opencode-wa link                   # (re)scan QR to pair the linked device
opencode-wa relink                 # force full re-link
opencode-wa status                 # current config + linked state

Environment

| Variable | Effect | |---|---| | WA_VERBOSE=1 | Verbose logging | | OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 | Disable OpenCode's Claude Code prompt integration (inherited) |

Troubleshooting

| Symptom | Fix | |---|---| | cannot execute opencode | Install the OpenCode CLI and ensure it's on PATH | | QR code never appears | opencode-wa relink to reset credentials and retry | | Gateway disconnects instantly | Run opencode-wa config again to rebuild config | | /modellist is empty | opencode auth login — no providers configured yet | | Port 4096 already in use | v0.1.6+ uses a random free port by default | | Hangs on "usage limit" | Upgrade to 0.1.4+ — now auto-aborts on quota events |

Upgrading

npm i -g opencode-wa@latest

Credentials, pinned session, and config live outside the package — upgrades never log you out or reset state.

License

MIT