---
name: tokeneconomizer-setup
description: 在使用者指定的 coding agent 上，為目前 repository 安裝 TokenEconomizer，並回報 status。僅在使用者明確要求安裝或檢查這個外掛時使用。
---

# 為目前 repository 裝上 TokenEconomizer

只在使用者明確要求安裝或檢查 TokenEconomizer 時使用。目標是：不改 agent 本體，用使用者既有的登入，讓這個 repository 之後的 session 少付重複成本，然後回報 status。

## 守則

- 不要改 agent 的原始碼、模型或權重。不要另申請 API key，也不要讀取、複製或寫下憑證。
- 先確認使用者要裝在哪一個 agent：Claude Code、Codex、GitHub Copilot CLI、Pi，或實驗性的 opencode。沒有指明就先問，不要猜。
- 需要 Python 3.10 或更新版本在 `PATH` 上。版本不夠就停止並回報，不要改系統 Python。
- 學習資料只應出現在本機 `~/.tokeneconomizer`。不要把這個目錄、session 紀錄或設定檔提交進 git。
- micro-skills 預設是關的。只有使用者明確要求時才打開。tool pruning 與 loop guard 維持官方預設，除非使用者要關。
- loop guard 只做 redirect，並在仍然卡住時告訴使用者怎麼自己停止。不要替使用者停掉 turn，也不要按中斷鍵。
- Pi 與 opencode 目前不做 tool pruning。不要為了啟用它去改別的 agent 設定。
- 同一步失敗或卡住兩次就停止，回報最後的指令輸出。外掛某一段失敗時，session 仍應能照常進行；不要為了裝外掛而重裝 agent。
- 安裝指令以官方 README 的 Quick start 為準：https://github.com/microsoft/TokenEconomizer 。下面只列對應入口，版本範圍與排除方式也以該頁為準。

## 流程

1. 在使用者指定、且你有權寫入的目錄 clone `https://github.com/microsoft/TokenEconomizer.git`。Claude Code、Codex、Copilot CLI、opencode 是從這份 clone 跑外掛，clone 要留在原地。marketplace 路徑用絕對路徑。
2. 依 agent 安裝，然後在目標 repository 啟動該 agent：
   - Claude Code：`claude plugin marketplace add` 該 clone，再 `claude plugin install tokeneconomizer@tokeneconomizer`。信任資料夾後執行 `/tokeneconomizer:status`。每台機器一次，以及 Claude Code 更新後，再跑 `/tokeneconomizer:toolprune refresh-catalog`。
   - Codex：`codex plugin marketplace add` 該 clone，再 `codex plugin add tokeneconomizer@tokeneconomizer`。信任資料夾與 hooks 後必須結束 session 再進一次，用 `$tokeneconomizer:status` 檢查。
   - Copilot CLI：`copilot plugin marketplace add` 該 clone，再 `copilot plugin install tokeneconomizer@tokeneconomizer`。執行 `/tokeneconomizer:status`。每台機器一次，以及 Copilot 更新後，跑 `/tokeneconomizer:toolprune refresh-catalog`。
   - Pi：`pi install git:github.com/microsoft/TokenEconomizer`，啟動後執行 `/te status`。
   - opencode：把 clone 裡的 `plugin/opencode/tokeneconomizer.ts` 以 symlink 放到 `~/.config/opencode/plugins/`。它沒有外掛指令，在 repository 裡用 `~/.tokeneconomizer/bin/te --host opencode status`。
3. status 有短狀態就視為安裝完成。用繁中回報：agent、repository、哪些機制是開的、status 裡看得到的學習摘要、學習目錄是否在 `~/.tokeneconomizer`。沒有在畫面上確認的項目不要說已經生效。