TapTapAI Claude Code Bridge Plugin

Local bridge that wraps the claude CLI, allowing you to control Claude Code from the TapTapAI iOS / watchOS apps.

How it works: The plugin runs on your dev machine as a long-lived process. It connects to the TapTapAI backend via WebSocket and, when you send a message from the app, it spawns claude -p (print/headless mode) with your prompt and streams the response back in real time.

Plugin ID: taptapai-claude-code

Prerequisites

| Requirement | Notes | |---|---| | Node.js ≥ 18 | Uses ESM + node: built-ins | | Claude CLI | Install from code.claude.com. Must be on $PATH or configured via claudePath. | | Claude auth | Run claude auth login once to authenticate |

Quick start

1) Install

cd claude-code-plugin
npm install

2) Configure

Create ~/.taptapai/claude-code/config.json:

{
  "backendWsUrl": "wss://your-backend.example.com/ws/claudecode/v2",
  "wsToken": "YOUR_PAIRING_TOKEN",
  "workingDir": "/path/to/your/project",
  "model": "claude-sonnet-4-6",
  "allowedTools": ["Read", "Glob", "Grep"],
  "permissionMode": "default",
  "logLevel": "info"
}

Or use taptapai setup --plugin claude-code (when supported by the CLI).

3) Run

npm start

Or directly:

npx tsx index.ts

4) Pair from TapTapAI app

The pairing flow is handled by the same taptapai CLI token system.

Configuration

| Option | Env var | Default | Description | |---|---|---|---| | backendWsUrl | TAPTAPAI_CLAUDE_WS_URL | wss://taptapai.gettaptap.ai/ws/claudecode/v2 | Backend WS endpoint | | wsToken | TAPTAPAI_CLAUDE_WS_TOKEN | — | Auth token (required) | | claudePath | CLAUDE_PATH | $PATH lookup | Absolute path to claude binary | | workingDir | TAPTAPAI_CLAUDE_WORKDIR | $HOME | CWD for claude sessions | | model | TAPTAPAI_CLAUDE_MODEL | (CLI default) | Model name or alias | | allowedTools | — | [] | Tools auto-approved without prompting | | maxTurns | — | 0 (unlimited) | Max agentic turns per request | | appendSystemPrompt | — | — | Extra instructions appended to system prompt | | permissionMode | — | default | default, plan, or bypassWithTools | | logLevel | — | info | error / warn / info / debug |

RPC Protocol

The plugin communicates with the TapTapAI backend over WebSocket using a simple JSON RPC protocol:

Inbound (backend → plugin)

{ "id": "req-123", "method": "chat.send", "params": { "text": "explain auth.py" } }

Outbound (plugin → backend)

| Message type | When | Payload | |---|---|---| | chat.ack | Request received | { status: "processing" } | | chat.delta | Each text token | { text: "...", index: N } | | chat.tool | Tool invocation | { tool: "Read", input: {...} } | | chat.final | Complete response | { text: "...", session_id: "..." } | | chat.error | Failure | { error: "...", code: "..." } | | chat.cancelled | After cancel | { request_id: "...", killed: true } |

Methods

| Method | Params | Description | |---|---|---| | chat.send | text, session_id?, continue?, working_dir?, model?, plan_mode? | Send prompt, get streaming response | | chat.cancel | request_id | Kill a running chat process | | sessions.list | — | List tracked sessions | | sessions.resume | session_id, text | Resume session with new prompt | | sessions.delete | session_id | Remove session from local store | | claude.status | — | CLI availability + active processes | | health | — | Heartbeat |

Architecture

┌──────────────────┐    WebSocket     ┌──────────────────┐
│  TapTapAI App    │ ◄──────────────► │  TapTapAI        │
│  (iOS / watchOS) │                  │  Backend         │
└──────────────────┘                  └────────┬─────────┘
                                               │ WS (RPC)
                                               ▼
                                      ┌──────────────────┐
                                      │  Claude Code     │
                                      │  Bridge Plugin   │
                                      │  (this process)  │
                                      └────────┬─────────┘
                                               │ spawn subprocess
                                               ▼
                                      ┌──────────────────┐
                                      │  claude -p       │
                                      │  (CLI headless)  │
                                      │  stream-json     │
                                      └──────────────────┘

The bridge runs on your dev machine alongside the claude CLI. Messages flow:

1. You tap a message in the TapTapAI app
2. App sends it to the TapTapAI backend
3. Backend forwards via WS to the bridge plugin
4. Bridge spawns claude -p "your message" --output-format stream-json
5. Streaming tokens flow back: bridge → backend → app
6. Session IDs are tracked for /resume support

Claude CLI flags used

| Flag | Purpose | |---|---| | -p "prompt" | Non-interactive (headless) mode | | --output-format stream-json | NDJSON streaming output | | --verbose | Include all event types | | --include-partial-messages | Stream tokens as they arrive | | --resume <id> | Continue a previous session | | --continue | Continue most recent session | | --model <name> | Model selection | | --allowedTools <tools> | Auto-approve specified tools | | --max-turns <N> | Limit agentic turns | | --append-system-prompt | Custom instructions | | --permission-mode plan | Read-only analysis mode | | --name <name> | Name the session for later resumption |

Troubleshooting

"Claude CLI not found" — Install from https://code.claude.com or set claudePath in config to the absolute path.

"Not authenticated" — Run claude auth login in your terminal.

"No wsToken configured" — Run taptapai setup --plugin claude-code or manually create ~/.taptapai/claude-code/config.json with your WS token.

Slow responses — Claude Code runs locally; response speed depends on your Anthropic plan and the model selected. Use --model sonnet for faster responses.

License

Same as TapTapAI — see root LICENSE.