agentleFS
JustinWangJPJustinWangJP/cc-agent-teams-action-monitor/CLAUDE.md

cc-agent-teams-action-monitor

CLAUDE.md6 starsChanged 9 months agoMITView on GitHub

Agent Teams Dashboard - Claude Code Agent Teams のリアルタイム監視ダッシュボード。 ~/.claude/ ディレクトリを監視し、チーム構成、タスク進捗、エージェント活動を可視化します。 .claude/rules/japanese-default.md に従い、以下を遵守すること: .claude/skills/teamworks/SKILL.md を参照し、*HARD-GATE*制約を厳守すること: チーム体制をユーザーへ提示し、明示的な承認を得るまで、以下を一切実行してはならない: - コードの記述・編集 - ファイルの作成・変更 - スキャフォールディング - その他すべての実装作業 app/main.py の lifespan コンテキストマネージャーで以下のサービ

  • Installs packages

The file

Files
CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

プロジェクト概要

Agent Teams Dashboard - Claude Code Agent Teams のリアルタイム監視ダッシュボード。 ~/.claude/ ディレクトリを監視し、チーム構成、タスク進捗、エージェント活動を可視化します。

必須ガイドライン

言語設定

.claude/rules/japanese-default.md に従い、以下を遵守すること:

  • すべての会話は日本語で行う
  • コード内のコメントは日本語で記述
  • エラーメッセージの説明は日本語
  • ドキュメント生成は日本語
  • 変数名・関数名は英語(camelCase / snake_case)

Teamworks Skill(重要)

.claude/skills/teamworks/SKILL.md を参照し、HARD-GATE制約を厳守すること:

チーム体制をユーザーへ提示し、明示的な承認を得るまで、以下を一切実行してはならない:

  • コードの記述・編集
  • ファイルの作成・変更
  • スキャフォールディング
  • その他すべての実装作業

技術スタック

バックエンド

  • FastAPI (Python 3.11+) - REST API サーバー
  • Pydantic v2 - データバリデーション・設定管理
  • Watchdog - ファイルシステム監視

フロントエンド

  • React 18 - UIフレームワーク
  • TypeScript 5.3+ - 型安全な開発
  • Vite 5 - ビルドツール
  • TanStack Query (React Query) - データフェッチング・キャッシュ
  • Zustand - 状態管理
  • Tailwind CSS 3.4 - スタイリング
  • Radix UI - アクセシブルUIコンポーネント(Dialog, Select, Slider)
  • react-hot-toast - トースト通知
  • D3 / vis-timeline - タイムライン可視化
  • react-markdown - Markdown レンダリング
  • lucide-react - アイコンライブラリ

開発コマンド

バックエンド (backend/)

# 依存関係インストール
cd backend
pip install -e ".[dev]"

# 開発サーバー起動
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# テスト実行
pytest                                    # 全テスト実行
pytest -v                                # 詳細出力
pytest tests/test_api_teams.py -v        # 個別テストファイル
pytest tests/test_api_teams.py::test_get_team -v  # 特定テスト関数
pytest --cov=app --cov-report=html       # カバレッジ付き

# カバレッジレポート確認
open htmlcov/index.html

フロントエンド (frontend/)

# 依存関係インストール
cd frontend
npm install

# 開発サーバー起動 (http://localhost:5173)
npm run dev

# 型チェック
npx tsc --noEmit                         # 型エラー確認(ビルドなし)

# テスト実行
npm run test                             # テスト実行(単発)
npm run test:watch                       # ウォッチモード
npm run test:coverage                    # カバレッジ付き
npm run test:ui                          # UIモード

# 本番ビルド(tsc + vite build)
npm run build

# ビルドプレビュー
npm run preview

高レベルアーキテクチャ

システム構成

┌─────────────────────────────────────────────────────────────┐
│                      Frontend (React)                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ useTeams    │  │ useTasks    │  │ useInbox            │  │
│  │ (RQ poll)   │  │ (RQ poll)   │  │ (RQ poll)           │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
└─────────┼────────────────┼────────────────────┼─────────────┘
          │ HTTP           │ HTTP               │ HTTP
          ▼                ▼                    ▼
┌─────────────────────────────────────────────────────────────┐
│                    Backend (FastAPI)                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ /api/teams  │  │ /api/tasks  │  │ CacheService        │  │
│  └─────────────┘  └─────────────┘  └──────────┬──────────┘  │
│                                              │              │
│  ┌───────────────────────────────────────────▼────────────┐ │
│  │              FileWatcherService                         │ │
│  │         (watchdog で ~/.claude/ を監視)                 │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
          │
          ▼ ファイル変更イベント(ログ出力のみ)
┌─────────────────────────────────────────────────────────────┐
│              ~/.claude/ ディレクトリ構造                      │
│  ├── teams/{team_name}/config.json      # チーム設定         │
│  │   └── inboxes/{agent_name}.json      # エージェント別受信箱│
│  ├── tasks/{team_name}/{task_id}.json   # タスク定義         │
│  └── projects/{project-hash}/           # セッションログ     │
│      └── {sessionId}.jsonl              # セッション履歴     │
└─────────────────────────────────────────────────────────────┘

