mikehasa/agentacct

agentacct – AIコーディングエージェントの誠実な作業レシート

何であるか – AIコーディングアシスタント（Claude Code、Codex、OpenCode、Hermesなど）がすでにあなたのマシン上に書き出しているログファイルを監視するローカルファーストのユーティリティで、これらのログをエージェントが実行した実際のコマンド、ファイル編集、ツール呼び出しと統合し、各タスクごとに1つの作業レシートを生成します。レシートには何が行われたか、いくらのコストか、そして証拠の信頼性（エージェント主張、自己確認、フック観測、CI検証）が表示されます。すべてのデータはあなたのコンピュータ上に留まり、クラウドサービス、テレメトリ、APIキーの取り扱いは一切ありません。

---

コアコンセプト

コンセプト	意味
作業レシート	タスクごとの監査スタイルの記録で、行動、コスト、各主張に対する証拠の段階をリストアップします。
証拠段階	四段階 – エージェント主張 < 自己報告の確認 < フック観測の終了コード < CI – ピップ形状で視覚化されます。
ローカルJSON API	他のスクリプトがレシートを照会できるローカルのみのHTTPサーバ（127.0.0.1:8765）。
macOSアプリ / TUI	同じレシートをレンダリングする2つのフロントエンド（ネイティブmacOS GUIとターミナルダッシュボード）。

---

あなたが得るもの

• タスクごとに1つのレシート – 行動（コマンド、編集されたファイル、使用されたツール）、コスト（実際のトークン数 + 定価表推定）、明確な意思決定/証拠の分離を表示します。
• 詳細表示 – レシートを展開して、すべてのセッションステップ、そのライフサイクル、終了コードの確認、および出典チップ（フック、トランスクリプト、MCP記録）を確認できます。
• 証拠優先のダッシュボード – 最も優先度の高いレビューが必要なタスクが強調表示され、証拠のレビューボタンと簡潔な「シフト概要」が表示されます。
• 使用状況とプランコスト – 実時間のプロバイダーキャパシティウィンドウ、記録されたトークン使用量、およびあなたの週次Claudeプランにおける推定使用割合（自身の制限履歴から導出）。
• 帰属信頼度 – 使用と作業の各結合はexact、high、medium、lowとラベル付けされます；欠落したリンクは推測せず、明示的に表示されます。
• プライバシー設計 – すべての状態は平文のローカルファイル（~/.local/state/agentacct/ またはリポジトリローカルの.agent-sentinel/）に保存され、ネットワークリスナーはローカルJSON APIのみで、キーは一切保存も送信もされません。

---

インストール

プラットフォーム	手順
macOS (GUI)	最新リリースから署名済みの.dmgをダウンロードし、Applicationsにドラッグして起動します。アプリはCLIをバンドルし、エージェントの自動オンボーディングを実行します。
macOS / Linux (CLI)	```bash
pipx install agentacct # または uv tool install agentacct
agentacct onboard # エージェントを検出、グローバルストアを作成、同期とAPIを開始
agentacct tui # 実時間のターミナルダッシュボード

| **Windows** | WSLを使用し、macOS/Linux CLI手順に従ってください。 |

*オンボーディング*はリポジトリ内にファイルを一切書き込みません。グローバルストアを作成し、エージェントの設定ファイルにフックを登録するのみで、将来のセッションをキャプチャします。

---
### 一般的なワークフロー
1. **オンボーディング** – マシン1台につき1回（`--scope project`でプロジェクトごとにも可能）。
2. 通常のAIコーディングエージェント（Claude Code、Codexなど）を実行します。エージェントの独自のログフックがセッションファイルを書き出します。
3. `agentacct tui`（またはmacOSアプリを開く） – ダッシュボードはレビューが必要な優先度の高いタスクを表示します。
4. レシートに**Enter**を押すと、完全な監査記録を表示し、セッション/ステップに詳細に掘り下げ、各主張の証拠段階を確認できます。
5. プログラム的なアクセスが必要な場合、`http://127.0.0.1:8765/receipts`（または`docs/reference.md`に記載された類似エンドポイント）を照会してください。
6. 終了後、`agentacct stop`でバックグラウンド同期を停止し、READMEに示されたコマンドでアンインストールします。

---
### 動作原理（概要）
- **使用状態の真実** – 各エージェントのローカルセッションファイルから直接取得（トークン数は`client_reported`；コストは組み込みの価格表から導出）。
- **作業の意味** – エージェントが発行するMCPイベント（`agentacct_record_section`、`agentacct_record_machine_check`）から収集し、テスト実行やCIなどの独立した確認も含む。
- **結合** – クライアントID、セッションID、トランスクリプトIDをマッチさせることでレシートを構築し、各帰属に信頼度レベルをラベル付けする。
- **証拠段階ピップ** – 基盤となる確認の独立性のグレードから導かれる視覚的インジケータ。

---
### どの人に向いているか
- AIコーディングアシスタントに頼り、**コスト管理**と**信頼性の検証**のための**監査trail**を求める開発者。
- AI生成変更が実際に実行され、テストを通過したことを**証明**する必要があるチーム。
- **プライバシー**に懸念があり、SaaSダッシュボードにデータを送信せずに完全にローカルでトークン使用状況を確認したい人。

---
### 現在の状態
- 初期アルファ版 – 機能は変更される可能性があります。
- Claude Code、Codex、OpenCode（完全なレシート）、Hermes（使用状況＋限定キャプチャ）、OpenClaw（使用状況のみ）、Cursor（存在のみ）をサポート。
- macOS GUIとフルターミナルTUIは動作可能；LinuxユーザーはTUIを利用可能。

---
### リンクとドキュメント（リポジトリに記載）
- **リファレンス** – `docs/reference.md`
- **インストール手順書** – `INSTALL.md`
- **使用状況とコストの真実テーブル** – `docs/usage-truth-table.md`
- **アーキテクチャとセーフティ** – `docs/architecture.md`、`docs/safety-boundaries.md`
- **フルデモ** – `docs/full-demo.md`

---
### クイックスタート例
```bash
# CLIのインストール
pipx install agentacct

# グローバルストアのセットアップとバックグラウンド同期の開始
agentacct onboard

# ターミナルUIの起動
agentacct tui

これで、任意のリポジトリでClaude Codeセッションを実行すると、ダッシュボードが即座に新しいタスクのレシートを表示します。

---

結論：agentacctは、AIコーディングエージェントが実際に何をしたか、いくらのコストが掛かったか、そして証拠がどれほど信頼できるかを、クラウド側のコンポーネントなしに、透明かつローカルに保存された台帳として提供します。