agent-team-pack 技術解説

外観

導入・設定・運用スクリプト ​

このページは「実際に動かす・運用する」観点で、導入フロー・設定ファイル・運用スクリプト・セキュリティガードをまとめます。

プラグインとマーケットプレイスの構造 ​

リポジトリ自体が 「ローカルマーケットプレイス＋プラグイン」 として作られています。

  • .claude-plugin/marketplace.json — マーケットプレイス定義（doubutuen-agent-tools）。
  • .claude-plugin/plugin.json — プラグイン定義（agent-team-pack v0.2.1）。hooks・experimental.monitors・userConfig を宣言。

plugin.json の主な宣言：

項目内容
hooks./hooks/hooks.json（SessionStart / Stop）
experimental.monitorsagent-dashboard を dashboard/start.sh で常時起動（:8080・read-only）
userConfig.memory_dirs記憶ディレクトリを GUI から設定する項目。フックとスキルへ自動配線される

install.sh の処理内容 ​

bash
bash install.sh "チーム名"

install.sh は次を順に行います。

  1. 依存チェック — node / python3 / git / claude の存在確認。
  2. FTS5 チェック — その python3 の sqlite3 で FTS5 仮想テーブルが作れるかを実際に試す（記憶層の前提）。
  3. マーケットプレイス登録 — claude plugin marketplace add <DIR>。
  4. プラグイン導入 — claude plugin install agent-team-pack@doubutuen-agent-tools。
  5. tasks/ 作成。
  6. dashboard/config.json の自動生成 — 既存があれば触らない。~/.claude/projects/ 配下から「memory/ を持つディレクトリ」を記憶ディレクトリ候補として自動検出し、HOME 等の環境値を埋め込んだ config.json を Python で生成する。

この自動生成のおかげで、フル導入経路はプレースホルダの手作業なしでそのまま動きます。生成される config.json はローカル専用の安全側既定（host: 127.0.0.1、allowedHosts: ["127.0.0.1","localhost"]）になります。

やめるときは bash uninstall.sh。

config.json：環境固有値の隔離先 ​

ホスト・絶対パス・チーム名・起動コマンドといった環境依存の値はすべて dashboard/config.json に集約され、これは .gitignore 済みでリポジトリに入りません。テンプレートは config.example.json で、<...> がプレースホルダです。

プレースホルダ意味
<YOUR TEAM NAME>画面に出すチーム名
<ABS_PATH>エージェントの workspace 等の絶対パス
<HOME>ホームディレクトリ
<ENCODED_LEAD_CWD>~/.claude/projects/ 配下の、リードエージェントの cwd を符号化したフォルダ名
<TAILSCALE_IP> / <TAILSCALE_HOSTNAME>別端末からのアクセス元（不要なら削除可）

serverOnly ブロックがサーバー内部だけで使う情報（データソースのパス・起動コマンド・許可ホスト）を保持し、クライアントには sanitizePublicConfig を通った安全な範囲しか渡りません。

運用スクリプト ​

セッションのアーカイブ／復元 ​

scripts/manage_sessions.sh は jsonl を projects ⇄ projects-archive で移動するだけ（中身不変・完全に可逆）。稼働中（pid 生存）のセッションは対象から自動除外します。

bash
# 稼働中以外のセッションをアーカイブへ退避
bash scripts/manage_sessions.sh archive-all
# 個別にアーカイブ（稼働中なら拒否）
bash scripts/manage_sessions.sh archive <sessionId>
# 退避したセッションを active に戻す
bash scripts/manage_sessions.sh restore <sessionId>

os.kill(pid, 0) による生存判定、mapfile を使わず while-read で読む（macOS の bash 3.2 互換）など、クロスプラットフォームへの配慮が随所にあります。ダッシュボードの POST API（archive-session / restore-session）と同じファイル移動セマンティクスを共有しているため、GUI と CLI のどちらから操作しても結果は一致します。

heartbeat：未着手タスクの担当エージェント起動（任意） ​

dashboard/heartbeat.sh は、tasks/*.md の frontmatter を読み「status: pending かつ担当者あり かつ blocked_by 空」のタスクを抽出し、担当エージェントの起動を支援します。

bash
bash heartbeat.sh                 # 未着手タスクを一覧表示
bash heartbeat.sh --copy <agent>  # 起動コマンドをクリップボードへコピー
bash heartbeat.sh --auto          # 担当エージェントを自動起動（確認あり）
bash heartbeat.sh --auto --yes    # 確認プロンプトをスキップ

多重起動を防ぐためのロック機構が丁寧に作られています。

  • .heartbeat.run.lock — flock でスクリプト自体の多重実行を防止。
  • .heartbeat_locks/<agent>.lock — 同一エージェントの再起動を lockTtlSec（既定 14400 秒 = 4 時間）抑制。
  • .heartbeat_locks/<agent>.pid — --auto で起動した子プロセスの PID。claude プロセス（または子孫）の生存と cwd を照合し、既に起動中なら二重起動しない。

プロセスの cwd 取得は Linux なら /proc、macOS なら lsof と分岐し、ここでもクロスプラットフォーム対応が徹底されています。これも frontmatter パースとタスク集計を Node のワンライナーで行うだけで、LLM は呼びません。

セキュリティ：公開前チェック ​

固有情報の混入を防ぐガードが同梱されています。公開・スクショ・配布の前に実行します。

bash
bash scripts/check_no_secrets.sh   # git 追跡ファイルに APIキー/固有名 等が無いか検査

secret_patterns.local.example をコピーして検査パターンをローカルに追加できます。config.json が .gitignore 済みであることと合わせ、「会社や他人の PC で使っても、公開ツリーに固有情報が混ざらない」を多層で担保しています。

まとめ：このパッケージの技術的な美点 ​

最後に、ソースを読み解いて見えた設計上の良さを整理します。

  • コスト構造をアーキテクチャで保証している：LLM を呼ぶ場所を「セッション内」だけに閉じ込め、ツールは機械的処理に徹する。これにより「常時動かしても追加課金ゼロ」が努力目標でなく構造的事実になっている。
  • 壊れても直せる前提（md が真実源）：SQLite を影と割り切ることで、冪等な reindex・非コミットの索引・シンプルな同期ロジックが成立している。
  • 安全性を許可リストで担保：メソッド・ホスト・静的ファイル・読み取りパスのすべてを「許可する側」で列挙し、read-only を既定にしている。
  • 増えても破綻しない仕組み：注入の目次方式、保存の重複拒否、エラー駆動の統合、ローテーション、棚卸しレポートが、記憶の経年劣化を多角的に抑える。
  • 移植性への執着：外部依存ゼロ、bash 3.2 互換、/proc と lsof の分岐など、macOS/Linux のどちらでも素直に動く配慮が一貫している。

agent-team-pack（MIT OSS）の仕組みを読み解いた技術解説資料

agent-team-pack: MIT License (c) 2026 合同会社どうぶつえん / 解説資料 by SYN