ライフサイクル管理(重要)

app/main.py の lifespan コンテキストマネージャーで以下のサービスを管理:

  1. FileWatcherService - ~/.claude/ のファイル変更を監視(ログ出力のみ)
  2. CacheService - チーム設定・インボックスのキャッシュ管理(TTL: 30秒/60秒)
# startup で開始、shutdown で停止
@asynccontextmanager
async def lifespan(app: FastAPI):
    watcher = FileWatcherService()
    await watcher.start()        # watchdog 監視開始
    app.state.watcher = watcher

    cache = await start_cache_service(config_ttl=30, inbox_ttl=60)
    app.state.cache = cache

    yield

    await watcher.stop()         # 監視停止
    await stop_cache_service()   # キャッシュ解放

データフェッチング(React Query)

HTTP Polling によるリアルタイム更新:

フックAPI エンドポイントポーリング間隔用途
useTeamsGET /api/teams30秒(設定可)チーム一覧
useTasksGET /api/tasks30秒(設定可)タスク一覧
useInboxGET /api/teams/{name}/inboxes30秒(設定可)インボックス
useAgentMessagesGET /api/teams/{name}/inboxes/{agent}30秒(設定可)エージェント別メッセージ

ポーリング間隔は Zustand Store で管理(5s/10s/20s/30s/60sから選択可能)。

// dashboardStore.ts
const DEFAULT_POLLING_INTERVAL = 30000; // 30秒

重要なパス・エイリアス

バックエンド

  • モジュールパス: app.* で統一(例: from app.models.team import Team)

フロントエンド(vite.config.ts)

  • エイリアス: @/ → src/ (例: import { useTeams } from '@/hooks/useTeams')
  • プロキシ: /api → http://127.0.0.1:8000(開発時のCORS回避)
// vite.config.ts
server: {
  port: 5173,
  proxy: {
    '/api': {
      target: 'http://127.0.0.1:8000',
      changeOrigin: true,
    },
  },
}

ファイル監視とキャッシュ無効化

FileWatcherService は以下のパターンを検知(ログ出力のみ、500msデバウンス):

パターンイベントキャッシュ無効化メソッド
**/teams/*/config.jsonチーム設定変更invalidate_team_config(team_name)
**/teams/*/inboxes/*.jsonインボックス更新invalidate_team_inbox(team_name, agent_name)
**/tasks/*/*.jsonタスク状態変更ログ出力のみ

ファイル変更検知時、対応するキャッシュを自動的に無効化し、次回のAPI呼び出しで新しいデータが返されます。

ダークモード実装

Tailwind CSS のクラスベースダークモード(darkMode: 'class')を使用:

  • html 要素に dark クラスを付与/削除で切り替え
  • Zustand Store で状態管理(isDarkMode)、ローカルストレージへ永続化
  • システム設定の検出は行わず、手動切り替えのみ対応

フロントエンドテスト環境

src/test/setup.ts で以下のグローバルモックを設定:

モック用途
IntersectionObserver可視性検出(無限スクロール等)
ResizeObserverリサイズ検出
localStorageストレージ操作のモック
matchMediaメディアクエリ(ダークモード検出等)

テストファイルは **/__tests__/**/*.test.tsx パターンで配置し、Vitest + React Testing Library を使用。

テストカバレッジ要件

backend/pyproject.toml で最低70%を要求:

[tool.pytest.ini_options]
addopts = [
    "--cov-fail-under=70"
]

主要コンポーネント

バックエンド

