# agentbridge

**Repository Path**: goodlucktou/agentbridge

## Basic Information

- **Project Name**: agentbridge
- **Description**: No description available
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-17
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AgentBridge

[![CI](https://github.com/anYuJia/agentbridge/actions/workflows/ci.yml/badge.svg)](https://github.com/anYuJia/agentbridge/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Go](https://img.shields.io/badge/Go-1.23%2B-00ADD8.svg)](go.mod)

**The universal bridge between AI applications and CLI agents.**

AgentBridge gives MCP-compatible applications one stable interface for running CLI AI agents. It handles process execution, streaming progress, session history, workspace boundaries, concurrency, and adapter-specific protocols behind a single deployable Go binary.

Kubernetes provides a runtime for containers. Nginx routes network traffic. AgentBridge aims to provide the runtime and routing layer for AI agents.

```text
 Claude Desktop   Cursor   Continue   OpenClaw   Custom Agents
        \           |         |          |           /
                         MCP
                          |
                   +-------------+
                   | AgentBridge |
                   +-------------+
                    /     |      \
             sessions  policies  adapters
                          |
                 Antigravity CLI (agy) / Claude Code / Codex CLI
```

## Why AgentBridge

CLI agents expose different flags, event formats, permission models, and session mechanisms. Integrating each agent directly creates tight coupling between an AI application and every downstream runtime.

AgentBridge separates those concerns:

- **One MCP contract** for every supported CLI agent
- **Adapter isolation** for vendor-specific commands and output formats
- **Streaming progress** through standard MCP notifications
- **Portable sessions** stored independently of vendor conversation formats
- **Workspace policies** based on canonical allowed roots
- **Bounded execution** with concurrency limits and hard timeouts
- **Secure defaults** with explicit permission escalation
- **Single-binary deployment** using Go and pure-Go SQLite

## Available Today

| Capability | Support |
| --- | --- |
| MCP stdio server | Yes |
| `ask_agent` tool | Yes |
| Antigravity CLI (`agy`) | Yes |
| Streaming step and tool progress | Yes |
| Persistent sessions | SQLite |
| Workspace allowlist | Yes |
| Claude Code adapter (`claude`) | Yes (v0.2) |
| OpenAI Codex CLI adapter (`codex`) | Yes (v0.3, JSONL streaming) |
| Optional ops HTTP server (`/healthz`, `/readyz`, `/metrics`) | Yes (v0.4, disabled by default) |
| Prometheus metrics instrumentation | Yes (v0.4) |
| Graceful drain on SIGINT/SIGTERM | Yes (v0.4) |
| SIGHUP config reload (low-risk fields) | Yes (v0.4 routing reload skeleton) |

Antigravity 1.1.3 streams execution steps and tool state. Assistant text is returned in the final `result.response`, so clients receive live operational progress followed by the complete answer.

The Codex CLI adapter uses `codex exec --json` and maps newline-delimited JSON events to AgentBridge stream events. Known event types (assistant messages, tool calls, status progress) are mapped to `EventText`, `EventTool`, or `EventStatus` respectively. Unknown event types are safely ignored. If a JSON parse error occurs, the stream returns a clear protocol error rather than dropping the data.

## Quick Start

### Requirements

- Go 1.23 or later
- Antigravity CLI `agy` 1.1.3 or later
- An MCP client with stdio server support

Authenticate Antigravity once in an interactive terminal:

```bash
agy
```

Build and start AgentBridge:

```bash
git clone https://github.com/anYuJia/agentbridge.git
cd agentbridge
make build
./bin/agentbridge server
```

With no configuration file, AgentBridge restricts workspaces to its current directory and stores sessions in `.agentbridge/agentbridge.db`.

## MCP Client Setup

Create an AgentBridge configuration from [`configs/agentbridge.example.yaml`](configs/agentbridge.example.yaml), then register the binary with your MCP client.

Example Claude Desktop configuration:

```json
{
  "mcpServers": {
    "agentbridge": {
      "command": "/absolute/path/to/agentbridge",
      "args": [
        "server",
        "--config",
        "/absolute/path/to/agentbridge.yaml"
      ],
      "env": {
        "AGENTBRIDGE_DATA_DIR": "/absolute/path/to/data",
        "AGENTBRIDGE_WORKSPACE_ROOT": "/absolute/path/to/projects"
      }
    }
  }
}
```

Start the server manually with:

```bash
./bin/agentbridge server --config /absolute/path/to/agentbridge.yaml
```

## Tool Contract

AgentBridge exposes `ask_agent` to interact with CLI agents:

```json
{
  "agent": "optional-agent-name",
  "strategy": "manual|auto|weighted",
  "task_type": "general|code_review|architecture_review|research",
  "prompt": "Review this project's concurrency design.",
  "workspace": "/absolute/path/to/project",
  "session_id": "optional-session-uuid"
}
```

- **`agent`**: Explicit target agent name (e.g. `agy`, `claude`, `codex`). Defaults to `agy` if omitted and `strategy` is `manual` or not set.
- **`strategy`**: Routing strategy.
  - `manual`: Direct routing to the specified `agent`.
  - `auto` (default): Deterministically selects the best healthy agent according to `task_type` capabilities and configured weights.
  - `weighted`: Selects from healthy matching agents based on weight configuration.
- **`task_type`**: Task profiles mapping to required capabilities (`general`, `code_review`, `architecture_review`, `research`).
- **`session_id`**: Reusable session UUID to continue the conversation.

When the MCP caller supplies a progress token, AgentBridge emits `notifications/progress` for agent initialization, reasoning steps, and tool activity.

AgentBridge also exposes `list_agents` to check status and metadata of registered agents:

Example call result:
```json
{
  "agents": [
    {
      "name": "agy",
      "enabled": true,
      "healthy": true,
      "capabilities": {
        "CodeReview": true,
        "ArchitectureReview": true,
        "Research": true,
        "Shell": true,
        "Streaming": true,
        "NativeSessions": false
      },
      "configured_weight": 100
    },
    {
      "name": "claude",
      "enabled": true,
      "healthy": true,
      "capabilities": {
        "CodeReview": true,
        "ArchitectureReview": true,
        "Research": true,
        "Shell": true,
        "Streaming": true,
        "NativeSessions": false
      },
      "configured_weight": 90
    },
    {
      "name": "codex",
      "enabled": false,
      "healthy": false,
      "capabilities": {
        "CodeReview": true,
        "ArchitectureReview": true,
        "Research": true,
        "Shell": false,
        "Streaming": true,
        "NativeSessions": false
      },
      "configured_weight": 80
    }
  ]
}
```

## Configuration

```yaml
server:
  name: agentbridge

runtime:
  max_concurrent: 16
  agent_timeout: 10m

storage:
  path: ${AGENTBRIDGE_DATA_DIR}/agentbridge.db

session:
  history_messages: 20
  history_chars: 32768

security:
  workspace_only: true
  allow_shell: false
  allowed_roots:
    - ${AGENTBRIDGE_WORKSPACE_ROOT}

adapters:
  antigravity:
    enabled: true
    binary: agy
    model: ""
    agent: ""
    mode: plan
    sandbox: true
    dangerously_skip_permissions: false
    print_timeout: 5m
    environment: {}
  claude:
    enabled: false
    binary: claude
    model: ""
    permission_mode: plan
    dangerously_skip_permissions: false
    max_budget_usd: 0
    environment: {}
  codex:
    enabled: false
    binary: codex
    model: ""
    sandbox_mode: read-only
    approval_policy: ""
    full_auto: false
    environment: {}

routing:
  default_strategy: auto
  weights:
    agy: 100
    claude: 90
    codex: 80

operations:
  # Optional HTTP ops server. Disabled by default; does not affect MCP stdio.
  enabled: false
  listen: "127.0.0.1:9090"
  health_path: "/healthz"
  readiness_path: "/readyz"
  metrics_path: "/metrics"
```

Environment variables are expanded at startup. Unknown YAML fields are rejected to prevent misspelled security settings from silently falling back to defaults.

## Operations

AgentBridge can expose a small same-process HTTP operations surface for long-running local or server deployments. **It is disabled by default** and has no effect on the MCP stdio transport when left off.

Enable it in configuration:

```yaml
operations:
  enabled: true
  listen: "127.0.0.1:9090"
  health_path: "/healthz"
  readiness_path: "/readyz"
  metrics_path: "/metrics"
```

| Endpoint | Purpose |
| --- | --- |
| `GET /healthz` | Liveness. Returns `200` with body `ok` while the process is up. |
| `GET /readyz` | Readiness. Checks storage ping and enabled adapters. Returns `200` when ready, `503` with JSON diagnostics when not. Disabled adapters do not fail readiness. |
| `GET /metrics` | Prometheus exposition of request counters, durations, stream events, adapter health, sessions, and active requests. |

Example readiness response:

```json
{
  "status": "ready",
  "storage": "ok",
  "adapters": [
    {"name": "agy", "enabled": true, "healthy": true},
    {"name": "claude", "enabled": false, "healthy": false}
  ]
}
```

Metrics labels are limited to low-cardinality dimensions (`agent`, `task_type`, `status`, `event_type`). Prompt text, workspace paths, and session IDs are never used as labels.

### Signals

| Signal | Behavior |
| --- | --- |
| `SIGINT` / `SIGTERM` | Stop accepting new agent work, drain in-flight tasks up to `runtime.agent_timeout`, shut down the ops HTTP server gracefully. |
| `SIGHUP` | Reload configuration from the path passed via `--config`. Applies only routing weights and default strategy. Operations settings, adapter binaries, permissions, storage path, session settings, and runtime settings are **not** hot-reloaded; changes are logged as warnings and require restart. |

Send `SIGHUP` only when the process was started with an explicit `--config` path.

## Permission Model

Antigravity execution permissions are configurable through three adapter settings:

| Setting | Values | Purpose |
| --- | --- | --- |
| `mode` | `plan`, `accept-edits` | Selects the Antigravity execution mode |
| `sandbox` | `true`, `false` | Enables Antigravity terminal restrictions |
| `dangerously_skip_permissions` | `true`, `false` | Auto-approves Antigravity tool permission requests |

Codex CLI permissions are configured through adapter settings that map to official CLI flags:

| Setting | Values | Maps to | Purpose |
| --- | --- | --- | --- |
| `sandbox_mode` | `read-only`, `workspace-write`, `danger-full-access` | `--sandbox <mode>` | Controls filesystem and command isolation |
| `approval_policy` | `untrusted`, `on-request`, `never` | `--ask-for-approval <policy>` | Controls when Codex asks for user approval |
| `full_auto` | `true`, `false` | `--full-auto` (deprecated) | Compatibility flag; prefer `sandbox_mode` |

`security.allow_shell` is the upper policy gate. When it is `false`:

- Antigravity requires `mode: plan` and rejects permission bypass
- Codex requires `sandbox_mode: read-only` (or empty) and rejects `approval_policy: never` and `full_auto: true`

Enabling `dangerously_skip_permissions` also requires Antigravity `sandbox: true`.

The recommended approach is to keep the bypass disabled and configure narrowly scoped Antigravity `permissions.allow` rules in `~/.gemini/antigravity-cli/settings.json`. Headless `agy` cannot show interactive approval prompts.

Example trusted sandbox profile:

```yaml
security:
  workspace_only: true
  allow_shell: true
  allowed_roots:
    - /workspace

adapters:
  antigravity:
    mode: accept-edits
    sandbox: true
    dangerously_skip_permissions: true
  codex:
    sandbox_mode: workspace-write
    approval_policy: on-request
```

Permission bypass is powerful. Use it only inside an isolated environment with restricted mounts, credentials, networking, CPU, memory, and process limits. See [`docs/security.md`](docs/security.md) for the full threat model.

## Architecture

AgentBridge keeps protocol, orchestration, and vendor integration independent:

```text
MCP transport
     |
MCP tool handlers
     |
Bridge service
  /       |        \
session  workspace  agent manager
  |                    |
SQLite              adapters
                       |
                       agy
```

See [`docs/architecture.md`](docs/architecture.md) for request lifecycle, concurrency, storage, and adapter design.

## Docker

The image contains AgentBridge but does not redistribute Google's platform-specific `agy` binary. Supply a Linux `agy` binary and authenticated configuration at runtime:

```bash
docker build -t agentbridge .
docker run --rm -i \
  -v "/path/to/linux/agy:/usr/local/bin/agy:ro" \
  -v "$HOME/.gemini:/home/agentbridge/.gemini" \
  -v "$PWD:/workspace:ro" \
  -v agentbridge-data:/data \
  agentbridge
```

The `agy` binary must match the container platform. A macOS binary cannot run in a Linux image.

## Building an Adapter

An adapter implements the common `agent.Adapter` contract:

```go
type Adapter interface {
    Name() string
    HealthCheck(context.Context) error
    Execute(context.Context, Request) (Response, error)
    Stream(context.Context, Request) Stream
}
```

Adapters own binary discovery, command construction, native event parsing, cancellation, and output aggregation. They must never write protocol data directly to stdout.

## Roadmap

- Additional CLI agent adapters (e.g. Google Gemini CLI, Cursor)
- External adapter plugin protocol
- Streamable HTTP transport with authentication
- OpenTelemetry tracing and full ops dashboard
- Container and platform sandbox profiles
- A2A protocol, remote workers, and multi-tenant policy

v0.4 delivers the operations foundation (optional HTTP health/metrics, graceful drain, SIGHUP routing reload skeleton). See [`docs/roadmap.md`](docs/roadmap.md) for delivery phases.

## Development

```bash
make test
make test-race
make vet
```

Contributions are welcome. Read [`CONTRIBUTING.md`](CONTRIBUTING.md) before opening a pull request. Report security issues according to [`SECURITY.md`](SECURITY.md).

## License

AgentBridge is available under the [MIT License](LICENSE).