VibeCodeHPCは、HPC向けの全自動で環境構築・コード最適化を行うマルチエージェントシステムです。 Claude Code等のCLI環境でtmuxを用いた通信により、複数のAIエージェントが協調します。
- 階層型マルチエージェント: PM → SE ↔ PG の企業的分業体制
- プロジェクト地図: 組織をリアルタイムに視覚化する
directory_pane_map
- 進化的探索: ボトムアップ型の
Flat
📁構造による効率的探索 - 自動最適化: OpenMP、MPI、OpenACC、CUDA...等の段階的並列化と技術融合
- 予算管理: 計算資源💰の効率的配分と追跡
- 統一ログ:
ChangeLog.md
による一元的な進捗管理
- スパコン: 不老、富岳等のHPCシステム
- コンパイラ: Intel OneAPI、GCC、NVIDIA HPC SDK...
graph TD
User[👤 User] --> PM[🤖 PM<br/>Project Manager]
PM --> SE1[🤖 SE1<br/>System Engineer]
PM --> CD[🤖 CD<br/>Continuous Delivery]
SE1 <--> PG1[🤖 PG1.1<br/>OpenMP]
SE1 <--> PG2[🤖 PG1.2<br/>MPI]
SE1 <--> PG3[🤖 PG1.3<br/>CUDA]
CD --> GitHub[📦 GitHub Repository]
Agent | 役割 | 主要成果物 | 責任範囲 |
---|---|---|---|
PM | プロジェクト統括 | directory_pane_map.md User-shared/final_report.md |
要件定義・リソース配分・予算管理 |
SE | システム設計 | User-shared/の画像とレポート | エージェント監視・統計分析・レポート生成 |
PG | コード生成・実行 | ChangeLog.md sota_local.txt |
並列化実装・SSH/SFTP接続・ジョブ実行・性能測定 |
CD | デプロイ管理 | GitHub/以下のprojectコピー | SOTA達成コード公開・匿名化 |
VibeCodeHPC/🤖PM
├── 📄 CLAUDE.md # 全エージェント共通ルール
├── 📄 requirement_definition.md # 要件定義書
├── 📄 directory_pane_map.md # エージェント配置とtmuxペイン統合管理
├── 📄 sota_project.txt # プロジェクト全体SOTA
│
├── 📁 Agent-shared/ # エージェント共有指示書
│
├── 📁 User-shared/ # ユーザ向け成果物
│ ├── 📄 final_report.md # 最終報告書
│ ├── 📁 reports/ # 統合レポート
│ └── 📁 visualizations/ # グラフ・図表
│
├── 📁 BaseCode/ # 既存のオリジナルコード
│
├── 📁 communication/ # エージェント起動・tmux通信システム
│
├── 📁 GitHub/🤖CD
│
└── 📁 Flow/TypeII/single-node/🤖SE1 # ハードウェア階層
├── 📄 hardware_info.md # 計算ノードのスペック情報
├── 📄 sota_hardware.txt # 指定ハード内のSOTA
├── 📁 intel2024/ # コンパイラ環境
│ └── 📁 OpenMP/🤖PG1.1.1 # 並列化モジュール
│ ├── 📄 ChangeLog.md # 進捗記録
│ └── 📄 sota_local.txt
└── 📁 gcc11.3.0/ # 別コンパイラ
└── 📁 CUDA/🤖PG1.2.1
- 特徴: 常にファイルやステータスを確認し、自律的に非同期で行動
- 例: PMが全エージェントを巡回監視→リソース再配分
- 例: PGがコード生成→自律的に実行→結果確認→次の最適化
- 特徴: 一連のタスクを順次実行し、各ステップで判断
- 例: 要件定義→環境調査→階層設計→エージェント配置
flowchart TB
%% 起動スクリプトの包含関係
subgraph StartScripts["🚀 起動スクリプト"]
User[👤 ユーザー]
PM[🤖 PM]
User -->StartPM[start_PM.sh<br/>PMプロセス専用]
PM -->StartAgent[start_agent.sh<br/>他エージェント用]
StartPM -->|直接実行| LaunchClaude
StartAgent -->|生成| LocalScript[start_agent_local.sh]
LocalScript -->|実行| LaunchClaude
end
%% 共通処理の流れ
subgraph CommonFlow["🔄 共通処理フロー"]
LaunchClaude[launch_claude_with_env.sh]
LaunchClaude -->|1.hooks設定判定| SetupHooks[setup_agent_hooks.sh]
LaunchClaude -->|2.telemetry設定判定| EnvSetup[環境変数設定<br/>.env読み込み]
LaunchClaude -->|3.claude --dangerously-skip-permissions| Claude[claude --dangerously-skip-permissions]
end
%% データフロー
subgraph DataFlow["💾 データ管理"]
SetupHooks -->|配置| HooksDir[.claude/📂settings.local.json<br/>hooks/📂<br/>session_start.py<br/>stop.py<br/>post_tool_ssh_handler.py<br/>agent_id.txt ]
LocalScript -->|working_dir記録| JSONL
Claude -->|SessionStartイベント| SessionHook[session_start.py]
SessionHook -->|agent_id.txt参照<br/>claude_session_id記録| JSONL
JSONL[(agent_and_pane_id_table.jsonl)]
end
%% Stop hookの動作フロー
Claude[claude起動] -->|Stopイベント| StopHook[stop.py実行]
StopHook -->|polling型| PreventWait[待機防止タスク提示]
%% スタイリング
style StartScripts fill:#fff8fc,stroke:#c2185b,stroke-width:2px
style CommonFlow fill:#e3f2fd,stroke:#0288d1,stroke-width:3px
style User fill:#fce4ec,stroke:#c2185b,stroke-width:2px
style PM fill:#fce4ec,stroke:#c2185b,stroke-width:2px
style LaunchClaude fill:#e1f5fe,stroke:#0288d1,stroke-width:3px
style JSONL fill:#fff9c4,stroke:#f57f17,stroke-width:2px
style JSONL fill:#fff9c4,stroke:#f57f17,stroke-width:2px
style HooksDir fill:#ffe0b2,stroke:#f57c00,stroke-width:2px
style StopHook fill:#ffe0b2,stroke:#f57c00,stroke-width:2px
style SessionHook fill:#ffe0b2,stroke:#f57c00,stroke-width:2px
詳細は Issue #23: エージェント起動とhooksのセットアップの流れ を参照。
sequenceDiagram
participant PM as PM
participant SE as SE
participant PG as PG
participant HPC as スパコン
PM->>PG: 最適化タスク割り当て
PG->>HPC: SSH/SFTP接続確立
loop 最適化ループ
PG->>PG: コード生成・修正・ChangeLog.md記録
PG->>HPC: コード転送・コンパイル・ジョブ投入
HPC-->>PG: 実行結果・性能データ
PG->>SE: SOTA達成報告
end
SE->>SE: 統計分析・可視化(非同期)
プロジェクトの終了条件とフローチャートは Issue #33: プロジェクト終了条件と手順 を参照してください。
本システムを利用する前に、以下の環境がセットアップ済みであることを確認してください。
Note
以下の理由から VibeCodeHPC は git clone を用いずzipでダウンロードし展開することを推奨
GitHub/📁でプロジェクトの匿名版コピーを管理するCDエージェントのGit認証との混同を避ける
releaseから(mainからでもOK) ダウンロードした.zipを展開
コマンドラインでダウンロードする場合(クリックで展開)
VibeCodeHPCをダウンロード
wget https://github.com/Katagiri-Hoshino-Lab/VibeCodeHPC-jp/archive/refs/tags/v{バージョン}.zip
zip解凍
unzip VibeCodeHPC-jp-{バージョン}.zip
展開後、VibeCodeHPCのルートへ移動
cd VibeCodeHPC-jp-{バージョン}
-
スーパーコンピュータへのパスワード不要のSSH接続を有効にするため、
ssh-agent
に秘密鍵を登録します。 -
ssh-agentを有効にする手順はこちらのGoogleスライドを参照
ssh-agentを起動:
eval "$(ssh-agent -s)"
秘密鍵を追加:
ssh-add ~/.ssh/your_private_key
-
確認コマンド
ssh-add -l
Note
このターミナルを閉じるまでは有効で、tmuxのターミナル分割でも引き継がれます。
- Windowsの場合は、WSL (Ubuntu 22.04) をセットアップします。
nvm
経由でのNode.js (v18以上) のインストールを推奨します [参考: https://zenn.dev/acntechjp/articles/eb5d6c8e71bfb9]- 以下のコマンドでClaude Codeをインストールし、初回起動時にアカウント認証を完了させてください。
npm install -g @anthropic-ai/claude-code claude
tmux, jq, Python環境のインストール方法(クリックで展開)
VibeCodeHPCの全機能を活用するため、以下のツールのインストールを推奨します:
Ubuntu/WSL:
sudo apt-get update && sudo apt-get install tmux
CentOS/RHEL/Fedora:
sudo yum install tmux # または sudo dnf install tmux
macOS:
brew install tmux
ユーザ権限でのインストール(sudo不可の環境):
wget https://github.com/tmux/tmux/releases/download/3.4/tmux-3.4.tar.gz
tar xzf tmux-3.4.tar.gz
cd tmux-3.4
./configure --prefix=$HOME/.local
make && make install
export PATH=$HOME/.local/bin:$PATH # .bashrcに追加推奨
シングルエージェントモード(
./start_solo.sh
)はtmuxなしでも動作しますが、セッション管理の観点からtmuxの使用を推奨
Ubuntu/WSL:
sudo apt install jq
macOS:
brew install jq
エージェント間通信(agent_send.sh)でJSONL形式のテーブルを効率的に解析します
通常のインストール:
pip3 install -r requirements.txt
必要なパッケージ:
- matplotlib - グラフ生成(SOTA推移、予算消費、コンテキスト使用率)
- numpy - 数値計算(線形回帰、統計処理)
- pandas - データ分析(ChangeLog.md解析、集計)
- scipy - 統計分析(予算予測の線形回帰)
これらのパッケージは主に可視化スクリプトで使用されます。バージョンは厳密に指定していないため、最新版で問題ありません
可視化スクリプトは
python3 script.py
で実行されます
GitHubのGUIでリポジトリ作成(Privateも可)
GitHub/📁に移動
cd GitHub
Gitの設定済み情報が表示するコマンド
git config -l
もしuser.emailとuser.nameが設定されていない場合:
git config --global user.email xxx@yyy.zzz
git config --global user.name YOUR_GITHUB_NAME
GitHubディレクトリの初期設定
git init
リモートリポジトリの設定
git remote add origin https://github.com/YOUR_NAME/YOUR_REPOSITORY.git
# 既に origin がある場合は:
git remote set-url origin https://github.com/YOUR_NAME/YOUR_REPOSITORY.git
➡以下のように選択肢は様々 https://zenn.dev/miya789/articles/manager-core-for-two-factor-authentication
選択肢1:GCM
Git Credential Manager (GCM)が推奨。 https://github.com/git-ecosystem/git-credential-manager/releases
WSLで使用する際の注意 https://zenn.dev/jeffi7/articles/dccb6f29fbb640
選択肢2:gh
gh (GitHub CLIツール)ダウンロード
sudo apt update
sudo apt install gh
ghでの認証
gh auth login
ブラウザ経由でログイン
開始直前に以下のMCPサーバを設定することを推奨します:
プロジェクトルート📂で起動するPM🤖にMCPサーバを与えます。 重要: Claude Code起動前にMCPを設定してください。
cd VibeCodeHPC-main
Desktop Commander MCP PM、SE、PGがHPC環境へのSSH/SFTP接続を管理に活用
claude mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander
mcp-screenshot PMが障害対応等でtmux全体の状況を視覚的な確認に活用
claude mcp add mcp-screenshot -- npx -y @kazuph/mcp-screenshot
Warning
mcp-screenshotはWSLでは機能しません WSL環境ではスクリーンショット機能が動作しないため、OSネイティブなコマンドプロンプトでの使用を推奨します。
# プロジェクトディレクトリに移動
cd VibeCodeHPC-jp-main
環境変数で無効化:
export VIBECODE_ENABLE_TELEMETRY=false
# セットアップ不要でトークン使用量を確認
npx ccusage@latest
監視環境の自動セットアップ:
./telemetry/setup_grafana.sh
ブラウザでアクセス:
http://localhost:3000
ログイン情報:
- ユーザー名:
admin
- パスワード:
admin
ccusageは、JSONLログからトークン使用量を分析するCLIツールです。
Grafanaでメトリクスを確認する方法(OpenTelemetry有効時のみ)
- Drilldown → Metrics を選択
- ログイン後、特に事前準備なしで利用可能
- Cost(コスト)やToken数が自動的に可視化される
- エージェント別・時系列でのトークン消費を確認
- 注意事項
- Claude CodeのOpenTelemetryメトリクスはOTLP経由で送信
- デフォルトではローカルのCollector(4317ポート)に接続
- 詳細な設定は
telemetry/otel_config.env
で調整可能
実験評価用シングルエージェントモード(クリックで展開)
実験評価用のシングルエージェントモードを追加しました。1つのClaude Codeインスタンスが全ての役割(PM/SE/PG/CD)を担当します。
使用方法
# セットアップ(0ワーカー = シングルモード)
./communication/setup.sh 0 --project GEMM
# エージェント起動
./start_solo.sh
起動後、以下のプロンプトが表示されるのでコピーして貼り付けてください:
あなたはVibeCodeHPCのシングルエージェントモードで動作します。
全ての役割(PM/SE/PG/CD)を1人で担当し、効率的にプロジェクトを進めます。
【初期設定】
まず以下のファイルを読み込んでください:
- CLAUDE.md(全エージェント共通ルール)
- instructions/SOLO.md(シングルモード専用の統合プロンプト)
- requirement_definition.md(存在する場合)
- Agent-shared/project_start_time.txt(プロジェクト開始時刻)
【ToDoリストによる役割管理】
TodoWriteツールを積極的に使用し、各タスクに役割タグ([PM], [SE], [PG], [CD])を付けて管理してください。
【時間管理】
- プロジェクト開始時刻から経過時間を定期的に確認
- requirement_definition.mdに時間制限がある場合は厳守
- 予算管理と並行して時間効率も意識
【効率的な実行順序】
1. [PM] 要件定義と環境調査
2. [SE] 環境構築
3. [PG] 実装とテスト(ループ)
4. [SE] 統計・可視化
5. [CD] GitHub同期(必要時)
6. [PM] 最終報告
agent_send.shは使用不要です(通信相手がいないため)。
全ての処理を内部で完結させてください。
プロジェクトを開始してください。
- 統合実行: 1つのインスタンスで全役割を実行
- ToDoリスト管理: 役割切り替えを明示的に管理
- 時間管理: project_start_time.txtで経過時間を追跡
- マルチモードと同じ仕組み: ChangeLog.md、SOTA管理等は共通
詳細は instructions/SOLO.md
を参照してください。
Important
VibeCodeHPCは複数のtmuxセッションを使用します:
- PMセッション: PMエージェント専用(ユーザとの対話用)
- デフォルト:
Team1_PM
- プロジェクト指定時:
{ProjectName}_PM
- デフォルト:
- ワーカーセッション: その他のエージェント(SE, PG, CD)
- デフォルト:
Team1_Workers1
- プロジェクト指定時:
{ProjectName}_Workers1
- デフォルト:
最小エージェント数は2です(SE + PG)
cd VibeCodeHPC-jp-main
./communication/setup.sh [ワーカー数] # 例: ./communication/setup.sh 12
コマンドラインオプション:
./communication/setup.sh 12 --project GEMM # デフォルト60秒間隔で定期Enter送信
./communication/setup.sh 12 --project GEMM --periodic-enter 30 # 30秒間隔
./communication/setup.sh 12 --project GEMM --periodic-enter 0 # 定期Enter無効
上記コマンドで GEMM_PM
, GEMM_Workers1
セッションを作成、残留メッセージ強制送信機能も起動
Workers | SE | PG | CD | 備考 |
---|---|---|---|---|
2 | 1 | 1 | 0 | 最小構成 |
4 | 1 | 3 | 0 | 小規模 |
8 | 2 | 5 | 1 | SE≧2で安定 |
12 | 2 | 9 | 1 | 推奨構成 |
16 | 3 | 12 | 1 | 大規模 |
プロジェクト名をGEMM
に指定した場合の例
タブ1(PMエージェント用):
tmux attach-session -t GEMM_PM
タブ2(その他のエージェント用):
tmux attach-session -t GEMM_Workers1
Tip
setup.shの出力に表示される実際のセッション名を使用してください。
要件定義(skipした場合は、PMと対話的に作成)
cp requirement_definition_template.md requirement_definition.md
# requirement_definition.mdを編集
PMを起動
./start_PM.sh
その他の起動オプション(クリックで展開)
# telemetryのみ(hooksなし、待機防止が無効)
./telemetry/launch_claude_with_env.sh PM
# 最小構成(hooks・telemetryなし)
claude --dangerously-skip-permissions
# telemetryのみ無効化(PM起動時)
VIBECODE_ENABLE_TELEMETRY=false ./start_PM.sh
# ⚠️ hooksの無効化は非推奨(ポーリング型エージェントが待機してしまう)
# どうしても無効化したい場合は、プロジェクト開始前に以下を実行:
# export VIBECODE_ENABLE_HOOKS=false
注意: PMはポーリング型エージェントのため、hooksを無効化すると待機状態に入ってしまいます。
エージェントの挙動を制御するhooks機能により、以下が実現されます:
- ポーリング型エージェント(PM, SE, PG, CD)の待機防止: 定期的なタスクを自動提示
- SSH/SFTP接続支援: PostToolUseフックがSSH接続を検出し、Desktop Commander MCPでのセッション管理方法を自動案内
- session_id追跡: 各エージェントのClaude session_idを記録・管理
# v3(デフォルト)確率的に生のドキュメントを提供
./communication/setup.sh 12
# v2: ファイルパスのみ提供(レガシー)
./communication/setup.sh 12 --hooks v2
- v3: 全モード推奨。
auto_tuning_config.json
で役割別の確率カスタマイズ可能 - v2: 旧バージョン。固定ファイルリストのみ提供
- SOLO: 常にv3を使用(v2指定は無視される)
詳細は hooks/hooks_deployment_guide.md
を参照してください。
起動後、以下のプロンプトをコピーして貼り付け:
あなたはPM(Project Manager)です。VibeCodeHPCプロジェクトを開始します。
まず以下のファイルを読み込んでプロジェクトの全体像を把握してください:
- CLAUDE.md(全エージェント共通ルール)
- instructions/PM.md(あなたの役割詳細)
- requirement_definition.md(プロジェクト要件)※存在する場合
- Agent-shared/以下の全ての.mdと.txtファイル(ただし、.pyファイルを除く)
特に重要:
- max_agent_number.txt(利用可能なワーカー数)
- agent_and_pane_id_table.jsonl(セッション構成とエージェント管理)
- directory_pane_map_example.md(エージェント配置とペイン管理)
- sota_management.md(SOTA管理方法とfamilyの重要性)
全て読み込んだ後、該当する既存の tmux セッションを活用してプロジェクトを初期化してください。新規セッションは作成しないでください。
名称 | 最高性能のスコープ |
---|---|
Local | PG自身のディレクトリ内 |
Family | 技術系統(親子世代の関係) |
Hardware | 同一ハードウェア構成内(single-node/multi-node等) |
Project | プロジェクト全体 |
各階層でのSOTA判定により、効率的なベンチマーク比較と最適化方針決定を自動化。
異なるミドルウェア(gcc, intel等)のデータを統合し、ハードウェア(single-node)構成全体での性能変遷が自動プロットされる。 特にその時点での最高性能:SOTA(State-of-the-Art)を可視化する。
HPC予算の消費をリアルタイムで追跡し、線形回帰による予測と閾値到達時刻(ETA)を表示。多くのスパコンでは前日までの集計しか確認できませんが、ChangeLog.mdから即座に推定値を算出します。
エージェント間の情報共有を実現する統一ログシステム。
実際のChangeLog.md
例:
変更点: "ブロッキング最適化とスレッド数調整"
結果: 理論性能の65.1%達成 312.4 GFLOPS
コメント: "ブロックサイズを64から128に変更、キャッシュ効率が大幅改善"
- 生成時刻:
2025-08-20T10:30:00Z
- compile
- status:
success
- warnings:
none
- status:
- job
- id:
123456
- resource_group:
F_small
- start_time:
2025-08-20T10:31:00Z
- end_time:
2025-08-20T10:31:45Z
- runtime_sec:
45
- status:
success
- id:
- test
- status:
pass
- performance:
312.4
- unit:
GFLOPS
- efficiency:
65.1%
- accuracy:
PASS (diff < 1e-6)
- status:
- sota
- scope:
local
- scope:
- params:
- nodes:
8
- threads_per_node:
32
- block_size:
128
- nodes:
変更点: "初期OpenMP実装"
結果: ベースライン確立 248.3 GFLOPS
コメント: "基本的なOpenMP並列化を外側ループに適用"
- 生成時刻:
2025-08-20T10:15:00Z
- compile
- status:
success
- warnings:
none
- status:
- job
- id:
123454
- resource_group:
F_small
- start_time:
2025-08-20T10:16:00Z
- end_time:
2025-08-20T10:16:48Z
- runtime_sec:
48
- status:
success
- id:
- test
- status:
pass
- performance:
248.3
- unit:
GFLOPS
- efficiency:
51.7%
- status:
- params:
- nodes:
8
- threads_per_node:
32
- nodes:
- 詳細:Agent-shared/change_log/ChangeLog_format.md
- PMオーバーライド:Agent-shared/change_log/ChangeLog_format_PM_override_template.md
- 🌱 種子期: 単一技術の個別最適化 (
/OpenMP/
,/MPI/
,/AVX512/
,/CUDA/
) - 🌿 交配期: 有望技術の融合 (
/OpenMP_MPI/
,/MPI_CUDA/
) - 🌳 品種改良期: 高度な組み合わせ (
/OpenMP_MPI_AVX512/
)
-
階層の曖昧性解消:
/MPI/OpenMP/
vs/OpenMP/MPI/
の重複排除 -
並列探索効率化: 複数エージェントによる同時最適化
-
技術継承: 上位世代が下位世代の成果を参照可能
-
詳細: Agent-shared/strategies/auto_tuning/evolutional_flat_dir.md
- 成果物配置: Agent-shared/artifacts_position.md
- SOTA管理: Agent-shared/sota/sota_management.md
- レポート階層: Agent-shared/report_hierarchy.md
Important
ユーザ向け成果物
プロジェクトの成果はUser-shared/
ディレクトリに集約されます:
Tip
エージェント可視化 各エージェントのコンテキスト推移を可視化 SE担当の統計解析により、性能推移とSOTA更新履歴をリアルタイム監視。
エージェントごとのコンテキスト使用量を自動追跡し、auto-compact(メモリリセット)の発生を予測・検知する監視機能を標準搭載。各エージェントの消費量を可視化し、効率的なリソース管理を支援します。
より詳細なトークン使用量やコスト、ツール実行状況の分析が必要な場合は、組み込みのOpenTelemetryによる監視が可能です。ただし、スパコン環境への導入が困難な場合があるため、オプション機能として提供しています。
監視設定は「2. 環境セットアップ」 の監視オプションを参照してください。
詳細設定: telemetry/README.md
- 機密情報保護:
_remote_info/
はGit管理外 - 自動匿名化: GitHub公開時にユーザID等を匿名化
- SOTA達成コードのみ公開: 性能向上を実現したコードのみ
- 階層別アクセス制御: Agent役割に応じた読み書き権限
このプロジェクトはApache License 2.0の下で公開されています。自由にご利用いただけますが、使用に関する責任は負いかねます。