專案簡介

通勤時用手機語音或文字下指令，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 就能同步。

技術選型

使用流程

實際場景：通勤 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 在容器環境更穩定後會重新啟用。

相關連結

• GitHub: astroicers/vibe-remote
• Claude Agent SDK 文件