Vibe Remote — 手機上的 AI Coding 助手

Mon, 08 Jun 2026 00:00:00 +0000

專案簡介

通勤時用手機語音或文字下指令，AI 幫你讀 codebase、寫程式碼，你審 diff、一鍵 commit push。這就是 Vibe Remote 在做的事。

手機上開不了 IDE，但 AI 可以替你操作整個 codebase。Vibe Remote 把 Claude Agent SDK 包裝成 mobile-first 的介面，專門為「對話 → review diff → approve → commit」的工作流設計。

跟 ChatGPT 或 Cursor 不一樣，Vibe Remote 不是聊天機器人。它是一個有完整 codebase 存取權的 AI Agent——可以讀檔、改檔、跑指令、自動修 bug，最後把改動交給你審查。

主要功能

AI 對話 — Claude Agent SDK 串流回應，即時看到 AI 的思考過程和 tool 呼叫
Diff 審查 — AI 改完程式碼後逐檔檢視差異，可以批准、退回、或留言要求修改
Git 操作 — commit、push、pull、切分支，全部在手機上完成
多 Workspace 並行 — 最多 3 個 AI Runner 同時跑，左滑右滑切換不同專案
非同步任務佇列 — Kanban 看板管理待辦任務，排隊讓 AI 依序處理
PWA 安裝 + Push 通知 — 安裝到主畫面，AI 完成任務後收到推播
Prompt 模板 — 常用指令存成模板，一鍵套用

架構概覽

1
2
3
4
5


手機 (PWA) ──HTTPS──→ Tailscale ──→ Docker Container
 ├── Express API + WebSocket (port 8080)
 ├── Claude Agent SDK Runner (max 3 並行)
 ├── SQLite (WAL mode)
 └── /workspace (volume mount → ~/projects)

Express API + WebSocket — 同一個 port 處理 REST API 和 WebSocket。WebSocket 負責 AI 串流回應和即時通知，REST 處理 CRUD 操作。

Claude Agent SDK Runner — 封裝 SDK 的 query() 函式，設定 cwd 為 workspace 路徑後，SDK 自動讀取專案的 CLAUDE.md，內建 Read / Edit / Write / Bash / Grep / Glob 等 tools。每個 runner 獨立追蹤 modified files，完成後觸發 diff review。

SQLite — 儲存對話歷史、diff reviews、裝置資訊、push subscriptions。開啟 WAL mode + busy_timeout，讓多個 runner 可以並行讀寫。

/workspace — Docker volume mount，把 host 的專案目錄映射進容器。手機上 approve 的改動，回到電腦 git pull 就能同步。

技術選型

選擇	原因
Claude Agent SDK	內建 Read/Edit/Write/Bash 等 tools，不用自己定義 tool schema，SDK 自動處理多輪 tool call
SQLite (better-sqlite3)	單容器部署、同步 API、零維運，WAL mode 支援並行讀寫
Tailscale	零信任網路，WireGuard 加密隧道，免設防火牆和 port forwarding
PWA (vite-plugin-pwa)	免上架 App Store，跨平台，離線快取，支援 Push Notification
Zustand	輕量 state management，per-workspace 狀態分割，boilerplate 最少
React 19 + Vite 6	生態最大、AI 產出品質最穩定、開發體驗好

使用流程

實際場景：通勤 10 分鐘完成一個 feature。

1
2
3
4
5
6


1. 手機打開 PWA → 選 workspace（左右滑動切換專案）
2. 語音或文字輸入需求：「幫 auth service 加上 rate limiting middleware」
3. AI 讀取 codebase、理解架構、寫程式碼（串流顯示進度）
4. 收到 Push 通知 → 切到 Diff tab
5. 逐檔審查 → 批准 → Commit + Push
6. 回到電腦 git pull，改動已同步

多 Workspace 的好處是可以同時丟幾個任務給不同專案的 AI，等通勤到站時一次 review。

部署方式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# docker-compose.yml
services:
 vibe-remote:
 build:
 context: .
 dockerfile: server/Dockerfile
 ports:
 - "8080:8080"
 volumes:
 - ${WORKSPACE_HOST_PATH:-/home/ubuntu}:/workspace:rw
 - vibe-data:/app/data
 - ${HOME}/.claude:/home/node/.claude:rw
 environment:
 - NODE_ENV=production
 - PORT=8080
 - JWT_SECRET=${JWT_SECRET}
 - CLAUDE_PERMISSION_MODE=bypassPermissions
 - CLAUDE_CODE_OAUTH_TOKEN=${CLAUDE_CODE_OAUTH_TOKEN}
 - WORKSPACE_HOST_PATH=${WORKSPACE_HOST_PATH:-/home/ubuntu}
 - WORKSPACE_CONTAINER_PATH=/workspace
 restart: unless-stopped

volumes:
 vibe-data:

啟動步驟：

1
2
3
4
5


git clone https://github.com/astroicers/vibe-remote.git
cd vibe-remote
cp .env.example .env
# 編輯 .env：填入 CLAUDE_CODE_OAUTH_TOKEN 和 WORKSPACE_HOST_PATH
docker compose up -d

Claude 認證有兩種方式：

OAuth Token（推薦）：claude setup-token 取得，使用 Max/Pro 訂閱額度
API Key：從 console.anthropic.com 取得，按用量付費

手機連線：確保手機和 server 都在 Tailscale 網路中，瀏覽器打開 http://<TAILSCALE_IP>:8080，Safari/Chrome「加到主畫面」安裝 PWA。

開發心得

Token 最佳化

AI 對話最大的成本是 token。Vibe Remote 做了幾層截斷：

歷史訊息：最多保留最近 5 則，每則上限 2000 字元
Context files：每個檔案上限 10,000 字元，超過 1MB 直接跳過
File tree：只展開到第 2 層，package.json 只保留套件名稱不保留版本號
Recent commits：只帶最近 3 筆

這些限制讓單次 AI 呼叫的 context 維持在合理範圍，又不會漏掉關鍵資訊。

多 Workspace 狀態隔離

所有 Zustand store 的 action 都接收明確的 workspaceId 參數，不依賴隱式全域狀態。Server 端用 Map<string, RunnerState> 以 workspaceId:conversationId 為 key 管理 runner，確保同一個 conversation 不會有兩個並行的 AI 查詢。

WebSocket 事件也帶 workspaceId，client 端依此路由到正確的 workspace partition。非當前 workspace 的完成通知會增加 unread badge + toast，不會干擾正在看的內容。

為什麼沒用 Session Resume

Claude Agent SDK 支援 persistSession / resumeSessionId 跨請求復用 conversation context，理論上可以省下大量重複的 context token。但在 Docker 環境中，session files 跨 spawned process 不穩定，最後改成 inline history（把歷史訊息截斷後直接附加到 prompt）。

等 SDK 的 session resume 在容器環境更穩定後會重新啟用。

claude on Astroicers Blog