【2026 最新】Claude Code 狀態燈教學：怎麼看懂誰在等你？從軟體面板到 USB 燈

你把 Claude Code 留在另一個視窗跑任務，過一會又切回去：它還在工作，還是在等你按允許？這篇Claude Code 狀態燈教學，帶你先用 VibeSignal 終端面板看懂事件，再決定是否接 USB 燈。

本文寫給第一次接觸 Hooks 的讀者。你會學會分辨 Session、檢查設定、安排兩個工作階段的驗收，以及安全移除整套通知。先準備已能正常使用的 Claude Code 與 Python 3.11 以上環境；不必先買燈。

截至 2026 年 10 月 25 日，本文固定對照 VibeSignal 0.1.2 與 Claude Code 官方 Hooks 文件。AlphaLab 用該版套件做了合成事件、狀態過期及設定合併測試；未執行真實 Claude 任務、Tk 視窗或 USB 硬體驗證，後面的雙 Session 與拔插步驟是你的驗收清單。

先說結論：Claude Code 狀態燈教學先記住這個等式

狀態燈＝事件收據＋每個 Session 的狀態＋優先序＋顯示器。它像餐廳叫號牌：幫你知道哪一桌需要服務，餐點是否做對，仍要看原始工作成果。

• 先用 vibesignal watch 看每列狀態，確認哪個 Session 需要你。
• 先讀狀態名稱再讀顏色：目前 README、終端與 USB 配色並非完全一致。
• 看到 done 就回原視窗查結果；預設 API 錯誤結束也會進入這個狀態。

一、四個零件：Hook 是門鈴，面板是叫號牌

Hook（事件掛鉤）是軟體遇到特定時刻就啟動的動作；Session（工作階段）則是一次對話的識別單位。依 官方事件格式，命令會從標準輸入收到 JSON，其中的 session_id 讓 VibeSignal 把多個對話分開，cwd 則可提供專案名稱。白話說，每張收據要寫桌號，才不會把 A 的結束蓋掉 B 的等待。

• 事件：送出問題記成 working；成功使用工具後也更新工作中。
• 狀態盒：每個 agent／session 一份 JSON，預設放在 ~/.vibesignal/sessions。
• 排序員：依 blocked > error > done > working > idle 挑出最需要注意的一個。
• 顯示器：終端 watch、Tk 浮動 widget 與 USB 燈使用同一狀態來源，但外觀不同。

這篇做的是通知整合；若你想先學格式化、測試與危險操作閘門，可讀 Claude Code Hooks 教學。通知事件與執行批准是不同責任，不要為了亮燈改鬆原本的權限。

二、Claude Code 狀態燈教學：先裝軟體，再看兩列訊號

① 找得到執行檔嗎？先固定環境

打開終端機，先跑 python3 --version；Windows 通常用 py --version。版本需達 3.11。以下是 macOS／Linux 的獨立環境做法，避免改動其他專案套件；虛擬環境只是給這個工具一個專用抽屜。

python3 -m venv ~/.venvs/vibesignal

source ~/.venvs/vibesignal/bin/activate

python -m pip install "vibesignal==0.1.2"

Windows PowerShell 可依序用 py -m venv "$env:USERPROFILE\.venvs\vibesignal"、& "$env:USERPROFILE\.venvs\vibesignal\Scripts\Activate.ps1"，再跑同一行安裝命令。若系統限制啟動腳本，改用該環境的 Scripts\python.exe -m pip 與 Scripts\vibesignal.exe 完整路徑，不要直接降低全機執行政策。

用 python -m pip show vibesignal 核對 0.1.2，再執行 vibesignal --help。macOS／Linux 用 command -v vibesignal，PowerShell 用 (Get-Command vibesignal).Source 記下位置。先讓安裝與執行指向同一個抽屜。

② 沒買燈怎麼知道有動？先造兩張測試收據

保持這個環境啟用，逐行執行以下三個命令。它們是合成 Session，會寫入 VibeSignal 測試狀態，也可能改變已連接 USB 燈的顏色；不會替 Claude 開始任務。每次測試都明寫 Session，避免落進共用的 default。

vibesignal event --agent claude --session tutorial-A --project tutorial-A --state working

vibesignal event --agent claude --session tutorial-B --project tutorial-B --state blocked

vibesignal event --agent claude --session tutorial-A --project tutorial-A --state done

vibesignal status

vibesignal watch --once

預期聚合仍是 blocked，面板 B 排在 A 上方。AlphaLab 在隔離狀態目錄得到的原始面板輸出如下；圖片把真實文字輸出排成可閱讀的視圖，並非兩個真實 Claude 任務截圖。

再跑 vibesignal clear --session tutorial-B，若沒有其他有效 Session、且 A 的 done 尚未超過 90 秒，預期剩下 A 的 done；否則依仍有效的列重新計算；接著 vibesignal clear --session tutorial-A 清掉練習資料。vibesignal watch 會持續更新，按 Ctrl+C 結束查看。

③ 想浮在桌面上？先確認 Tk

在同一環境跑 python -m tkinter，能開測試視窗才繼續 vibesignal widget。若出現 No module named _tkinter，先用終端 watch；需要浮窗時，再按該 Python 發行版的方式補齊 Tk。macOS 的 vibesignal[macos]==0.1.2 額外套件改善原生視窗定位，不等於安裝 Tk。本次環境缺少 Tk，因此沒有浮窗測試成績。

三、接入真實 Hooks：先備份，再核對六種事件

痛點是已有自己的設定，怕安裝器整份蓋掉。解法是備份＋合併＋讀回：先複製 ~/.claude/settings.json 到自己命名的備份檔；Windows 對應使用者資料夾內的 .claude\settings.json。檔案不存在就記錄「原本不存在」，不要建立空白 JSON 去覆蓋既有內容。

Windows 要多做一項前置檢查：這版安裝器替 Claude 產生 POSIX shell 引號。請先確認 Claude Code 可用 Git Bash，再沿用此接法；缺少 Git Bash 時，現行 Claude 可能改用 PowerShell，不能把這份引號配置直接當作可用。先依 官方 Windows Hook 排錯準備 Git Bash 或另做 exec-form 轉換與測試；尚未確認就停在軟體合成事件練習，不啟用整合。

vibesignal install-hooks

依 0.1.2 安裝器，它把指令的絕對路徑合併進使用者設定。AlphaLab 用含既有 Stop Hook 與 permissions 的測試檔檢查，安裝、卸載後原設定保留；這項結果只證明該 fixture，仍請讀回自己的設定，確認原有 Handler 和 permissions 還在。換虛擬環境後要重新核對路徑。

新開 Claude Code Session，輸入 /hooks 檢查生效項目，並用 claude --version 留下版本。2026 年 10 月 24 日可查的官方 v2.1.310 發行說明含 Windows permission hooks 修正；不同版本與介面要分開驗收。

• UserPromptSubmit、PostToolUse → working。
• Notification 的 permission_prompt → blocked。
• Stop、StopFailure、Notification 的 idle_prompt → done。
• SessionEnd → 移除這個 Session。

這是 預設事件對照，不要把其他 Agent 的 PermissionRequest 設定直接搬來冒充同一份配置。Claude 官方 Notification 文件說明，終端 permission 通知通常約六秒後才觸發，打字會延後；它也不是涵蓋所有詢問視窗的通用偵測器。

done 的意思是「回去查看」，不是驗收成功。 Stop 官方定義是主 Agent 結束回覆；而這份預設配置把 API 錯誤的 StopFailure 也放進 done。要判斷測試是否通過、檔案是否正確，請回原視窗看錯誤、測試紀錄與交付物。

設定讀回時，另外檢查三件事：命令只有你剛安裝的執行檔與固定參數；沒有把事件 JSON 送到不認識的網址；也沒有順手變更 permissions。官方安全說明指出 command Hook 使用你的帳號權限執行，因此來源與路徑本身就是要審查的程式。VibeSignal 的狀態檔保留 agent、Session、專案標籤與時間等中繼資料；不要把整份設定或事件輸入貼到公開討論區。

四、雙 Session 驗收：A 結束，不能蓋掉 B 的等待

開兩個不含私密資料的練習資料夾，各開一個 Claude Code Session。A 請它讀一段普通文字再摘要；B 使用你現有權限會要求確認、且可逆的練習操作，停在批准畫面。不要為測燈去執行刪檔、付款或公開發布。

• B 等待：暫時不回答，等 Notification；用面板查看 B 的專案與狀態，記下提示和變更時間。
• A 結束：讓 A 完成一輪回覆；預期 B 仍在前面，聚合維持 blocked。
• B 繼續：先在原視窗讀清楚操作，再自行批准；成功工具事件應把 B 更新成 working。若拒絕或中斷，觀察後續實際事件，不預填結果。
• 正常關閉：結束 B 的 Session，檢查對應列是否清除；另用強制中斷情境看有無殘留。

用紙或試算表記「Session ID、操作、預期狀態、實際狀態、時間、是否清除」。若兩個真 Session 擠成一列，查命令是否取得 stdin JSON、是否被 wrapper 吃掉，及環境路徑是否仍正確；不要只改燈的顏色掩蓋問題。

TTL（存活期限）像收據的有效日期。0.1.2 resolver給 done 90 秒、working 靜默 600 秒、blocked／error 28,800 秒；AlphaLab 用指定時間驗證了期限前後的解析結果，並未真的等待八小時。長時間靜默的有效任務也可能被視為過期，所以列消失本身不能證明程序已關閉。

軟體過期與實體熄燈要分開測。watch／widget 會重新讀狀態；USB 寫入則由 event、clear、end 等動作驅動。0.1.2 的 viewer 不會替 USB 定時重畫，因此不要承諾燈一定在第 90 秒自動熄滅。

五、再接 USB 燈：先比型號，別照抄網友的配色

一則 使用者的 Kuando 工作流分享展示了紅燈工作／等待、綠燈閒置；那是他的設定，並不是 VibeSignal 的預設。購買前先查 busylight-core 的硬體清單，分清「底層函式庫列出型號」與「短命令退出後仍能維持狀態」。

blink(1) mk2 在底層支援清單中；原廠 FAQ也說明同時只能由一個程式存取，接 VibeSignal 前先關閉會占用裝置的控制程式。Luxafor 清單列 Flag，VibeSignal README 推薦 Flag 2；買之前核對確切世代與 USB 識別，不把家族名稱視為所有版本保證。Kuando Alpha／Omega 雖被底層列出，VibeSignal 作者另提醒這類燈需要持續連線，與短命令設計不同；本教學先用軟體面板，不提供未驗證的常駐服務接線。

截至 2026 年 10 月 25 日，底層套件的 平台說明要求 Linux 準備 USB 存取的 udev 規則，Windows 硬體路徑則標示為未測試。軟體面板可用與 USB 可控要分開驗收；Windows 先完成面板與 Hooks，硬體通過自己的測試再納入日常工作。

接好一盞燈後，先送具名 working、blocked、done 測試事件，再讀 status。0.1.2 原始碼的 USB 目標色依序為綠、紅、藍，手動 error 是紫；README 的琥珀 blocked、紅 error 與它不同，終端 blocked 又用黃色。以狀態字與你的實際裝置輸出對照，不靠顏色猜。

接著做三個檢查：拔除後送事件，確認軟體仍記錄；插回後先執行 vibesignal off，再重送一個具名事件；最後清除測試 Session。重插可能遇到「上次顏色快取相同」而略過寫入，單跑 status 只讀資料，不會強制重設燈。off 會清掉所有 Session，請安排在自己的測試時段，避免清走其他工作提醒。

硬體驗收先固定一盞、同一條資料線與同一個 USB 埠，逐項寫下「短命令退出後是否保色、閒置後是否改變、重插後是否恢復、是否被其他控制軟體搶走」。每次只改一個條件；若面板正確而燈不對，先查裝置層，若面板的 Session 就錯了，先查事件層。這能把故障範圍縮到一層，而不是反覆重裝所有工具。

六、常見問題：八個容易讀錯的訊號

亮藍燈表示任務成功？

不能這樣判斷。預設 StopFailure 也會記成 done；請在原視窗驗收。

等待批准會立刻變色？

不一定。這份設定走 Notification 的 permission_prompt，有延遲條件；用實際提示時間對照。

四個 Session 能各占一顆燈？

本文配置顯示聚合狀態。0.1.2 的硬體 wrapper 選第一盞可用燈；找哪個 Session 請看面板，逐 Session 配燈需要另外整合。

關掉 watch 就停止 Hooks？

不會。viewer 和事件命令分開；關閉面板後，已裝的 Hook 仍可寫入狀態。

要開機自動顯示嗎？

先手動驗收。macOS／Windows 需要時才用 install-launcher、install-autostart；後者會立即啟動 widget 並加入登入啟動，先把 Tk 測通。Linux 先手動啟動 viewer，登入啟動需另按桌面環境設定。

Hooks 可以幫我自動批准？

這份配置記錄狀態與更新指示，不回傳批准決策。command Hook 以使用者權限執行，安裝前閱讀程式與設定；批准仍回原介面處理。

沒有 USB 燈，流程有用嗎？

有。watch 可以逐列顯示專案與狀態，先確認事件沒有遺漏，再決定是否添購硬體。

如何完整移除？

先移 Hooks，再關燈。執行 vibesignal uninstall-hooks，接著 vibesignal off；若曾設自動啟動或捷徑，再跑 uninstall-autostart、uninstall-launcher。關閉 viewer，核對原有 Hooks 仍在，最後才移除套件或虛擬環境。

給新手的三個重點

• 事件比顏色重要：知道 blocked 由哪個通知來，才知道覆蓋範圍。
• 每個 Session 要有桌號：先測 B 等待、A 結束的優先序，再接真任務。
• 清除也是功能：正常結束、強制關閉、TTL 與拔插都要留下可辨識結果。