ファイル説明
app/main.pyFastAPI エントリーポイント、lifespan 管理(FileWatcher/CacheService)
app/config.pyPydantic Settings(環境変数プレフィックス: DASHBOARD_)
app/api/routes/teams.pyチーム REST API、インボックスAPI
app/api/routes/tasks.pyタスク REST API
app/api/routes/messages.pyメッセージ関連 API
app/api/routes/agents.pyエージェント関連 API
app/api/routes/timeline.pyタイムライン API(セッションログ統合)
app/services/timeline_service.pyinbox + セッションログ統合サービス
app/services/agent_status_service.pyエージェント状態推論サービス
app/services/file_watcher.pywatchdog によるファイル監視、ログ出力のみ
app/services/cache_service.pyTTLベースキャッシュ、クリーンアップ間隔5分
app/models/*.pyPydantic データモデル

フロントエンド

ファイル説明
src/hooks/useTeams.tsチームデータ取得(React Query + ポーリング)
src/hooks/useTasks.tsタスクデータ取得(React Query + ポーリング)
src/hooks/useInbox.tsインボックス取得(React Query + ポーリング)
src/hooks/useAgentMessages.tsエージェント別メッセージ取得(React Query + ポーリング)
src/hooks/useFileChanges.tsファイル変更監視フック
src/hooks/useUnifiedTimeline.ts統合タイムラインデータ取得フック
src/stores/dashboardStore.tsZustand Store(ポーリング間隔管理含む)
src/components/dashboard/TeamCard.tsxチームカード表示
src/components/tasks/TaskCard.tsxタスクカード表示
src/components/chat/ChatMessageBubble.tsxメッセージバブル(inbox/session統合表示)
src/types/*.tsTypeScript 型定義

環境変数

バックエンドは DASHBOARD_ プレフィックスの環境変数で設定:

環境変数デフォルト説明
DASHBOARD_HOST127.0.0.1サーバー待ち受けアドレス
DASHBOARD_PORT8000サーバー待ち受けポート
DASHBOARD_DEBUGTrueデバッグモード
DASHBOARD_CLAUDE_DIR~/.claudeClaude データディレクトリ

セッションログ監視(統合タイムライン)

セッションログの場所

Claude Code のセッションログは以下のパスに保存されます:

~/.claude/projects/{project-hash}/{sessionId}.jsonl
  • project-hash: cwd(作業ディレクトリ)から生成(先頭に - を付与し、/ を - に置換)
  • sessionId: チーム設定(config.json)の leadSessionId から取得

統合タイムラインサービス

TimelineService が inbox メッセージとセッションログを統合:

データソースファイルパス用途
inboxteams/{name}/inboxes/{agent}.jsonエージェント間メッセージ
sessionprojects/{hash}/{sessionId}.jsonlセッション履歴(thinking, tool_use, file_change 等)

セッションログエントリタイプ

タイプ内容表示アイコン
user_messageユーザー入力👤
assistant_messageアシスタント応答🤖
thinking思考プロセス💭
tool_useツール呼び出し🔧
file_changeファイル変更📁

エージェント状態推論

AgentStatusService が以下の情報からエージェント状態を推論:

状態判定条件表示
idle5分以上無活動💤 待機中
workingin_progressタスクあり🔵 作業中
waitingblockedなタスクあり⏳ 待ち状態
error30分以上無活動❌ エラー
completed全タスク完了✅ 完了

状態推論に使用するデータ:

  • inbox メッセージ(task_assignment, task_completed 等)
  • タスク定義(owner, status, blockedBy)
  • セッションログ(最終活動時刻、使用モデル)

チームステータス判定

チームのステータスは以下のロジックで判定:

ステータス判定条件削除ボタン
activeセッションログ mtime ≤ 1時間非表示
stoppedセッションログ mtime > 1時間表示
unknownセッションログなし非表示
inactivemembers 空配列非表示

判定フロー:

  1. config.json の members 配列を確認 → 空の場合は inactive
  2. セッションログの存在確認 → なしの場合は unknown
  3. セッションログ mtime と現在時刻の差分 → 1時間以内は active、超過は stopped

ファイル変更履歴

file-history-snapshot エントリからファイル変更を抽出:

操作アイコン色
created✨緑
modified✏️青
deleted🗑️赤
read📖灰

タイムラインAPIエンドポイント

エンドポイント用途パラメータ
GET /api/history統合タイムライン取得team_name, limit, types, before_event_id
GET /api/updates差分更新取得team_name, since(ISO8601タイムスタンプ)
GET /api/file-changes/{team}ファイル変更一覧team_name

差分更新(/api/updates)により、ポーリング時のデータ転送を最小化します。

チーム削除 API

stopped 状態のチームのみ削除可能:

DELETE /api/teams/{team_name}

削除対象ファイル:

  • teams/{team-name}/ - チーム設定全体
  • tasks/{team-name}/ - タスク定義
  • projects/{project-hash}/{session}.jsonl - セッションログ(ディレクトリは残す)

エラーレスポンス:

  • 404 Not Found - チームが存在しない
  • 400 Bad Request - ステータスが stopped 以外

ドキュメント構造

多言語ドキュメント

docs/spec/ 内のドキュメントは言語別にサフィックスで管理:

ファイル言語
*.md日本語(デフォルト)
*.en.md英語
*.zh.md中国語

例: system-design.md, system-design.en.md, system-design.zh.md

スクリーンショット

UI のスクリーンショットは docs/images/ に配置:

ファイル内容
dashboard-main-page.pngメインページ(チーム一覧)
dashboard-team-detail-page.pngチーム詳細
dashboard-team-timeline-page.pngタイムラインビュー
dashboard-message-detail-page.pngメッセージ詳細
dashboard-team-tasks-page.pngタスク管理(カンバン)

詳細ドキュメント一覧

docs/spec/ 内の主要ドキュメント:

  • architecture.md - アプリケーションアーキテクチャ
  • backend-tech-stack.md - バックエンド技術詳細
  • frontend-tech-stack.md - フロントエンド技術詳細
  • system-design.md - システム設計書
  • ut-plan.md - ユニットテスト計画
  • user-guide.md - ユーザーガイド

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.