ClusterBridge OpenCode Plugin

HTTP API bridge for OpenCode - Manage Agents, Skills, and execute Shell commands via REST API.

Features

• 🚀 HTTP REST API - Full REST endpoints for OpenCode management
• 🤖 Agent Management - CRUD operations for OpenCode agents
• 📚 Skill Management - CRUD operations for Agent skills
• 💻 Shell Execution - Execute shell commands with streaming support
• 📊 Node Status - System information, memory, and CPU stats
• 🔄 Real-time Events - WebSocket support for live updates
• 🔒 Type Safe - Full TypeScript support

Installation

# Install via npm
npm install clusterbridge-opencode-plugin

# Or via bun
bun add clusterbridge-opencode-plugin

Usage

Add to your OpenCode config (~/.config/opencode/opencode.json or project opencode.json):

{
  "plugin": ["clusterbridge-opencode-plugin"]
}

The plugin will automatically start an HTTP server on port 8080 when OpenCode loads.

API Endpoints

Health Check

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /health | Server health status |

Test Example:

curl http://localhost:8080/health

Response:

{
  "success": true,
  "data": {
    "status": "ok",
    "timestamp": 1772070711820
  },
  "meta": {
    "timestamp": 1772070711820,
    "requestId": "req-..."
  }
}

Version Info

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/version | Get OpenCode and plugin version info |

Test Example:

curl http://localhost:8080/api/version

Response:

{
  "success": true,
  "data": {
    "version": {
      "opencode": {
        "version": "unknown",
        "pluginApi": "^1.0.0"
      },
      "plugin": {
        "name": "clusterbridge-opencode-plugin",
        "version": "1.0.3"
      },
      "runtime": {
        "name": "Bun",
        "version": "1.3.6"
      }
    }
  },
  "meta": {
    "timestamp": 1772070711820,
    "requestId": "req-..."
  }
}

Node Status

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/node/status | Get raw node status (system, memory, CPU) | | GET | /api/node | Get formatted node status with human-readable values |

Test Example - Raw Status:

curl http://localhost:8080/api/node/status

Response:

{
  "success": true,
  "data": {
    "status": {
      "system": {
        "platform": "darwin",
        "release": "25.4.0",
        "arch": "arm64",
        "hostname": "MacBook-Pro.local",
        "uptime": 172553,
        "loadavg": [5.13, 5.79, 6.41]
      },
      "memory": {
        "total": 34359738368,
        "free": 467107840,
        "used": 33892630528,
        "usagePercent": 98.64
      },
      "cpu": {
        "model": "Apple M2 Pro",
        "speed": 2400,
        "cores": 12,
        "usage": [48.08, 45.85, 43.47, 41.52, 13.77, 8.08, 4.94, 3.26, 13.69, 8.06, 4.91, 3.23]
      },
      "timestamp": 1772070711820
    }
  },
  "meta": {
    "timestamp": 1772070711820,
    "requestId": "req-..."
  }
}

Test Example - Formatted Status:

curl http://localhost:8080/api/node

Response:

{
  "success": true,
  "data": {
    "node": {
      "system": {
        "platform": "darwin",
        "release": "25.4.0",
        "arch": "arm64",
        "hostname": "MacBook-Pro.local",
        "uptime": 172553,
        "uptimeFormatted": "1d 23h 55m 53s",
        "loadavg": [5.13, 5.79, 6.41]
      },
      "memory": {
        "total": 34359738368,
        "totalFormatted": "32.00 GB",
        "free": 467107840,
        "freeFormatted": "445.59 MB",
        "used": 33892630528,
        "usedFormatted": "31.56 GB",
        "usagePercent": 98.64
      },
      "cpu": {
        "model": "Apple M2 Pro",
        "speed": 2400,
        "cores": 12,
        "usage": [48.08, 45.85, 43.47, 41.52, 13.77, 8.08, 4.94, 3.26, 13.69, 8.06, 4.91, 3.23]
      },
      "timestamp": 1772070711820
    }
  },
  "meta": {
    "timestamp": 1772070711820,
    "requestId": "req-..."
  }
}

