# ⚡ Agent Squad Bridge

> **Bidirectional Multi-Agent MCP Collaboration Runtime & Discussion Space Web UI**  
> Orchestrating **Claude Code**, **Google Antigravity (Gemini)**, **GPT / Codex**, and **OpenCode** on your local machine with isolated Git worktrees, turn-budget safeguards, and real-time collaboration.

---

## 🌟 Overview

Inspired by the architectures of **Claude Squad**, **gemini-mcp**, **agent-mcp**, and **Vibe Kanban**, **Agent Squad Bridge** transforms individual AI coding CLIs into a synchronized engineering team.

Instead of running disjointed chat windows or letting autonomous agents blindly overwrite the same files, Agent Squad Bridge provides:

1. **Local MCP Collaboration Server**: Exposes cross-agent communication tools (`ask_agent`, `send_agent_message`, `request_review`, `create_agent_worktree`, etc.).
2. **Turn-Budget & Recursion Safeguards**: Prevents recursive ping-pong loops (e.g. Claude ➔ Gemini ➔ Claude ➔ Gemini) by tracking call depth and decrementing remaining turn budgets.
3. **Isolated Git Worktrees**: Automatically assigns separate branches (`agent/claude/*`, `agent/gemini/*`, etc.) in isolated directories (`.worktrees/`) so parallel coding never causes merge collisions.
4. **Interactive Discussion Space & Kanban Web UI**: A clean, modern local web dashboard (`agent-team ui`) to inspect cross-agent discussions, track tasks on a Kanban board, view code review diffs, and intervene as a human-in-the-loop.

```
                          YOUR WORKSTATION
┌────────────────────────────────────────────────────────────────────────┐
│  WEB DASHBOARD (agent-team ui - http://localhost:8765)                 │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │ Project Selector | Discussion Space (Chat) | Task Kanban | Review │  │
│  └──────────────────────────────────┬───────────────────────────────┘  │
│                                     │ REST API                         │
│                                     ▼                                  │
│                    ┌──────────────────────────────────┐                │
│                    │     Local Agent Bridge & MCP     │                │
│                    │      (FastMCP / Starlette)       │                │
│                    └────────────────┬─────────────────┘                │
│                                     │                                  │
│         ┌───────────────┬───────────┴───────────┬───────────────┐      │
│         ▼               ▼                       ▼               ▼      │
│    Claude Code     Antigravity / Gemini    GPT / Codex      OpenCode   │
│   (Architecture)     (Review/Research)      (Algorithm)     (Executor) │
│         │               │                       │               │      │
│         └───────────────┼───────────────────────┴───────────────┘      │
│                         ▼                                              │
│               Shared Multi-Project Store                               │
│              (messages, tasks, DAG, reviews)                           │
│                         │                                              │
│                         ▼                                              │
│          Isolated Git Worktrees per Agent / Branch                     │
│         (.worktrees/claude-*, .worktrees/gemini-*, ...)                │
└────────────────────────────────────────────────────────────────────────┘
```

---

## 🚀 Quick Start Tutorial

### 1. Prerequisites

