mikehasa/agentacct

agentacct – 為您的程式碼代理程式提供誠實的工作收據

內容為何 – 一款優先考慮本地端的工具，它會監控 AI 程式碼助手（Claude Code, Codex, OpenCode, Hermes 等）已在您的機器上寫入的日誌檔案，將這些日誌與代理程式執行的實際指令、檔案編輯和工具呼叫結合起來，並為每個任務產生單一的 工作收據。該收據會顯示 做了什麼、花費了多少 以及 證據的可信度有多高（代理程式聲稱、自我檢查、hook 觀察、CI 驗證）。所有數據都保留在您的電腦上；沒有雲端服務、遙測或 API-key 處理。

---

核心概念

Concept	Meaning
Work Receipt	一個針對每個任務的稽核風格記錄，列出動作、成本和每個聲稱的證據等級。
Evidence tiers	四個等級 – agent claim < self-reported check < hook-observed exit code < CI – 以 pip 形狀視覺化。
Local JSON API	一個僅限回環的 HTTP 伺服器 (127.0.0.1:8765)，其他腳本可以查詢收據。
macOS app / TUI	兩個前端（原生 macOS GUI 和終端機儀表板）來渲染相同的收據。

---

您可以獲得什麼

• 每個任務一份收據 – 顯示動作（指令、觸及的檔案、使用的工具）、成本（實際 token count + 價格表估算）以及清晰的決策/證據拆分。
• 鑽研細節視圖 – 展開收據以查看每個工作階段的步驟、其生命週期、exit-code 檢查和來源標籤（hook, transcript, MCP record）。
• 證據優先儀表板 – 最頂層需要審查的任務會被高亮顯示，並帶有 Review evidence 按鈕和簡潔的 “Shift Brief”。
• 使用量與方案成本 – 即時的供應商配額視窗、記錄的 token 使用量，以及您每週 Claude 方案的估算份額（根據您自己的限制歷史記錄）。
• 歸屬可信度 – 每個使用量與工作的結合點都被標記為 exact, high, medium 或 low；缺失的連結會被明確顯示而非猜測。
• 隱私設計 – 所有狀態都存在於純本地檔案 (~/.local/state/agentacct/ 或 repo-local .agent-sentinel/)，唯一的網路監聽器是本地 JSON API，且從不儲存或傳輸任何金鑰。

---

安裝

Platform	Steps
macOS (GUI)	從最新版本下載經過公證的 .dmg，拖入 Applications，啟動。該應用程式內含 CLI 和自動為您的代理程式進行 onboarding。
macOS / Linux (CLI)	```bash
pipx install agentacct # or uv tool install agentacct
agentacct onboard # detects agents, creates global store, starts sync & API
agentacct tui # live terminal dashboard

| **Windows** | 使用 WSL 並遵循 macOS/Linux CLI 步驟。 |

*Onboarding* 不會在您的 repo 中寫入任何檔案，僅會建立一個全域儲存區並在代理程式的設定檔中註冊 hooks，以便捕捉未來的 session 進行記錄。

---
### 典型工作流程
1. **Onboard** 機器一次（或使用 `--scope project` 針對每個專案）。
2. 執行您常用的 AI 程式碼助手（Claude Code, Codex 等）。代理程式本身的 logging hooks 會寫入 session 檔案。
3. `agentacct tui` (或開啟 macOS app) – 儀表板會顯示最高優先級的任務，需要進行審查。
4. 按下收據上的 **Enter** 以查看完整的稽核記錄，深入研究 session/步驟，並檢查每個聲稱的證據等級。
5. 如果您需要程式化存取，請查詢 `http://127.0.0.1:8765/receipts` (或 `docs/reference.md` 中記載的類似端點)。
6. 當結束時，使用 `agentacct stop` 停止背景同步；使用 README 中顯示的指令來解除安裝。

---
### 運作原理 (高層級)
- **Usage truth** – 直接從每個代理程式的本地 session 檔案中提取（token counts 是 `client_reported`；成本是從內建的價格表推導出的）。
- **Work meaning** – 從代理程式發出的 MCP events (`agentacct_record_section`, `agentacct_record_machine_check`) 加上任何獨立檢查（測試執行、CI）中收集。
- **Join** | 結合點 – 收據是透過匹配 client IDs, session IDs 和 transcript IDs 來建立的，然後為每個歸屬標記一個可信度等級。
- **Evidence tier pip** | 證據等級 pip – 視覺化指標，源自於底層檢查的獨立性等級。

---
### 誰應該使用它
- 依賴 AI 程式碼助手並希望透過成本控制和信任驗證來獲得 **audit trail** (稽核軌跡) 的開發人員。
- 需要 **證明** AI 生成的變更在合併之前確實已執行並通過測試的團隊。
- 任何關心 **隱私** 並希望在不將數據傳送到 SaaS 儀表板的情況下，獲得完全本地化的 token 使用量視圖。

---
### 目前狀態
- 早期 alpha – 功能可能會變動。
- 支持 Claude Code, Codex, OpenCode (完整收據), Hermes (使用量 + 有限捕捉), OpenClaw (usage only), Cursor (presence only)。
- macOS GUI 和完整的終端機 TUI 是可用的；Linux 用戶則使用 TUI。

---
### 連結 & docs (如 repo 中所列)
- **Reference** – `docs/reference.md` 
- **Install run-book** – `INSTALL.md` 
- **Usage & cost truth table** – `docs/usage-truth-table.md` 
- **Architecture & safety** – `docs/architecture.md`, `docs/safety-boundaries.md` 
- **Full demo** – `docs/full-demo.md` 

---
### 快速開始範例
```bash
# Install the CLI
pipx install agentacct

# Set up the global store and start background sync
agentacct onboard

#agentacct tui

現在在任何 repo 中執行一個 Claude Code session；儀表板會立即列出新任務的收據。

---

Bottom line: agentacct 為您提供一個透明、本地儲存的分類帳，記錄了您的 AI 程式碼代理程式實際做了什麼、花費了多少，以及證據的可靠性有多高——且不含任何雲端組件。