CodeMote CLI

Run coding agents on your machine, drive them from your iPhone & iPad. CodeMote streams a real terminal, your files, Git, and — new in 2.0 — native Claude Code agent chats to the CodeMote iOS app over a secure tunnel. No file-syncing and no cloud copy of your code: the phone is a remote control for the machine that's already running your work.

Unlike the CodeMote VS Code extension, this CLI needs no IDE — run it on a VPS, a server, or any machine with Node, on macOS, Linux, or Windows.

You also need the CodeMote iOS app on your iPhone or iPad to connect.

New in 2.0

• Native agent chats. Start Claude Code sessions and steer them from a real native chat UI on the phone — approve/deny tool permissions, watch sub-agent work, attach PDFs, use slash commands, and rewind. Requires the claude binary on the host (see Agent chats).
• Zero-setup tunnel. Cloudflare quick tunnels are the new default — npx codemote-cli start just works, no account and no login.
• Git PR review. Open, diff, close, and merge pull requests from your phone.
• Notes. A first-class notes editor, opened with a shake.
• In-editor media. View images & Markdown and play video/audio right in the mobile editor.

Install & run

# one-off — zero setup, just works
npx codemote-cli start

# or install globally, then use the `codemote` command anywhere
npm install -g codemote-cli
codemote start           # run inside the project folder you want to drive

codemote start [path] starts a session in the current folder (or the given path), prints a QR code plus a pasteable pairing string, and stays in the foreground. Scan the QR — or paste the code into the app's Enter code manually sheet — to connect. Press Enter for a fresh pairing code, and Ctrl-C to stop.

The tunnel is outbound-only, so it works behind a firewall or NAT with no inbound ports opened.

Agent chats

CodeMote can host native Claude Code agent chats: instead of typing into a raw terminal, you get a proper chat UI on the phone with tool-permission prompts, live token/progress, sub-agent transcripts, slash commands, PDF attachments, and rewind.

This needs the claude binary on the host machine. Install it once:

curl -fsSL https://claude.ai/install.sh | bash
# or: npm i -g @anthropic-ai/claude-code

On start, CodeMote prints whether it found Claude Code. If it's missing, the terminal, files, Git, and notes still work — only agent chats are gated.

Choosing a tunnel

CodeMote reaches your phone through a tunnel. The default — Cloudflare — needs zero setup but hands out a fresh URL each restart. The other three give a stable URL, so a paired device reconnects across restarts without re-scanning.

codemote start               # cloudflare (default, zero setup, ephemeral URL)
codemote start --ngrok       # ngrok (stable)
codemote start --tailscale   # tailscale funnel (stable)
codemote start --devtunnel   # devtunnel (stable)
codemote start --ngrok ~/app # any provider + an explicit folder

Print a provider's full setup guide any time:

codemote help              # overview of all providers
codemote help cloudflare
codemote help ngrok
codemote help tailscale
codemote help devtunnel

| Provider | One-time setup | URL | Notes | |-----------------------|--------------------------------------------------|-----------|-------| | cloudflare (default) | none | ephemeral | zero setup; binary auto-downloaded; re-pair after restart | | ngrok | free account + paste one API key | stable | binary auto-downloaded; static domain auto-assigned | | tailscale | install + tailscale up + enable Funnel | stable | your own tailnet; most private | | devtunnel | install devtunnel + devtunnel user login | stable | Microsoft; the login can expire and prompt again |

CodeMote remembers the last provider you chose, so you set it once. Everything runs on your own machine under your own account — no CodeMote servers, no CodeMote-held credentials.

cloudflare (default)

The fastest way to connect. On first use CodeMote downloads Cloudflare's cloudflared and opens a temporary public HTTPS tunnel — no account, no login, no configuration. The trade-off: the URL is ephemeral, so you get a new https://<words>.trycloudflare.com each restart and re-pair (scan the QR again) next time. Want a URL that survives restarts? Switch to any stable provider below once and CodeMote remembers it.

ngrok

A stable public HTTPS URL through your own free ngrok account.

1. Create a free account at ngrok.com.
2. In the dashboard, open Identity & Access → API Keys and create an API key.
3. Give it to CodeMote once:

   codemote config set ngrok.apiKey <YOUR_API_KEY>
   codemote start --ngrok

From that one API key CodeMote downloads the ngrok binary, mints a tunnel authtoken, and reserves your free static domain — all automatically, cached in ~/.codemote/config.json. (On the free plan ngrok picks the domain name; it's permanent and reused every run.)

tailscale

The most private option — the tunnel lives inside your own tailnet, and Tailscale Funnel exposes just the one port over a stable *.ts.net URL.

1. Install Tailscale and sign in: tailscale up.
2. In the Tailscale admin console, enable HTTPS certificates and the Funnel node attribute (see codemote help tailscale for the exact steps).
3. Run:

   codemote start --tailscale

devtunnel

A stable URL through Microsoft's dev tunnels.

devtunnel user login
codemote start --devtunnel

Install the devtunnel CLI first. If the recurring login prompts bother you, ngrok or tailscale use a credential you set once that doesn't expire.

Requirements

• Node.js 18+
• For agent chats: the claude binary (see Agent chats).
• Cloudflare (default) needs nothing else. For a stable URL, set up one of the other providers (see Choosing a tunnel).

What you get on the phone

• Native Claude agent chats — permission prompts, sub-agent transcripts, live progress, slash commands, PDF attach, and rewind.
• A real terminal — run dev servers, agent CLIs, anything.
• File browsing, image & Markdown viewing, and in-editor video/audio playback.
• Full local Git (status, diff, commit, push, branches) plus PR review (open, diff, close, merge) — no credentials ever leave your machine.
• A notes editor.
• Live terminal activity on your Lock Screen (Live Activities), so you know when an agent needs you.

Configuration

codemote config reads and writes ~/.codemote/config.json (created with 0600 permissions):

codemote config set ngrok.apiKey <key>
codemote config get ngrok.apiKey

Notes

• With a stable provider, session tokens persist to ~/.codemote/session-tokens.json, so a paired device reconnects across restarts without re-scanning. (Cloudflare's URL rotates each restart, so it re-pairs.)
• Your code never leaves your machine; only terminal/file/Git/agent data you request is streamed to your paired phone over the encrypted tunnel.

Learn more at codemote.caste.work.