Spaces:
Sleeping
Sleeping
File size: 3,401 Bytes
f762929 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 | # Direct CLI Integration
Connect CLI tools (Claude Code, Codex, custom agents) directly to Mission Control without a gateway.
## Quick Start
### 1. Register a connection
```bash
curl -X POST http://localhost:3000/api/connect \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"tool_name": "claude-code",
"tool_version": "1.0.0",
"agent_name": "my-agent",
"agent_role": "developer"
}'
```
Response:
```json
{
"connection_id": "550e8400-e29b-41d4-a716-446655440000",
"agent_id": 42,
"agent_name": "my-agent",
"status": "connected",
"sse_url": "/api/events",
"heartbeat_url": "/api/agents/42/heartbeat",
"token_report_url": "/api/tokens"
}
```
- If `agent_name` doesn't exist, it's auto-created.
- Previous connections for the same agent are automatically deactivated.
### 2. Heartbeat loop
Send heartbeats to stay alive and optionally report token usage:
```bash
curl -X POST http://localhost:3000/api/agents/42/heartbeat \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"connection_id": "550e8400-e29b-41d4-a716-446655440000",
"token_usage": {
"model": "claude-sonnet-4",
"inputTokens": 1500,
"outputTokens": 800
}
}'
```
Response includes work items (mentions, assigned tasks, notifications) plus `"token_recorded": true` if usage was reported.
Recommended heartbeat interval: **30 seconds**.
### 3. Subscribe to events (SSE)
```bash
curl -N http://localhost:3000/api/events \
-H "x-api-key: YOUR_API_KEY"
```
Receives real-time events: task assignments, mentions, agent status changes, etc.
### 4. Report token usage
For bulk token reporting (separate from heartbeat):
```bash
curl -X POST http://localhost:3000/api/tokens \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"model": "claude-sonnet-4",
"sessionId": "my-agent:chat",
"inputTokens": 5000,
"outputTokens": 2000
}'
```
### 5. Disconnect
```bash
curl -X DELETE http://localhost:3000/api/connect \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"connection_id": "550e8400-e29b-41d4-a716-446655440000"}'
```
Sets the agent offline if no other active connections exist.
## API Reference
| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| POST | `/api/connect` | operator | Register CLI connection |
| GET | `/api/connect` | viewer | List all connections |
| DELETE | `/api/connect` | operator | Disconnect by connection_id |
| POST | `/api/agents/{id}/heartbeat` | operator | Heartbeat with optional token reporting |
| GET | `/api/events` | viewer | SSE event stream |
| POST | `/api/tokens` | operator | Report token usage |
## Connection Lifecycle
```
POST /api/connect → Agent set online
↓
Heartbeat loop (30s) → Reports tokens, receives work items
↓
DELETE /api/connect → Agent set offline (if no other connections)
```
## Notes
- Each agent can only have one active connection at a time. A new `POST /api/connect` for the same agent deactivates the previous connection.
- The `sessionId` format for token reporting follows `{agentName}:{chatType}` convention (e.g., `my-agent:chat`, `my-agent:cli`).
- Heartbeat responses include pending work items (assigned tasks, mentions, notifications) so CLI tools can act on them.
|