# Agent Bar — Sistema de Burbujas por Agente

## Resumen

Cada agente de Claude Code (main, ejecutor, etc.) puede tener su propia burbuja flotante en la UI. Las burbujas muestran animaciones en tiempo real cuando el agente procesa, usa herramientas, recibe notificaciones, etc.

## Arquitectura

```
Agente (hooks en settings.json)
    |
    v
POST /api/claude-status  { status, agent, tool? }
    |
    v
server/routes/claude-status.ts  (valida y reenvía)
    |
    v
Terminal Server :4103  /claude-status  (broadcast WebSocket)
    |
    v
AgentBar.vue  (escucha ws://...:4103, matchea por agent id)
    |
    v
CSS classes + keyframes  (animaciones en la burbuja)
```

## Archivos clave

| Archivo | Función |
|---|---|
| `.claude/ui.json` | Config visual del agente main |
| `.claude-ejecutor/ui.json` | Config visual de ejecutor |
| `.claude-ejecutor/settings.json` | Hooks que envían status de ejecutor |
| `server/routes/agents.ts` | API `GET /api/agents` — descubre agentes |
| `server/routes/claude-status.ts` | API `POST /api/claude-status` — recibe status |
| `server/services/terminal.ts` | Broadcast WebSocket a todos los clientes |
| `frontend/src/components/AgentBar.vue` | Burbujas flotantes + animaciones |
| `frontend/src/config/endpoints.ts` | URLs de WebSocket (dev vs HTTPS) |

---

## Cómo agregar un nuevo agente

### 1. Crear directorio `.claude-<nombre>/`

```
.claude-miagente/
  ui.json
  settings.json
  CLAUDE.md          (opcional — instrucciones del agente)
```

### 2. Configurar `ui.json`

```json
{
  "label": "Mi Agente",
  "shortLabel": "MA",
  "color": "#8b5cf6",
  "gradient": "linear-gradient(135deg, #8b5cf6, #7c3aed)",
  "terminalBg": "#0f0a1a",
  "terminalBorder": "#8b5cf6",
  "enabled": true
}
```

| Campo | Descripción |
|---|---|
| `label` | Nombre completo (tooltip, titlebar del terminal) |
| `shortLabel` | 1-3 caracteres que se muestran dentro de la burbuja |
| `color` | Color base (hex). Usado para box-shadow, glow, prompt |
| `gradient` | Fondo de la burbuja (CSS gradient) |
| `terminalBg` | Background del terminal frame mockup |
| `terminalBorder` | Color del borde del terminal frame |
| `enabled` | `true` = visible en la barra, `false` = oculto |

### 3. Configurar hooks en `settings.json`

Los hooks notifican a la UI cuando el agente hace algo. Agregar dentro de `settings.json`:

```json
{
  "env": {
    "AGENT_NAME": "miagente"
  },
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [{
          "type": "command",
          "command": "powershell -NoProfile -Command \"try { Invoke-RestMethod -Uri 'http://localhost:4101/api/claude-status' -Method POST -Body '{\\\"status\\\":\\\"processing\\\",\\\"agent\\\":\\\"miagente\\\"}' -ContentType 'application/json' -TimeoutSec 2 | Out-Null } catch {}\"",
          "timeout": 5000
        }]
      }
    ],
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [{
          "type": "command",
          "command": "powershell -NoProfile -Command \"try { Invoke-RestMethod -Uri 'http://localhost:4101/api/claude-status' -Method POST -Body '{\\\"status\\\":\\\"toolUse\\\",\\\"agent\\\":\\\"miagente\\\"}' -ContentType 'application/json' -TimeoutSec 2 | Out-Null } catch {}\"",
          "timeout": 5000
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [{
          "type": "command",
          "command": "powershell -NoProfile -Command \"try { Invoke-RestMethod -Uri 'http://localhost:4101/api/claude-status' -Method POST -Body '{\\\"status\\\":\\\"toolDone\\\",\\\"agent\\\":\\\"miagente\\\"}' -ContentType 'application/json' -TimeoutSec 2 | Out-Null } catch {}\"",
          "timeout": 5000
        }]
      }
    ],
    "Notification": [
      {
        "matcher": ".*",
        "hooks": [{
          "type": "command",
          "command": "powershell -NoProfile -Command \"try { Invoke-RestMethod -Uri 'http://localhost:4101/api/claude-status' -Method POST -Body '{\\\"status\\\":\\\"notification\\\",\\\"agent\\\":\\\"miagente\\\"}' -ContentType 'application/json' -TimeoutSec 2 | Out-Null } catch {}\"",
          "timeout": 5000
        }]
      }
    ],
    "Stop": [
      {
        "hooks": [{
          "type": "command",
          "command": "powershell -NoProfile -Command \"try { Invoke-RestMethod -Uri 'http://localhost:4101/api/claude-status' -Method POST -Body '{\\\"status\\\":\\\"idle\\\",\\\"agent\\\":\\\"miagente\\\"}' -ContentType 'application/json' -TimeoutSec 2 | Out-Null } catch {}\"",
          "timeout": 5000
        }]
      }
    ]
  }
}
```

