Skip to content

About

Drive Claude Code on your own PC from an Android phone. Streaming chat, calendar/alarms/ledger, file transfer, voice, swappable persona files.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

7 Commits

Folders and files

Repository files navigation

butler-kit

從手機驅動你自己電腦上的 Claude Code。一個 Android App 加一支本機服務, 連線走你自己的網路,中間沒有第三方。

不是聊天機器人的殼。你在手機上打一句「電腦好卡」,它會去看記憶體與行程佔用, 然後回報數字並問你要關哪個——CC 在你電腦上有的能力,它全都有。

有什麼

  • 對話 — SSE 串流,逐字顯示思考與回覆;工具軌跡多到會蓋掉回覆時自動收成 一行摘要,點開才看明細
  • 多對話 — 助理一條、工作多條,各自獨立的 CC session,接得回歷史; 往上捲到頂會自己往前翻一頁,翻完不會把你彈回底部。助理那條每天換一段新的 session(不然會越接越肥、越跑越慢),畫面上照樣接得到之前的,中間畫一條分隔線
  • 選項按鈕 — 助理要你做決定時,手機上跳出按鈕直接點
  • 模型選單跟著官方走 — 清單向官方的 /v1/models 要(用 Claude Code 自己的登入), 新模型發佈當天就出現,不必回來改程式碼。太新的模型這版 Claude Code 跑不動時, 選單會把它灰掉;到工具頁按一下就能把 Claude Code(SDK)更新到最新版
  • 額度用完會自己接回去 — 撞到 rate limit 時,若回復時間在六小時內, 訊息留在佇列裡等額度回來自動重跑;更久的才叫你自己決定
  • 行事曆/鬧鐘/記帳/課表 — 你隨口說「明天十點看牙醫」它就開行程; 鬧鐘會在手機上真的響
  • 傳檔雙向 — 電腦端做出來的圖直接推到手機;手機上的截圖丟給它看。 附件在對話裡畫成縮圖或檔案卡,不是一串電腦路徑——路徑只有模型看得到
  • 算式、圖表、圖片 — 回覆裡的 $E = mc^2$ 會畫成真正的數學式(上下標、 分數、根號、向量、希臘字母),一段 ```chart 區塊會變成折線/長條/散佈圖, ![說明](網址) 直接顯示圖片。沒引任何函式庫,字型與配色跟著主題走
  • 語音 — 語音輸入、朗讀、面對面即時翻譯(離線可用)
  • 課程頁(選配) — 一門課一條對話、一個資料夾:提問紀錄、理解程度、 講義教材都在裡面,課表格子點下去就進那門課的工作區。預設關閉, 見下面的「課程頁」
  • 看板 — 工作看板,助理自己開卡換欄;手機上一屏一欄、用明確按鈕換欄
  • 位置 — 手機背景定期回報位置,助理要用時直接讀快取;只留最新一筆,不存軌跡
  • 服務控制台 — 在手機上看服務狀態(跑多久、哪一版),一鍵重啟
  • 用量 — token 消耗與訂閱方案剩餘額度
  • 人格 — 純文字檔,改語氣不必碰程式碼;每種對話掛哪一份人格與哪些工具 由 engine/profiles.py 的前綴註冊表決定,接第三個前端只要多註冊一條
  • 深色模式 — 跟隨系統,色票在 Theme.kt 裡淺深各一份
  • App 內更新 — 重編出新的 APK,用傳檔工具推到手機,Wi-Fi 下 App 自己抓好, 按一下就裝。第一次會要你在系統設定開一次「允許安裝未知應用程式」

開始

整包丟給你自己的 Claude Code,叫它讀 AGENTS.md——那份是寫給它看的, 從裝相依到編 APK 到配對都在裡面,連踩過的坑一起。

要自己動手的話:docs/manual-setup.md。

⚠️ 先知道你在裝什麼

這東西給手機端一台電腦的完整控制權。

引擎跑在 bypassPermissions 下——刪檔、跑 PowerShell、讀任何檔案都不會問你。 這是刻意的:你人在外面,不可能一直點確認。代價是 device token 外流等於電腦被接管。

服務永遠不綁 0.0.0.0,設了會直接拒絕啟動,這條沒有開關。要綁哪裡由 BUTLER_BIND 決定(走通道就填 127.0.0.1);什麼都不設時它會自己找 tailnet 位址,找不到也是拒絕啟動——不會「退而求其次」綁到別的地方去。

外觀要自己設計

附的外觀是佔位用的。 白底灰字、吉祥物的位置上只有一顆會依狀態變色的點—— 能跑、看得懂,但毫無個性。原封不動編出去,你的 App 會跟每一支沒改過的 butler-kit 長得一模一樣。

要改的東西集中在兩個檔,改完不會波及其他四十幾個:

  • app/.../ui/Theme.kt — 色票、圓角、字級、預設字型,改它全 App 跟著變。 淺色深色各一份(LightColors / DarkColors),畫面一律讀 Palette.*, 所以換色票不必碰任何一個引用點。深色不是把淺色反過來——底不要用純黑、 強調色要提亮一階,那個檔的註解寫了理由
  • app/.../ui/PetBot.kt — 吉祥物。整支換掉都行,只要保住 PetMood 七個狀態 與 PetFace() 的簽名

兩個檔的檔頭註解都寫了怎麼改、有哪些坑。想找靈感的話,ui-ux-pro-max 這個 Claude Code skill(開源,內含 49 種 UI 風格與色彩字型資料庫)可以先產幾個 方向的預覽,挑一個再套進 Theme.kt。

一句提醒:中文襯線字的取得方式見 ui/SerifProbe.kt 的註解—— FontFamily.Serif 對中文是無效的,要直接載系統的 NotoSerifCJK。

課程頁(選配)

這一頁預設不會出現。它要的不只是程式碼,還要你照一個約定擺資料夾:

<課程目錄>/<課名>/
    index.md   課程資訊與理解進度表
    log.md     提問流水帳
    raw/       講義、投影片、拍到的板書
    notes/     整理過的筆記
    對話/      對話原文

開啟方式二選一:

  • 把課程目錄建出來(預設 ~/courses),或
  • 設 BUTLER_COURSES_DIR 指到你要的位置

想明確關掉就設 BUTLER_COURSES=0。伺服器啟動時決定,改完要重啟服務; App 會問伺服器一次,沒開就不顯示那一格——不是點進去看到空白。

開了之後,每門課是一條 course:<資料夾名> 的對話,套的是 personas/course.txt 的人格加上那門課的資料夾路徑。它會把你問過的問題 追加到 log.md,你說「整理一下」的時候再收斂進 index.md 的進度表。 課程對話每週換一段新的 session——紀錄在資料夾裡,不靠 session 記。

資料夾不用自己建。 課表上的每門課,伺服器都會在課程目錄底下開好資料夾 (課名推出資料夾名,「通識:生活中的天文學」→「生活中的天文學」),並把對到的 資料夾名寫回課表;你手動建好、名字對得上的,它會直接認領。只建不刪。

換學期在課程頁最底下:這學期的資料夾與課表整批搬進 <課程目錄>/_封存/<學期>/ (紀錄一筆都不刪),課程對話一起收起來、課表清空。有課程對話還在跑時會擋下; 有別的程式開著某個課程資料夾(例如拿它當工作目錄)時搬不動,會整批退回並說是哪一個。

課表本身不需要這個功能——那在日常頁,一直都在。課程頁多出來的是 「點一堂課進去跟它討論那門課」。

怎麼組起來的

電腦端分成三層,手機 App 只碰最外面那層:

層 位置 管什麼
engine/ 引擎 回合、session、工具、人格、狀態。不認識 HTTP
protocol/ 介面 事件格式與 Frontend 這個抽象前端
transport/ 前端 FastAPI:SSE、REST、驗證、檔案

分這一刀是為了讓 engine 能被第二個前端接上(另一支 bot、一支 CLI、一個網頁殼), 不必把回合邏輯抄一份。落實這件事的是三個檔:

  • engine/worker.py — 一條對話一個工作者:排隊、合併、插話、停止、 助理自己醒來的回合、限流自動續跑。做成類別而不是模組全域,兩個前端可以各持一份
  • engine/ports.py — engine 需要外界做的事(推播、要位置、送檔案、資料變了) 收成一個必填的 dataclass。少接一條會在啟動時 TypeError,而不是上線後靜默不動
  • engine/profiles.py — 哪條對話用哪份人格與哪些工具,用 conv_id 前綴註冊, 最長前綴優先。接自己的前端就多註冊一條,不必改 engine

需要

  • Windows / macOS / Linux 上的 Python 3.11+,以及已登入的 Claude Code CLI
  • Android 8.0 以上的手機
  • JDK 17+ 與 Android SDK(編 APK 用)
  • Tailscale(預設的連線方式,其他選法見 docs/transport.md)

文件

AGENTS.md 給 AI 助理的部署指南
docs/transport.md 五種連線方式的優缺與選法
docs/persona.md 怎麼寫人格,以及會把它寫壞的幾種方式
docs/manual-setup.md 純人工部署

授權

MIT。

app/app/src/main/assets/opencc/ 底下的簡繁字典來自 OpenCC,以 Apache License 2.0 授權, 未經修改。歸屬說明見 NOTICE,授權全文見 licenses/Apache-2.0.txt。

About

Drive Claude Code on your own PC from an Android phone. Streaming chat, calendar/alarms/ledger, file transfer, voice, swappable persona files.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages