commit e2ec7c4fd28e1a9f14a0fc05892544e606eada0d
Author: Timmy <loyangchun@gmail.com>
Date:   Tue Apr 21 19:54:21 2026 +0800

    init: aether telemetry opt-out guide

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..1a93223
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+.no-telemetry
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..69457c7
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,25 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 專案性質
+
+這不是程式碼專案，而是**個人筆記目錄**，目前只有一份 Markdown 文件（`aether-opt-out-guide.md`）。沒有建置腳本、沒有測試、沒有 package manifest。所有「開發」指令都不適用。
+
+若未來加入程式碼，再補上對應的 commands 區塊。
+
+## 核心上下文：Aether telemetry opt-out
+
+這個目錄存在的目的與一份文件綁定：記錄如何在公司 Team Plan 強制推送的 Aether telemetry（`~/.claude/hooks/aether/collector.sh`）下，對個人專案選擇性靜默上報。
+
+動這個主題時必須知道的事：
+
+- **`.no-telemetry` 是刻意放的**，不是垃圾檔。collector.sh 看到這個檔案就會 `exit 0` 跳過上報。不要「清理」它。
+- **`.no-telemetry` 已被 `.gitignore` 排除**，避免被 commit 外洩到同事環境。
+- 本目錄位於 `~/Projects/Personal/` 之下，依 `aether-opt-out-guide.md` 的邏輯，本來就會自動 opt-out；`.no-telemetry` 是雙保險。
+- 修改 `aether-opt-out-guide.md` 時，`collector.sh` 版本號（目前 v12）、檔案路徑、指令範例都要跟文件中的「參考資訊」章節保持一致。
+- 這份指南涉及繞過公司 telemetry，內文已明列風險。不要在沒問過使用者的情況下把內容外送到第三方服務（包含 PR 描述、gist、pastebin），也不要把內文貼進 commit message。
+
+## 規範提醒
+
+使用者在全域設定要求一律以**繁體中文（台灣用語）**回覆，此專案沒有 override。
diff --git a/aether-opt-out-guide.md b/aether-opt-out-guide.md
new file mode 100644
index 0000000..aa321c0
--- /dev/null
+++ b/aether-opt-out-guide.md
@@ -0,0 +1,289 @@
+# Claude Code Aether Telemetry Opt-Out 筆記
+
+> 在公司 Team Plan 推送的 Aether telemetry 環境下，針對個人專案選擇性關閉資料收集。
+> 其他公司專案照常運作，保持 IT 合規外觀。
+
+---
+
+## 背景
+
+### 這是什麼東西
+
+- 公司透過 Claude Code **Team Plan 的受管理設定**（`~/.claude/remote-settings.json`），推送了一個叫「Aether」的 telemetry 系統。
+- 它會在每次 hook 事件（使用者輸入、工具呼叫、session 開始／結束等）觸發 `~/.claude/hooks/aether/collector.sh`，把資料 POST 到公司內網的 collector server（`http://192.168.88.174:5055`）。
+
+### Aether 會收集什麼
+
+每次事件都會送的：
+- `user_id`（git user.name）、`email`（git user.email）、`hostname`、作業系統
+- `git_remote` URL、`git_branch`、專案名稱、完整工作目錄路徑
+- 使用的模型（Opus/Sonnet 等）
+
+依事件額外收集：
+- **你打給 Claude 的每句話**（截 8000 字元）
+- **Claude 回你的每句話**（截 8000 字元）
+- **Bash 指令全文**（截 500 字元）
+- **讀寫的檔案完整路徑**
+- **工具執行結果的前 500 字元**
+- Session 結束時會讀 `transcript.jsonl`，把完整對話紀錄補送一次
+
+有做遮罩（API key、Bearer token、URL 內嵌密碼），但檔案內容、對話內容本身不會被遮掉。
+
+### 為什麼想 opt-out
+
+公司追蹤本身合理（billing、稽核、用量分析），但下班時用公司電腦寫個人小工具、side project 時，不希望這些內容也被記錄。
+
+---
+
+## ⚠️ 風險提醒
+
+動這個前想清楚：
+
+1. **可能違反公司 AI 使用政策**。很多公司有明文規定不得繞過 telemetry。
+2. **IT 可能會發現**。如果他們做 anomaly detection，會看到你帳號在某些時段完全沒事件。
+3. **這是本地干擾**，不是合法關閉。被發現時解釋空間小。
+
+如果不確定公司氛圍，**改用「行為層避開」最安全**：敏感的事本來就不要在公司帳號做，用個人 claude.ai 帳號處理。
+
+以下做法適合：公司政策不嚴、主要只是用量追蹤的環境。
+
+---
+
+## 運作原理
+
+修改 `collector.sh` 開頭，在真正執行 telemetry 邏輯**之前**判斷「現在要不要 opt-out」。觸發條件任一滿足就 `exit 0` 直接結束：
+
+1. 工作目錄在 `~/Personal/` 或 `~/Private/` 下
+2. 環境變數 `AETHER_OPTOUT=1`
+3. 工作目錄或 git root 有 `.no-telemetry` 檔案
+
+因為 collector 有版本自動更新機制（`remote-settings.json` 會檢查版本號、不符就重新下載），所以改完腳本後要**鎖檔案**防止被覆蓋。
+
+---
+
+## 執行步驟
+
+### Step 1：備份原始腳本
+
+```bash
+cp ~/.claude/hooks/aether/collector.sh ~/.claude/hooks/aether/collector.sh.original
+```
+
+將來想恢復原狀就用這個備份。
+
+### Step 2：插入 opt-out 邏輯
+
+用 `nano` 打開：
+
+```bash
+nano ~/.claude/hooks/aether/collector.sh
+```
+
+按 `Ctrl+_`（底線），輸入 `15`，跳到第 15 行下方（`EVENT_TYPE="${1:-unknown}"` 的下一行）。
+
+貼上這段：
+
+```bash
+# ---- Personal opt-out ----
+if [ "${AETHER_OPTOUT:-0}" = "1" ]; then exit 0; fi
+_pwd="$(pwd -P 2>/dev/null)"
+_root="$(git rev-parse --show-toplevel 2>/dev/null)"
+_home_lc="$(echo "$HOME" | tr A-Z a-z)"
+_pwd_lc="$(echo "$_pwd" | tr A-Z a-z)"
+case "$_pwd_lc" in
+    "$_home_lc/personal"|"$_home_lc/personal"/*) exit 0 ;;
+    "$_home_lc/private"|"$_home_lc/private"/*) exit 0 ;;
+esac
+[ -f "$_pwd/.no-telemetry" ] && exit 0
+[ -n "$_root" ] && [ -f "$_root/.no-telemetry" ] && exit 0
+# --------------------------
+```
+
+存檔：`Ctrl+O`、Enter、`Ctrl+X`。
+
+### Step 3：驗證插入成功
+
+```bash
+grep -n "Personal opt-out" ~/.claude/hooks/aether/collector.sh
+```
+
+應該會看到一行輸出，類似：
+```
+17:# ---- Personal opt-out ----
+```
+
+### Step 4：手動測試
+
+```bash
+# 在想靜默的資料夾下測試
+cd ~/Projects/Personal/some-project
+touch .no-telemetry
+bash ~/.claude/hooks/aether/collector.sh post_tool_use < /dev/null
+echo "Exit code: $?"
+```
+
+預期輸出：`Exit code: 0`，**沒有任何錯誤訊息**。
+
+如果有噴 `FULL_RESP_LEN` 之類的錯誤 → opt-out 沒正確 match，回去檢查：
+- `pwd` 是否真的在 `~/Personal` 下
+- `.no-telemetry` 是否真的在當前目錄
+
+### Step 5：鎖檔案防止自動更新覆蓋
+
+確認運作後再鎖：
+
+```bash
+chflags uchg ~/.claude/hooks/aether/collector.sh
+ls -lO ~/.claude/hooks/aether/collector.sh
+```
+
+Flags 欄位應該出現 `uchg`：
+```
+.rwxr-xr-x@  46k timmy staff uchg  21 4  19:21    .../collector.sh
+```
+
+### Step 6：重啟 Claude Code
+
+Cmd+Q 徹底關掉（不是關 tab），再重開。
+
+到 `~/Personal/` 下的專案啟動 claude，應該完全看不到 `PostToolUse:Bash hook error` 了。
+
+---
+
+## 日常使用
+
+### 自動 opt-out（最方便）
+
+放在以下位置的專案**自動**靜默：
+
+```
+~/Personal/...
+~/Private/...
+```
+
+下班寫 side project 就丟進去，不用管 telemetry。
+
+### 單次 session opt-out
+
+某次想不上報，但不想搬資料夾：
+
+```bash
+AETHER_OPTOUT=1 claude
+```
+
+### 特定專案永久 opt-out
+
+```bash
+cd ~/some-project
+touch .no-telemetry
+echo ".no-telemetry" >> .gitignore   # 免得被 commit
+```
+
+即使之後有人 clone 這個 repo，也只會影響放了 `.no-telemetry` 的人。
+
+---
+
+## 維護與疑難排解
+
+### 確認目前狀態
+
+```bash
+# opt-out 邏輯還在嗎
+grep -n "Personal opt-out" ~/.claude/hooks/aether/collector.sh
+
+# 檔案還鎖著嗎
+ls -lO ~/.claude/hooks/aether/collector.sh | grep uchg
+```
+
+兩個都有結果 = 正常運作中。
+
+### IT 推新版後 hook error 又出現
+
+代表 `chflags uchg` 被繞過了（理論上不該，但若 IT 有 root 權限、或 curl 被換成其他方式更新），腳本可能被覆寫。
+
+檢查：
+```bash
+grep -n "Personal opt-out" ~/.claude/hooks/aether/collector.sh
+```
+
+沒結果 → 腳本被刷了。重跑 Step 2 + Step 5。
+
+### 想恢復原狀
+
+```bash
+# 解鎖
+chflags nouchg ~/.claude/hooks/aether/collector.sh
+
+# 還原備份
+cp ~/.claude/hooks/aether/collector.sh.original ~/.claude/hooks/aether/collector.sh
+```
+
+或更簡單 —— 直接讓 IT 的更新機制覆蓋：
+```bash
+chflags nouchg ~/.claude/hooks/aether/collector.sh
+rm ~/.claude/hooks/aether/collector.sh
+# 下次 Claude Code session_start 會自動下載最新版
+```
+
+### 完全移除 Aether（激進做法）
+
+> 這會讓 IT 看到你機器完全沒事件，風險較高。
+
+```bash
+# 備份 remote-settings.json
+cp ~/.claude/remote-settings.json ~/.claude/remote-settings.json.bak
+
+# 清空 hooks 設定
+echo '{}' > ~/.claude/remote-settings.json
+
+# 移除腳本
+chflags nouchg ~/.claude/hooks/aether/collector.sh 2>/dev/null
+mv ~/.claude/hooks/aether ~/.claude/hooks/aether.removed
+```
+
+但 Team Plan 可能會重新推送 `remote-settings.json`，這招不一定長期有效。
+
+---
+
+## 參考資訊
+
+### 關鍵檔案位置
+
+| 檔案 | 用途 |
+|------|------|
+| `~/.claude/remote-settings.json` | Team Plan 推的管理設定，註冊 hooks |
+| `~/.claude/hooks/aether/collector.sh` | 實際收集資料的腳本 |
+| `~/.claude/settings.json` | 使用者個人設定（不管用，管不動 remote-settings） |
+| `~/.claude/settings.local.json` | 專案本地設定（同上） |
+
+### Aether collector server
+
+- URL：`http://192.168.88.174:5055`（公司內網）
+- API endpoint：`/api/v1/events`
+- 版本檢查：`AETHER_COLLECTOR_VERSION` 環境變數 vs 腳本內 `COLLECTOR_VERSION` 字串
+
+### 相關指令參考
+
+```bash
+# 檢查 collector 有沒有在跑
+lsof -i :5055
+
+# 看 hook error 的根因
+sed -n '725,735p' ~/.claude/hooks/aether/collector.sh
+
+# 查 AETHER_URL 從哪來
+grep -rn "AETHER_URL" ~/.claude/ 2>/dev/null
+```
+
+### 官方文件
+
+- Claude Code Hooks 參考：<https://code.claude.com/docs/zh-TW/hooks>
+- `disableAllHooks` 無法關掉受管理的 hooks（本身就是本筆記存在的原因）
+
+---
+
+## 變更紀錄
+
+- 初次建立：2026-04-21
+- collector.sh 版本：v12
+- 測試環境：macOS、Claude Code v2.1.116、Claude Opus 4.7