0x0funky/vibehq-hub

🌐 Language: English | 繁體中文 | 日本語

⚡ VibeHQ

Running 5 AI agents in parallel is easy.Making them not break each other’s code is the hard part.

VibeHQ adds contracts, task tracking, and idle-aware messaging to Claude Code, Codex & Gemini CLI — so they work like an actual engineering team, not 5 interns editing the same file.

---

The Problem Nobody Talks About

Every “multi-agent” tool lets you run multiple CLI agents in parallel. But parallel ≠ collaboration. Here’s what actually happens when 5 agents build the same app:

These aren’t edge cases. They’re LLM-native behavioral patterns that reliably appear across model families. We documented 7 of them with full session logs.

📖 Read the full analysis: 7 LLM-Native Problems →

---

What VibeHQ Actually Does

VibeHQ is a teamwork protocol layer that sits on top of real CLI agents. Each agent stays a full Claude Code / Codex / Gemini process with all native features — VibeHQ adds the coordination they’re missing:

---

Self-Improving Coordination: The Framework That Debugs Itself

VibeHQ doesn’t just coordinate agents — it analyzes its own failures and writes code to fix them. Fully automated, zero human intervention.

We built a closed-loop system: run a benchmark → analyze the logs → /optimize-protocol reads the analysis and implements real code changes → rebuild → run again and measure:

┌─────────────┐     ┌──────────────────┐     ┌───────────────────┐
│  Benchmark   │────▶│  vibehq-analyze   │────▶│ /optimize-protocol│
│  (run team)  │     │  --with-llm       │     │   (Claude skill)  │
└─────────────┘     └──────────────────┘     └───────────────────┘
       ▲                                              │
       │              writes real code changes        │
       └──────────────────────────────────────────────┘

Benchmark Results: Todo App (V1 → V5, 4 agents)

Benchmark Results: Classroom Quiz (fully automated loop)

What the system learned and built

       23.1M ┤                         * CQ-V1
             │
       15.0M ┤               * V3  * V4
       13.8M ┤                            * CQ-V2
             │
        7.2M ┤  * V1
        5.7M ┤                                  * V5
        3.9M ┤      * V2
             │
           0 ┼──────────────────────────────────────
             V1   V2   V3   V4  CQ1  CQ2   V5

Key insight: Prompt constraints are suggestions. CLI-level enforcement is law. Agents adapt and route around soft limits — the fix must be architectural.

📖 Full blog post: Self-Improving Multi-Agent Coordination →

---

📱 Web Dashboard — Desktop & Mobile

Start agents on your PC, monitor from your phone.

Mobile

https://github.com/user-attachments/assets/9d056e18-44ea-418a-8831-dafc5cb724b8

Desktop

https://github.com/user-attachments/assets/6f0fe691-bef8-49f9-a0ce-a65b215d264f

---

🚀 Quick Start

git clone https://github.com/0x0funky/vibehq-hub.git
cd vibehq-hub && npm install
npm run build

Terminal (TUI)

vibehq

Interactive menu — select a team, configure agents, start. Everything runs in your terminal.

Web Dashboard

npm run build:web
vibehq-web

Open http://localhost:3100 — create a team, add agents, hit Start. Manage everything from a browser.

# With auth (recommended for LAN/mobile access)
VIBEHQ_AUTH=admin:secret vibehq-web

The server prints your LAN IP — open it on your phone and you’re in.

---

🔧 20 MCP Tools

Every agent gets 20 collaboration tools auto-injected via Model Context Protocol:

Communication (6): ask_teammate, reply_to_team, post_update, get_team_updates, list_teammates, check_status

Tasks (5): create_task, accept_task, update_task, complete_task, list_tasks

Artifacts (5): publish_artifact, list_artifacts, share_file, read_shared_file, list_shared_files

Contracts (3): publish_contract, sign_contract, check_contract

System (1): get_hub_info

🎬 Watch 7 agents collaborate in real-time →

---

📊 Post-Run Analytics & Auto-Optimization

Analyze

