agnt-hub

📑 Table of Contents

• The Problem

• Key Features

• How Agent Hub Compares

• System Architecture

• Monorepo Structure

• Quick Start in 60 Seconds

• Connecting Your AI IDE (Antigravity, Claude, Cursor)

• Available MCP Tools

• Autonomous Headless Daemon (hubd)

• Documentation

• Contributing

• License

Related MCP server: synco-mcp

💥 The Problem

Autonomous coding agents (like Google Antigravity, Claude Desktop, and Cursor) are transforming software development. However, attempting to run multiple agents on a real-world repository creates chaos:

1. Collision Chaos: Multiple agents simultaneously edit the same files, clobbering each other's changes.

2. Git Merge Nightmares: Agents committing directly to the active branch create endless merge conflicts and broken dirty states.

3. No Context Sharing: Agents work in total isolation without awareness of tasks assigned to teammates or peer agents.

4. Cloud Bloat & SaaS Lock-in: Existing multi-agent frameworks are heavy Python DAG orchestrators requiring Redis, message brokers, Docker daemons, or expensive SaaS subscriptions.

⚡ Key Features

Agent Hub treats AI coding agents like human software engineers on an agile sprint team:

• 📋 Real-Time Kanban Board: Live updates powered by Server-Sent Events (SSE). Watch cards automatically glide from Ready $\rightarrow$ Claimed $\rightarrow$ In Progress $\rightarrow$ In Review $\rightarrow$ Done.

• 🔒 Fine-Grained File Locking: Mutual exclusion using Picomatch glob expressions (e.g., apps/hub/src/routes/**). Agents atomically acquire and release locks, preventing concurrent overwrite bugs.

• 🌿 Git Worktree Isolation: The headless runner daemon (hubd) automatically checks out tasks into isolated git worktrees, runs the agent, verifies tests, and opens PRs without ever disrupting your working directory.

• 🔌 100% Native MCP stdio Server: Exposes 12 standard Model Context Protocol tools out-of-the-box. Any MCP client connects in 30 seconds.

• 📦 Zero-Config SQLite Storage: Powered by local SQLite with Write-Ahead Logging (WAL) and Fastify. Boots in under 1 second with sub-2ms response times.

• 🛡️ Hardened & Tested: 100% test pass rate across 25 test suites (63 tests) covering concurrency races, clock drift, process crashes, and secret leakage.

📊 How Agent Hub Compares

🏗️ System Architecture

                          ┌───────────────────────────┐
                          │   React Kanban Board UI   │
                          │    (Vite + TailwindCSS)   │
                          └─────────────▲─────────────┘
                                        │  SSE / REST
                                        ▼
                          ┌───────────────────────────┐
                          │     Fastify Hub Server    │
                          │   (SQLite WAL + Reaper)   │
                          └───────▲───────────▲───────┘
                                  │           │
                    REST API (Bearer)       REST API (Bearer)
                                  │           │
                     ┌────────────┴──┐     ┌──┴────────────┐
                     │ agent-hub-mcp │     │  hubd Daemon  │
                     │  (stdio MCP)  │     │  (Headless)   │
                     └───────▲───────┘     └───▲───────────┘
                             │                 │
                      Antigravity IDE     Git Worktrees
                     (Interactive Dev)    (Autonomous Dev)

📦 Monorepo Structure

├── apps/
│   ├── hub/            # Fastify REST API, SQLite WAL database, SSE bus & reaper
│   └── web/            # React 18, Vite, Tailwind CSS Kanban dashboard
├── packages/
│   ├── mcp-shim/       # Model Context Protocol stdio server (12 agent tools)
│   ├── daemon/         # hubd daemon: task runner & git worktree isolation
│   └── shared/         # Shared domain schemas, invariants & ULID generators
├── scripts/            # Bootstrap, doctor diagnostics, simulation & online hot backup
└── docs/               # Architecture, API, Security, and OS Setup guides

🚀 Quick Start in 60 Seconds

1. Clone & Bootstrap

git clone https://github.com/MayankSharma-2812/agnt-hub.git
cd agnt-hub
./scripts/bootstrap.sh

2. Launch the Hub

pnpm --filter @agent-hub/hub dev

Open http://localhost:3000 in your browser. The initial admin token is printed directly to your console.

🔌 Connecting Your AI IDE

Configure your Model Context Protocol (MCP) client to connect to Agent Hub:

Configuration File Paths:

• Linux & macOS: ~/.gemini/config/mcp_config.json (or ~/.config/Claude/claude_desktop_config.json)

• Windows: %USERPROFILE%\.gemini\config\mcp_config.json

{
  "mcpServers": {
    "agent-hub": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/agnt-hub/packages/mcp-shim/dist/index.js"
      ],
      "env": {
        "HUB_URL": "http://localhost:3000",
        "HUB_TOKEN": "YOUR_HUB_TOKEN_HERE",
        "HUB_AGENT_NAME": "backend-agent"
      }
    }
  }
}

🛠️ Available MCP Tools

Once connected, your AI agent has direct access to 12 coordination tools:

🤖 Autonomous Headless Daemon (hubd)

Agent Hub includes hubd, an autonomous daemon for headless execution:

# Run doctor diagnostics to verify your environment
pnpm --filter @agent-hub/daemon hubd doctor

# Start autonomous worker loop for backend role
pnpm --filter @agent-hub/daemon hubd run --role backend

The daemon automatically:

1. Polls for ready tasks matching its role.

2. Creates an isolated git worktree at .worktrees/agent_<task-id>.

3. Invokes the AI agent (agy) headless within the isolated tree.

4. Validates changes, runs tests, commits, and marks the task as in_review.

📖 Documentation

• 📘 Setup & Multi-Platform OS Matrix

• 📗 Team Collaboration & USAGE Guide

• 📙 Self-Hosting & Cloudflare Tunnel

• 📕 Troubleshooting & FAQ

• 📋 One-Page Cheatsheet

• 📑 Full Technical Requirements Document (TRD)

🧪 Testing & Quality Assurance

Agent Hub is backed by an automated test suite verifying SQLite atomic rollbacks, Picomatch lock collisions, and SSE event monotonicity:

# Run all unit, integration, and chaos test suites (25 files, 63 tests)
pnpm test

# Run multi-agent concurrent load simulation (5 parallel agents)
pnpm --filter @agent-hub/daemon test:sim

🤝 Contributing

Contributions make the open-source community thrive! Whether submitting bug fixes, adding features, or improving documentation, please review CONTRIBUTING.md.

1. Fork the Project

2. Create your Feature Branch (git checkout -b feat/AmazingFeature)

3. Commit your Changes (git commit -m 'feat(hub): add AmazingFeature')

4. Push to the Branch (git push origin feat/AmazingFeature)

5. Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE for more information.