Vibehq Hub

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 →

List Teammates

https://github.com/user-attachments/assets/b4e20201-dc32-4ab4-b5fe-84b165d44e23

Teammate Talk

https://github.com/user-attachments/assets/ea254931-9981-4eb6-8db3-44480ec88041

Assign Task

https://github.com/user-attachments/assets/fec7634e-976a-4100-8b78-bd63ad1dbec0

📊 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.

The web platform is accessible on your LAN by default. For external access:

⚠️ Always set VIBEHQ_AUTH before exposing remotely — the web UI gives full terminal access.

Tailscale (recommended): Install on PC + phone → sign in both → VIBEHQ_AUTH=admin:secret vibehq-web → open http://<tailscale-ip>:3100 on phone.

vibehq.config.json

{
  "teams": [{
    "name": "my-project",
    "hub": { "port": 3001 },
    "agents": [
      { "name": "Alex", "role": "Project Manager", "cli": "codex", "cwd": "D:\\project" },
      { "name": "Jordan", "role": "Frontend Engineer", "cli": "claude", "cwd": "D:\\project\\frontend",
        "dangerouslySkipPermissions": true, "additionalDirs": ["D:\\project\\shared"] }
    ]
  }]
}

Built-in presets: Project Manager, Product Designer, Frontend Engineer, Backend Engineer, AI Engineer, QA Engineer

vibehq              # Interactive TUI
vibehq-web          # Web platform (browser + mobile)
vibehq-hub          # Standalone hub server
vibehq-spawn        # Spawn single agent
vibehq-analyze      # Post-run analytics

Manual Spawn

vibehq-spawn --name "Jordan" --role "Frontend Engineer" \
  --team "my-team" --hub "ws://localhost:3001" \
  --skip-permissions --add-dir "/shared" -- claude

┌──────────────────────────────────────────────────┐
│                   VibeHQ Hub                      │
│               (WebSocket Server)                  │
│  ┌────────┐ ┌──────────┐ ┌────────┐ ┌─────────┐ │
│  │ Tasks  │ │Artifacts │ │Contract│ │ Message │ │
│  │ Store  │ │ Registry │ │ Store  │ │  Queue  │ │
│  └────────┘ └──────────┘ └────────┘ └─────────┘ │
│  ┌──────────────────────────────────────────────┐│
│  │  Agent Registry — idle/working detection     ││
│  └──────────────────────────────────────────────┘│
└────────┬──────────┬──────────┬──────────┬────────┘
    ┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌───▼────┐
    │ Claude │ │ Claude │ │ Codex  │ │ Claude │
    │  (FE)  │ │  (BE)  │ │  (PM)  │ │  (QA)  │
    │ 20 MCP │ │ 20 MCP │ │ 20 MCP │ │ 20 MCP │
    └────────┘ └────────┘ └────────┘ └────────┘
         ▲          ▲          ▲          ▲
         └──────────┴────┬─────┴──────────┘
                    ┌────▼─────────────┐
                    │  Web Dashboard   │
                    │ Desktop & Mobile │
                    └──────────────────┘

Key design:

• Process isolation — each agent is a separate OS process. Crashes don't cascade.
• Contract-driven — specs must be signed before coding begins.
• Idle-aware queue — messages queue when busy, flush when idle (JSONL watcher + PTY timeout).
• State persistence — all data survives hub restarts (~/.vibehq/teams/<team>/hub-state.json).
• MCP-native — 20 purpose-built tools, type-safe, auto-configured per agent.
• Orchestrator enforcement — Claude PMs get --disallowedTools (CLI-level hard block on Bash/Write/Edit/Read/Glob); Codex PMs get --sandbox read-only.
• Content validation — MCP rejects 0-byte artifacts, stub patterns, and >80% size regressions at the tool level.
• Self-improving — analyze→optimize loop with cross-run trend tracking and automated changelogs.

Mac: requires xcode-select --install. If posix_spawnp failed: chmod +x node_modules/node-pty/prebuilds/*/spawn-helper

Linux: requires build-essential and python3.

agent-hub/
├── bin/                  # CLI entry points (start, spawn, hub, web, analyze)
├── src/
│   ├── hub/              # WebSocket hub, agent registry, message relay
│   ├── spawner/          # PTY manager, JSONL watcher, idle detection
│   ├── web/              # Express server, REST API, WebSocket handlers
│   ├── mcp/              # 20 MCP tools + hub-client bridge
│   ├── analyzer/         # Post-run analytics pipeline (13 rules)
│   ├── shared/           # TypeScript types
│   └── tui/              # Terminal UI screens + role presets
├── web/                  # React frontend (Vite + xterm.js)
├── blog/                 # Technical articles on LLM behavioral patterns
└── benchmarks/           # V1 vs V2 comparison reports

🤝 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