vibehq-analyze ./data                        # Analyze session logs
vibehq-analyze --team my-team --with-llm     # Auto-resolve team logs + LLM insights
vibehq-analyze --team my-team --with-llm --save --run-id v1  # Save for optimization
vibehq-analyze compare v1 v2                 # Compare two runs side-by-side
vibehq-analyze history --last 10             # View past runs

13 automated detection rules: artifact regression, orchestrator role drift, stub files, task timeout, incomplete tasks, coordination overhead, unresponsive agents, zero artifacts, context bloat, duplicate artifacts, premature task accept, excessive MCP polling, task reassignment.

Skills: /run-teamwork, /benchmark-loop & /optimize-protocol

VibeHQ ships three skills. Skills work on both Claude Code and Codex CLI — same format, different directory.

Cross-Platform Skill Locations

The SKILL.md format is an emerging cross-platform standard — same frontmatter (name, description), same markdown body. A skill created for one platform works on the other.

Setup

Claude Code — skills are already included in .claude/skills/. Just use them:

# In Claude Code, type:
/run-teamwork "Build an AI investment analysis platform"
/benchmark-loop "Build a todo app" --grade A
/optimize-protocol v1

Codex CLI — copy the skills to Codex’s directory:

# Project-level (committed to repo)
mkdir -p .agents/skills
cp -r .claude/skills/run-teamwork .agents/skills/
cp -r .claude/skills/optimize-protocol .agents/skills/
cp -r .claude/skills/benchmark-loop .agents/skills/

# Or user-level (available in all projects)
cp -r .claude/skills/run-teamwork ~/.codex/skills/
cp -r .claude/skills/optimize-protocol ~/.codex/skills/
cp -r .claude/skills/benchmark-loop ~/.codex/skills/

Then in Codex CLI, invoke with /skills or type $ to mention a skill.

/run-teamwork — One-Shot Team Builder

Give it a project description — it designs the team, spawns agents, and builds it. No analysis, no loop.

/run-teamwork "Build an e-commerce site with payments and admin panel"

1. Analyzes the prompt to determine required domains and team size
2. Generates PM system prompt with research-first workflow (research before implementation)
3. Spawns agents in tmux (macOS/Linux) or Windows Terminal
4. Waits for all tasks to complete
5. Reports the output directory and file count

/optimize-protocol — Framework Engineer

Reads analysis data and writes real code fixes (not parameter tuning):

/optimize-protocol v1    # Read analysis for run v1, implement fixes

1. Loads current run + all previous optimization reports
2. Builds cross-run trend table (what’s improving, what regressed, what’s a side-effect)
3. Classifies each problem as NEW, RECURRING, or SIDE-EFFECT of a previous fix
4. Implements real TypeScript changes to the framework
5. Verifies build passes
6. Saves a detailed changelog to ~/.vibehq/analytics/optimizations/

/benchmark-loop — Autonomous Runner

Runs the full self-improving cycle automatically:

/benchmark-loop "Build a Todo app with REST API, React frontend, and WebSocket real-time updates"

1. Spawns a fresh team with a standardized project
2. Waits for the team to finish (heartbeat monitoring)
3. Analyzes session logs (13 rules + LLM grading)
4. Triggers /optimize-protocol to write code fixes
5. Rebuilds the framework (npx tsup)
6. Repeats with a new team — zero human intervention

Manual Step-by-Step (works with any CLI)

The underlying tools are regular CLI commands — no skills required:

# 1. Run a benchmark
vibehq start --team your-team

# 2. Analyze
vibehq-analyze --team your-team --with-llm --save --run-id v1

# 3. Auto-optimize (Claude Code / Codex skill)
/optimize-protocol v1

# 4. Run again, compare
vibehq start --team your-team
vibehq-analyze --team your-team --with-llm --save --run-id v2
vibehq-analyze compare v1 v2

All optimization reports are saved to ~/.vibehq/analytics/optimizations/ for tracking and auditing.

Supports both Claude Code and Codex CLI native JSONL log formats.

---

🤝 Contributing

PRs welcome. Modular architecture:

• New MCP tool? → src/mcp/tools/ + register in hub-client.ts
• New CLI? → detection in spawner.ts + MCP config in autoConfigureMcp()
• New widget? → web/src/components/ or src/tui/screens/

📄 License

MIT

---

𝕏 @0x0funky