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

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.

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 →

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:

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        │
       └──────────────────────────────────────────────┘

       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 →

Start agents on your PC, monitor from your phone.

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

vibehq

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

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.

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 →

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.

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

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.

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.

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

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/

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

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.

{
  "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"] }
    ]
  }]
}

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

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 │
                    └──────────────────┘

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

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/

MIT

𝕏 @0x0funky