Agents

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/agents | List all agents | | POST | /api/agents | Create new agent | | GET | /api/agents/:id | Get agent details | | PUT | /api/agents/:id | Update agent | | DELETE | /api/agents/:id | Delete agent |

Test Example - List Agents:

curl http://localhost:8080/api/agents

Test Example - Create Agent:

curl -X POST http://localhost:8080/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "description": "Reviews code for quality",
    "mode": "subagent",
    "prompt": "You are a code reviewer..."
  }'

Test Example - Get Agent:

curl http://localhost:8080/api/agents/code-reviewer

Test Example - Update Agent:

curl -X PUT http://localhost:8080/api/agents/code-reviewer \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "prompt": "You are an expert code reviewer..."
  }'

Test Example - Delete Agent:

curl -X DELETE http://localhost:8080/api/agents/code-reviewer

Skills

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/skills | List all skills | | POST | /api/skills | Create new skill | | GET | /api/skills/:id | Get skill details | | PUT | /api/skills/:id | Update skill | | DELETE | /api/skills/:id | Delete skill |

Test Example - List Skills:

curl http://localhost:8080/api/skills

Test Example - Create Skill:

curl -X POST http://localhost:8080/api/skills \
  -H "Content-Type: application/json" \
  -d '{
    "name": "git-helper",
    "description": "Git command helper",
    "content": "You help users with git commands..."
  }'

Test Example - Get Skill:

curl http://localhost:8080/api/skills/git-helper

Test Example - Update Skill:

curl -X PUT http://localhost:8080/api/skills/git-helper \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Advanced git helper"
  }'

Test Example - Delete Skill:

curl -X DELETE http://localhost:8080/api/skills/git-helper

Shell

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /api/shell/execute | Execute shell command | | GET | /api/shell/:id/status | Get execution status | | GET | /api/shell/history | Get execution history | | DELETE | /api/shell/:id | Kill running process |

Test Example - Execute Command:

curl -X POST http://localhost:8080/api/shell/execute \
  -H "Content-Type: application/json" \
  -d '{
    "command": "ls -la",
    "cwd": "/tmp",
    "timeout": 30000
  }'

Response:

{
  "success": true,
  "data": {
    "id": "shell-abc123",
    "command": "ls -la",
    "status": "completed",
    "exitCode": 0,
    "stdout": "total 0\ndrwxrwxrwt...",
    "stderr": "",
    "startTime": 1772070711820,
    "endTime": 1772070711830
  },
  "meta": {
    "timestamp": 1772070711830,
    "requestId": "req-..."
  }
}

Test Example - Get Execution Status:

curl http://localhost:8080/api/shell/shell-abc123/status

Test Example - Get History:

curl "http://localhost:8080/api/shell/history?limit=10"

Test Example - Kill Process:

curl -X DELETE http://localhost:8080/api/shell/shell-abc123

WebSocket

Connect to WebSocket for real-time events:

const ws = new WebSocket('ws://localhost:8080');

ws.onopen = () => {
  console.log('Connected to ClusterBridge');
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data.type, data.data);
};

Events:

• connected - Initial connection
• session.created - New session created
• session.updated - Session updated
• tool.execute.before - Tool execution started
• tool.execute.after - Tool execution completed

Configuration

Create .opencode/clusterbridge.json:

{
  "port": 8080,
  "hostname": "127.0.0.1",
  "auth": {
    "enabled": false,
    "token": "your-secret-token"
  }
}

With Authentication

{
  "port": 8080,
  "hostname": "127.0.0.1",
  "auth": {
    "enabled": true,
    "token": "my-secret-token-123"
  }
}

Test with Auth:

curl http://localhost:8080/api/version \
  -H "Authorization: Bearer my-secret-token-123"

Error Responses

All errors follow this format:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Agent not found: my-agent",
    "details": null
  },
  "meta": {
    "timestamp": 1772070711820,
    "requestId": "req-..."
  }
}

Common Error Codes:

• NOT_FOUND - Resource not found (404)
• VALIDATION_ERROR - Invalid input (400)
• UNAUTHORIZED - Authentication required (401)
• UNKNOWN_ERROR - Internal server error (500)

License

MIT