Agents API Reference

Agent management is exposed through JSON-RPC bridge methods (for the frontend and programmatic access) and CLI commands (for humans).

Bridge Methods (JSON-RPC)

These methods are registered in gateway/server-bridge-methods-agents.js and wrap the existing CLI logic.

`agents.list`

List all agents with status and health info.

// Request
{ method: "agents.list" }

// Response
{
  "agents": [
    {
      "id": "marketing-manager",
      "name": "Marketing Manager",
      "role": "manager",
      "model": "claude-opus-4-6",
      "workspace": "/path/to/workspace",
      "status": "active",
      "health": { "ok": true, "issues": [] },
      "identity": { "name": "Marketing Manager", "emoji": "📊" },
      "bindings": ["slack", "discord"]
    }
  ]
}

`agents.get`

Get detailed agent info including health check results.

// Request
{ method: "agents.get", params: { agentId: "marketing-manager" } }

// Response
{
  "agent": { /* full agent config */ },
  "health": {
    "ok": true,
    "checks": [
      { "name": "workspace", "ok": true },
      { "name": "agents_md", "ok": true },
      { "name": "soul_md", "ok": true },
      { "name": "config", "ok": true }
    ]
  }
}

`agents.create`

Create a new agent with role and optional config overrides.

// Request
{
  method: "agents.create",
  params: {
    agentId: "ad-optimizer",
    role: "worker",
    workspace: "/path/to/workspace",
    config: {
      model: "claude-sonnet-4-6",
      team: "marketing"
    }
  }
}

// Response
{ "agent": { /* created agent entry */ }, "scaffolded": true }

`agents.update`

Update an existing agent's config.

// Request
{
  method: "agents.update",
  params: {
    agentId: "marketing-manager",
    config: {
      model: "claude-opus-4-6",
      heartbeat: { "every": "1h" }
    }
  }
}

// Response
{ "agent": { /* updated agent entry */ } }

`agents.delete`

Remove an agent. Optionally clean up workspace.

// Request
{
  method: "agents.delete",
  params: {
    agentId: "old-worker",
    cleanWorkspace: true  // Also trash workspace directory
  }
}

// Response
{ "deleted": true, "agentId": "old-worker" }

`agents.doctor`

Run health checks on a specific agent or all agents.

// Request
{ method: "agents.doctor", params: { agentId: "marketing-manager" } }

// Response
{
  "ok": true,
  "checks": [
    { "name": "workspace_exists", "ok": true },
    { "name": "agents_md", "ok": true },
    { "name": "soul_md", "ok": true },
    { "name": "config_valid", "ok": true },
    { "name": "model_available", "ok": true }
  ]
}

`agents.roles`

Get available roles and their defaults.

// Request
{ method: "agents.roles" }

// Response
{
  "roles": {
    "coordinator": { "model": "claude-opus-4-6", "heartbeat": { "every": "30m" }, ... },
    "manager": { "model": "claude-opus-4-6", "heartbeat": { "every": "2h" }, ... },
    "worker": { "model": "claude-sonnet-4-6", "heartbeat": null, ... },
    "research": { "model": "claude-opus-4-6", "heartbeat": { "every": "4h" }, ... },
    "assistant": { "model": "claude-opus-4-6", "heartbeat": { "every": "2h" }, ... }
  }
}

CLI Commands

`reeve agents list`

List all agents with identity, workspace, model, and channel bindings.

reeve agents list

Output:

  marketing-manager  📊 Marketing Manager
    Role: manager | Model: claude-opus-4-6
    Workspace: /Users/matt/reeve-workspaces/marketing
    Channels: slack, discord
    Heartbeat: every 2h

  frontend-worker  ⚡ Frontend Dev
    Role: worker | Model: claude-sonnet-4-6
    Workspace: /Users/matt/reeve-workspaces/frontend
    Channels: (none)
    Heartbeat: disabled

`reeve agents add`

Interactive wizard to create a new agent.

reeve agents add
reeve agents add --name my-agent --role worker --workspace ~/ws/my-agent

`reeve agents inspect <agent-id>`

Show detailed config and health status.

reeve agents inspect marketing-manager

`reeve agents doctor [--fix]`

Health check for all agents. With --fix, auto-repairs missing files and config issues.

reeve agents doctor
reeve agents doctor --fix

`reeve agents delete <agent-id>`

Remove an agent from config. Optionally trashes workspace and session data.

reeve agents delete old-worker

`reeve agents set-identity <agent-id>`

Set display name, emoji, and theme.

reeve agents set-identity marketing-manager --name "MarketBot" --emoji "🚀" --theme purple

API Reference

On this page