> **Importante:** El campo `"AGENT_NAME"` en `env` es necesario para que los hooks heredados de `.claude/settings.local.json` (main) se desactiven automáticamente. Sin esto, el agente dispararía tanto sus hooks como los de main.

### 4. Resultado

La burbuja aparece automáticamente en la barra inferior. `GET /api/agents` la descubre al escanear `.claude-<nombre>/ui.json`.

---

## Status disponibles

El payload `POST /api/claude-status` acepta:

```json
{
  "status": "processing",
  "agent": "ejecutor",
  "tool": "render_vue_component"
}
```

| Status | Hook que lo dispara | Animación default | Descripción |
|---|---|---|---|
| `processing` | `UserPromptSubmit` | Pulse naranja + thinking dots | Agente procesando input |
| `toolUse` | `PreToolUse` | Flash blanco expandiéndose | Usando una herramienta |
| `toolDone` | `PostToolUse` | Reset de reading/writing | Herramienta completada |
| `reading` | `PreToolUse` (Read/Glob/Grep) | Bubble cyan + wobble + ojo | Leyendo archivos |
| `writing` | `PreToolUse` (Edit/Write) | Bubble verde + scale + lápiz | Escribiendo archivos |
| `notification` | `Notification` | Bounce vertical (4x) | Notificación del agente |
| `idle` | `Stop` | Vuelve al color original | Agente inactivo |
| `permissionRequest` | `PermissionRequest` | Rojo alert + triángulo shake | Esperando permiso |
| `sessionStart` | `SessionStart` | (solo App.vue FAB) | Sesión iniciada |

---

## Animaciones custom por agente

Cada agente puede tener sus propias animaciones sobreescribiendo las defaults con el selector `[data-agent="<id>"]` en `AgentBar.vue`.

### Ejemplo: Ejecutor

Ejecutor tiene animaciones completamente distintas definidas en el CSS de `AgentBar.vue`:

```css
/* Ejecutor Processing: Heartbeat — doble latido cardiaco */
.agent-bubble[data-agent="ejecutor"].processing {
  animation: ej-heartbeat 1.2s ease-in-out infinite !important;
}

/* Ejecutor Tool Flash: Shockwave crimson — doble anillo rojo */
.agent-bubble[data-agent="ejecutor"].tool-flash::after {
  background: rgba(239, 68, 68, 0.5) !important;
  animation: ej-shockwave 0.6s ease-out forwards !important;
}

/* Ejecutor Notification: Glitch — jitter + skew + chromatic split */
.agent-bubble[data-agent="ejecutor"].notification {
  animation: ej-glitch 0.15s steps(2) 8 !important;
}
```

| Status | Ejecutor | Default |
|---|---|---|
| `processing` | **Heartbeat** — doble latido, ember glow rojo/naranja, arcos girando | Pulse naranja suave |
| `toolUse` | **Crimson Shockwave** — doble anillo rojo expandiéndose | Flash blanco simple |
| `notification` | **Glitch** — jitter rápido, skew, split chromático cyan/red | Bounce vertical |
| `reading` | **Infrared** — glow rojo barriendo alrededor del borde | Cyan wobble |
| `writing` | **Forge** — pulso white-hot a rojo, brightness boost | Verde scale pulse |

### Contenido interno

Cuando ejecutor está en `processing`, en vez de los 3 thinking dots genéricos, muestra un **ember ring**: dos arcos concéntricos girando en direcciones opuestas (blanco/naranja y rojo/crimson).

### Agregar animaciones custom a otro agente

1. Agregar `@keyframes` con prefijo único (ej: `ma-` para "miagente")
2. Sobreescribir con `.agent-bubble[data-agent="miagente"].processing { ... }`
3. Opcionalmente agregar contenido inner custom en el template con `v-if="agent.id === 'miagente'"`

---

## Herencia de hooks y el guard AGENT_NAME

Claude Code **hereda hooks** de `.claude/settings.local.json` a todos los perfiles. Esto significa que si main tiene hooks, ejecutor también los dispara.

**Solución implementada:**

1. Cada agente secundario define `"AGENT_NAME": "<id>"` en su `env` de `settings.json`
2. Los hooks de main tienen un guard al inicio:

```
if($env:AGENT_NAME){exit}
```

3. Cuando main corre → `AGENT_NAME` no existe → hooks de main disparan normalmente
4. Cuando ejecutor corre → `AGENT_NAME="ejecutor"` → hooks de main hacen `exit` → solo disparan los hooks propios de ejecutor

---

## Probar animaciones manualmente

Se puede simular cualquier status con curl:

```bash
# Processing (heartbeat)
curl -X POST http://localhost:4101/api/claude-status \
  -H "Content-Type: application/json" \
  -d '{"status":"processing","agent":"ejecutor"}'

# Tool use (shockwave)
curl -X POST http://localhost:4101/api/claude-status \
  -H "Content-Type: application/json" \
  -d '{"status":"toolUse","agent":"ejecutor","tool":"render_vue_component"}'

# Notification (glitch)
curl -X POST http://localhost:4101/api/claude-status \
  -H "Content-Type: application/json" \
  -d '{"status":"notification","agent":"ejecutor"}'

# Reset
curl -X POST http://localhost:4101/api/claude-status \
  -H "Content-Type: application/json" \
  -d '{"status":"idle","agent":"ejecutor"}'
```

---

## API Reference

### `GET /api/agents`

Retorna array de agentes descubiertos:

```json
[
  {
    "id": "main",
    "name": "Claude Code (main)",
    "directory": ".claude",
    "files": [...],
    "uiConfig": {
      "label": "Main",
      "shortLabel": "M",
      "color": "#6366f1",
      "gradient": "linear-gradient(135deg, #6366f1, #8b5cf6)",
      "terminalBg": "#0f0a1a",
      "terminalBorder": "#6366f1",
      "enabled": false
    }
  },
  {
    "id": "ejecutor",
    "name": "Ejecutor",
    "directory": ".claude-ejecutor",
    "files": [...],
    "uiConfig": {
      "label": "Ejecutor",
      "shortLabel": "EJ",
      "color": "#ef4444",
      "gradient": "linear-gradient(135deg, #ef4444, #dc2626)",
      "terminalBg": "#0a0f1a",
      "terminalBorder": "#ef4444",
      "enabled": true
    }
  }
]
```

- `uiConfig: null` si no existe `ui.json` en el directorio del agente
- `enabled: true` por default si `ui.json` existe pero no tiene el campo

### `POST /api/claude-status`

```json
{
  "status": "processing",
  "agent": "ejecutor",
  "tool": "render_vue_component"
}
```

- `status` (requerido): uno de los valores de ClaudeStatus
- `agent` (opcional): id del agente. Default: `"main"`
- `tool` (opcional): nombre de la herramienta en uso

### `GET /api/agents/file?path=.claude-ejecutor/ui.json`

Lee un archivo de configuración de agente.

### `POST /api/agents/file?path=.claude-ejecutor/ui.json`

```json
{ "content": "{...}" }
```

Escribe un archivo de configuración. Valida JSON si el archivo termina en `.json`. Paths restringidos a `.claude/*`, `.claude-*/*`, `CLAUDE.md`, `.mcp.json`.
