esque-bridge

Desktop-side receiver for the Esque Agent iOS app. Pairs your phone with the local claude CLI so prompts you send from the app run through your Claude Pro / Max subscription rather than per-token API billing.

What it does

1. Boots an Express server on localhost
2. Opens a public localtunnel URL to that port
3. Prints a QR code in your terminal embedding esque://pair?url=…&secret=…
4. Accepts POST /execute { prompt, sessionId } (pairing-secret-gated)
5. Runs each prompt through claude --print --output-format json
6. Returns Claude's response to the phone, persisting the Claude session id so the next prompt continues the same conversation

Install

You'll need:

• Node.js 18 or newer — https://nodejs.org
• Claude Code CLI logged into your Pro/Max account:

  npm install -g @anthropic-ai/claude-code
  claude /login

Then either run via npx (no install) or globally:

npx esque-bridge                    # zero-install
# — or —
npm install -g esque-bridge
esque-bridge

Run

# from the directory you want Claude to edit:
esque-bridge

# point at a different repo without cd:
esque-bridge --workdir ~/my-project

# pick a non-default port:
esque-bridge --port 4000

The terminal will print a QR code. Open the Esque Agent iOS app, tap Pair Bridge, and scan the code. That's it.

Flags

| Flag | Default | Purpose | | ------------- | ------------ | ----------------------------------------- | | --port | 3030 | Local HTTP port | | --workdir | $(pwd) | Directory Claude runs in | | --bin | claude | Path to the Claude CLI binary | | --timeout | 300000 | Per-prompt timeout (ms) | | --subdomain | (auto) | Stable localtunnel subdomain (optional) |

Security notes

• The pairing secret is regenerated every time the bridge starts and never persisted. If you stop and restart, you must re-pair the phone. This is deliberate — a leaked tunnel URL alone can't drive your Claude session.
• The bridge accepts a no-auth GET / and POST / {_probe: true} for the Esque app's connection-test only. Every other request requires the secret in the X-Esque-Pair header.
• spawn(claude, [...args]) is used so the prompt body can never inject shell commands.

Troubleshooting

'claude' not found in PATH — install the CLI: npm install -g @anthropic-ai/claude-code, then claude /login to authenticate.

Failed to open localtunnel — your network is blocking localtunnel.me. Run cloudflared instead:

cloudflared tunnel --url http://localhost:3030

…and paste that URL into the Esque app manually (skip the QR).

Long prompts time out — bump --timeout 600000 (10 min).

Session continuity

Each Esque conversation maps to a Claude session id. The map is persisted to ~/.esque-bridge-sessions.json so restarting the bridge doesn't lose context. Delete that file to wipe history.

License

MIT