- **Python**: 3.11+ (recommended with [`uv`](https://github.com/astral-sh/uv))
- **Git**: Installed and available in PATH
- **Claude Code**: Installed via npm (`npm install -g @anthropic-ai/claude-code`)
- **Gemini CLI / Antigravity**: Installed via npm (`npm install -g @google/gemini-cli`)
- **OpenAI API Key** *(Optional)*: Set `OPENAI_API_KEY` for live GPT / Codex invocations. Override the balanced `gpt-5.6-terra` default with `AGENT_BRIDGE_OPENAI_MODEL`.
- **OpenCode** *(Optional)*: Install the `opencode` CLI or set `OPENCODE_BIN` to its executable

---

### 2. Installation & Setup

Clone the repository and sync dependencies:

```bash
git clone https://github.com/kagtgi/claude-antigravity-bridge.git
cd claude-antigravity-bridge

# Sync virtualenv using uv
uv sync
```

---

### 3. Register MCP Servers

Run the automated registration command:

```cmd
agent-team register
```

This automatically configures the bridge into:
- **Google Antigravity / Gemini**: `~/.gemini/config/mcp_config.json`
- **Claude Code**: Registered via `claude mcp add agent-bridge`

Verify registration:
```cmd
agent-team check
claude mcp list
```

You should see:
```text
agent-bridge: ... - √ Connected
```

---

### 4. Launch the Discussion Space Web UI

Start the interactive web dashboard:

```cmd
agent-team ui
```

This automatically opens **`http://localhost:8765`** in your default browser.

#### Web Dashboard Highlights:
- **📁 Project Selector**: Filter discussions and tasks by workspace.
- **💬 Discussion Space**: Chronological timeline of inter-agent messages, thoughts, and reviews with color-coded badges:
  - 🟣 **Claude** (Purple)
  - 🔵 **Gemini** (Cyan)
  - 🟢 **Codex** (Emerald)
  - 🟠 **OpenCode** (Amber)
  - 👤 **User** (Indigo)
- **📋 Task Kanban Board**: Visual columns for `Pending`, `In Progress`, `Review Needed`, and `Completed`.
- **🔍 Code Reviews**: Review ticket inspector displaying branch diffs and feedback verdicts.
- **✈️ Human Intervention Bar**: Send guidance or new tasks to all agents or a specific agent at any time.

---

## 🛠️ Multi-Agent Collaboration Workflow

Here is a typical production workflow where **Claude** builds, **Gemini** conducts security reviews, and **Codex** handles algorithmic optimization:

### Step 1: Prompt Claude Code
Start Claude Code in your project directory:
```cmd
claude
```
Instruct Claude:
> *"Implement user authentication in `auth.ts`. Once implemented, call `ask_gemini` to perform a rigorous security and edge-case review of your changes. If Gemini finds any vulnerabilities, address them before finishing."*

### Step 2: Automated Cross-Agent Review
1. Claude implements `auth.ts` in branch `agent/claude/auth-feature`.
2. Claude calls the bridge tool `ask_gemini`:
   ```json
   {
     "prompt": "Review auth.ts for token rotation vulnerabilities and CSRF race conditions."
   }
   ```
3. The bridge executes Gemini non-interactively in headless mode with turn-budget protection.
4. Gemini's analysis returns directly into Claude's context stream:
   > *"Found 2 vulnerabilities: 1. Refresh token reuse window; 2. Missing SameSite flag on cookie."*
5. Claude patches both issues and runs the test suite.
6. Claude calls `submit_result` to mark the task completed.

---

## 📦 MCP Tools Reference

The bridge registers the following 15 tools with both Claude Code and Antigravity:

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `ask_agent` | `agent`, `prompt`, `context`, `worktree`, `remaining_turn_budget` | Unified router dispatching to `claude`, `gemini`, `codex`, or `opencode` with turn-budget safety. |
| `ask_claude` | `prompt`, `context`, `worktree`, `timeout` | Headless non-interactive Claude Code call (`claude -p`). |
| `ask_gemini` | `prompt`, `context`, `worktree`, `timeout` | Headless non-interactive Gemini/Antigravity call (`gemini -p`). |
| `ask_codex` | `prompt`, `context`, `model`, `timeout` | GPT / Codex specialist invocation via OpenAI API. |
| `ask_opencode` | `prompt`, `context`, `worktree`, `timeout` | Autonomous OpenCode harness executor. |
| `send_agent_message` | `recipient`, `subject`, `message`, `project_id`, `task_id` | Post structured note to another agent or broadcast to `all`. |
| `read_agent_messages` | `recipient`, `project_id`, `unread_only` | Fetch unread messages for an agent and mark them read. |
| `request_review` | `target_branch_or_path`, `summary`, `requester`, `reviewer` | Create formal review ticket with diff generation. |
| `submit_review` | `review_id`, `verdict`, `feedback`, `reviewer` | Record review feedback and an approval, change request, or comment verdict. |
| `get_agent_status` | `agent` | Check operational readiness of all agents or a specific agent. |
| `submit_result` | `task_id`, `summary`, `commit_hash`, `project_id` | Mark task completed with summary and commit SHA. |
| `get_task_state` | `task_id`, `project_id` | Query specific task or list all tasks for a project. |
| `update_task_state` | `task_id`, `status`, `title`, `assigned_to`, `result` | Update task progress in the shared state store. |
| `create_agent_worktree`| `agent_name`, `branch_name`, `base_branch` | Create isolated Git worktree (`.worktrees/<agent>-<branch>`). |
| `list_projects` | *(none)* | List all registered workspaces and activity metrics. |

---

## 💻 CLI Commands (`agent-team`)

```bash
# Run system diagnostics and verify agent paths
agent-team check

# Register MCP server with Claude Code and Antigravity
agent-team register

# Launch Discussion Space & Kanban Web Dashboard
agent-team ui [--port 8765] [--no-browser]

# Check active tasks, messages, and reviews
agent-team status [--project <project_id>]

# Query any agent directly from the terminal
agent-team ask claude "Summarize architectural best practices"
agent-team ask gemini "Review security considerations for JWTs"

# Post a message into the discussion space
agent-team send --to gemini -s "Review Request" -m "Please inspect auth module"

# Create a task on the Kanban board
agent-team task --title "Implement OAuth2 Flow" --assignee claude --status in_progress
```

---

## 🛡️ Built-in Safeguards

1. **Turn-Budget & Recursion Ceiling**:
   - Monitored through `AGENT_BRIDGE_DEPTH` and `AGENT_BRIDGE_TURN_BUDGET`.
   - Halts execution when limits are reached, returning a synthesis instruction to eliminate runaway token loops.
2. **Git Worktree Isolation**:
   - Each agent operates in dedicated directories under `.worktrees/`, keeping main repositories clean and avoiding simultaneous file overwrite conflicts.
3. **Encoding & Shell Resilience**:
   - Cross-platform Windows UTF-8 console stream wrappers prevent charmap crashes when printing multi-language text (including Vietnamese, Japanese, and emoji indicators).
4. **Crash-Safe Shared State**:
   - Cross-process locking and atomic file replacement prevent concurrent agents from losing each other's messages, tasks, or reviews.
   - Invalid JSON is reported without overwriting the existing state file.
5. **Per-Agent Broadcast Delivery**:
   - Broadcast messages track readers independently, so one agent cannot consume a team-wide message on behalf of every other agent.

---

## 📄 License

MIT License. Designed and maintained by [kagtgi](https://github.com/kagtgi).