@promptkaizen/agent

PromptKaizen のローカル常駐エージェント。~/.claude/projects/*.jsonl を監視し、 差分パース・PII マスキング後に ローカル SQLite(FTS5) へ保存 し、 トークン設定時のみ PromptKaizen Cloud へ送信する (未設定なら完全ローカル動作)。 ローカル DB にも生 PII / 生機密は残さない。詳細は docs/local-store.md。

なぜローカルエージェントなのか

Phase 0 初期実装で proxy 方式（リバースプロキシ経由で Anthropic API を中継）を試したが、 ユーザーが Anthropic Max プラン契約済みの場合、proxy 経由で使うと API 従量課金が 追加で発生する二重課金問題があり、個人開発者層には経済合理性がない。

ローカルエージェント方式 (Bプラン) なら:

• Claude Code は Max プラン直結のまま使い続けられる (追加課金ゼロ)
• 観測データだけクラウドに送信
• Anthropic 利用規約的にもクリーン（OAuth トークン中継なし）
• 観測遅延は 30秒〜数分（事後分析用途には十分）

詳細は ../proxy/README.md の凍結ノートと docs/architecture.md（追って整備）を参照。

ステータス

✅ Phase A〜G 完了。SAKAMA 内本格運用 (Phase H) 開始可能。

実装フェーズ:

• [x] Phase A: proxy 凍結 + agent/ サブディレクトリ初期化
• [x] Phase B: Claude Code ログ構造調査
• [x] Phase C: PoC エージェント実装 (watcher / parser / offset-store)
• [x] Phase D: PII マスキング実装
• [x] Phase E: クラウド側受信 API (Cloud Functions + Firestore)
• [x] Phase F: ダッシュボード MVP (/settings 設定 + /events 観測一覧 + 詳細 + 集計グラフ)
• [x] Phase G: 配布パッケージング (CLI + macOS launchd + シェルスクリプト一発インストーラ)
• [ ] Phase H: SAKAMA 内本格運用検証 (6 週間)

インストール (Mac, ワンショット)

前提: Node.js 20+。nvm install 20 && nvm use 20。

git clone https://github.com/SAKAMA-INC/promptkaizen-mvp.git
cd promptkaizen-mvp
./scripts/install-agent.sh

apiKey は dashboard /settings のセットアップガイドから 1 度発行してコピー。 スクリプトの中で promptkaizen-agent init が起動し apiKey をペーストすると ~/.promptkaizen/agent.config.json が生成され、macOS launchd に登録されて 自動起動 + 落ちても自動再起動するようになります。

完全非対話モード (CI / dotfiles 用):

PK_API_KEY=pk_xxxxx PK_ENV=stg ./scripts/install-agent.sh

環境変数:

| 変数 | デフォルト | 用途 | |---|---|---| | PK_API_KEY | (空) | 設定すると init を非対話で実行 | | PK_ENV | stg | stg / prod / custom | | PK_NO_LAUNCHD | 0 | 1 で launchd 登録をスキップ (foreground 運用) |

CLI コマンド

npm link 後、グローバルに promptkaizen-agent コマンドが入ります。

| サブコマンド | 用途 | |---|---| | init | 対話 or --api-key K --env stg --yes で config.json 生成 | | detect | 解析対象 (Claude Code / Codex / Gemini) を自動検出して表示。--write で検出した watchPaths を既存 config に非破壊反映 (apiKey 等は保全)、--json で機械可読 | | start | foreground 起動 (launchd が裏で叩いているのと同じ) | | status | config / plist / プロセス / offsets / endpoint の診断 |

起動時に検出した解析対象が watchPaths に無ければ、start が自動で追記して監視します (セルフヒール)。 agent を更新して新ツール対応が入った場合もユーザー操作なしで watched になります。 無効化するには config の agent.autoDetectWatchPaths を false に設定します。 | install-launchd | [macOS] launchd に登録 (自動起動 + 落ちたら再起動) | | uninstall-launchd | [macOS] launchd 登録を解除 (config/offsets は残す) | | install-systemd | [Linux] systemd user unit に登録 (自動起動 + 落ちたら再起動) | | uninstall-systemd | [Linux] systemd 登録を解除 (config/offsets は残す) | | install-task | [Windows] Task Scheduler に登録 (ログオン起動 + 5分毎 watchdog) | | uninstall-task | [Windows] Task Scheduler 登録を解除 (config/offsets は残す) | | version | バージョン表示 | | help | ヘルプ |

アンインストール

promptkaizen-agent uninstall-launchd    # 自動起動を止める (Linux: uninstall-systemd)
rm -rf ~/.promptkaizen                  # config + offsets + logs を削除
cd promptkaizen-mvp/agent && npm unlink # グローバル CLI を削除 (任意)

トラブルシューティング

| 症状 | 対処 | |---|---| | promptkaizen-agent: command not found | install 時の Node version と現 shell の Node version が違う (nvm) ことが多い。 一時対応: source ~/.nvm/nvm.sh && nvm use 20 && promptkaizen-agent status。 恒久対応: ~/.zshrc 末尾に alias promptkaizen-agent='source ~/.nvm/nvm.sh && nvm use 20 >/dev/null && command promptkaizen-agent' を追記。 launchd 経由の agent 本体は plist で Node 20 絶対パス指定のため、 CLI が PATH になくても agent 自体は動く | | status で endpoint unreachable | dashboard /settings で発行した apiKey が正しいか / ネットワークを確認 | | status で process not running | tail -100 ~/.promptkaizen/agent.error.log でエラーを確認 | | agent.error.log に POST failed 401: Invalid apiKey | apiKey と endpoint の環境がズレている。dashboard が STG なら PROD apiKey は使えない (逆も同様)。promptkaizen-agent init --api-key '<key>' --env stg\|prod --yes で再 init → launchctl kickstart -k gui/$(id -u)/ai.promptkaizen.agent で再起動 | | 過去の Claude Code セッションが /events に出ない | 起動以前の entries は default で送らない (agent.skipInitialBacklog: true)。過去も送りたい場合は ~/.promptkaizen/agent.config.json の agent.skipInitialBacklog を false にして launchctl kickstart で再起動 | | Firebase CLI v15.x is incompatible with Node.js v18 | nvm use 20 に切り替え (install-agent.sh は自動で試みる) | | Mac 再起動後に動かない | launchctl list \| grep promptkaizen で plist が active か確認 |

想定アーキテクチャ

~/.claude/projects/*.jsonl
        ↓ (chokidar による fs watch)
PromptKaizen Agent (Node.js 常駐, ~10MB)
        ↓ (差分パース、オフセット管理)
        ↓ (PII マスキング)
        ↓ (バッチング: 5秒 or 50エントリ)
PromptKaizen Cloud API (HTTPS POST)

ディレクトリ構造

agent/
├── package.json
├── tsconfig.json
├── src/             # 実装本体 (Phase C で追加)
├── tests/           # vitest テスト
├── docs/            # 設計ドキュメント
└── scripts/         # 調査・運用スクリプト

開発

ルートで npm install 後:

npm run build --workspace=agent
npm run dev --workspace=agent      # tsx watch
npm run test --workspace=agent     # vitest