aiworker-agent/AGENT-ACCESS.md

# Agent Access Guide

## 🌐 Acceso al Terminal Web (Recomendado)

El terminal web con tmux persistente está disponible en:

**https://claude.fuq.tv**

### Características:
- ✅ Terminal web con ttyd
- ✅ Sesión tmux persistente (sobrevive recargas de página)
- ✅ Claude Code ya instalado
- ✅ 10GB de almacenamiento persistente en `/workspace`
- ✅ Todas las herramientas: git, bun, node, python3, kubectl

### Cómo usar:

1. **Abre tu navegador** en: https://claude.fuq.tv
2. Verás un terminal bash
3. **Primera vez**: Claude Code te pedirá tu API key de Anthropic
4. **Trabajar**:
   ```bash
   cd /workspace
   git clone https://git.fuq.tv/admin/tu-proyecto.git
   cd tu-proyecto
   claude
   ```

### Persistencia:
- Tu sesión tmux permanece activa aunque cierres el navegador
- Puedes reconectar desde cualquier dispositivo
- El workspace en `/workspace` es persistente (PVC de 10GB)

---

## 🐳 Acceso al Pod del Agente (Alternativa)

Si prefieres acceder directamente al pod en K8s:

```bash
export KUBECONFIG=~/.kube/aiworker-config
kubectl exec -it -n agents deployment/claude-agent -- /bin/bash
```

Dentro del pod:
```bash
cd /workspace

# Primera vez: Claude Code pedirá tu API key
claude
```

---

## 🔧 Configuración MCP en Claude Code

Los endpoints MCP están disponibles en: **https://api.fuq.tv/api/mcp/**

### Herramientas disponibles:

1. **get_next_task** - Obtener siguiente tarea del backlog
   ```bash
   curl -X POST https://api.fuq.tv/api/mcp/get_next_task \
     -H "Content-Type: application/json" \
     -d '{"agentId":"'$POD_NAME'"}'
   ```

2. **update_task_status** - Actualizar estado de tarea
   ```bash
   curl -X POST https://api.fuq.tv/api/mcp/update_task_status \
     -H "Content-Type: application/json" \
     -d '{"taskId":"task-id","status":"in_progress"}'
   ```

3. **create_branch** - Crear rama Git
   ```bash
   curl -X POST https://api.fuq.tv/api/mcp/create_branch \
     -H "Content-Type: application/json" \
     -d '{"taskId":"task-id","branchName":"feature/nueva-funcionalidad"}'
   ```

4. **create_pull_request** - Crear PR en Gitea
   ```bash
   curl -X POST https://api.fuq.tv/api/mcp/create_pull_request \
     -H "Content-Type: application/json" \
     -d '{"taskId":"task-id","title":"Add feature","branchName":"feature/nueva-funcionalidad"}'
   ```

5. **ask_user_question** - Preguntar al usuario
   ```bash
   curl -X POST https://api.fuq.tv/api/mcp/ask_user_question \
     -H "Content-Type: application/json" \
     -d '{"taskId":"task-id","question":"¿Qué autenticación prefieres: JWT o sessions?"}'
   ```

### Uso en Claude Code:

Dentro de una sesión de Claude Code, puedes usar estas herramientas:

```bash
# Ejemplo: Obtener siguiente tarea
TASK=$(curl -s -X POST https://api.fuq.tv/api/mcp/get_next_task \
  -H "Content-Type: application/json" \
  -d "{\"agentId\":\"$POD_NAME\"}")

echo "$TASK" | jq .

# Trabajar en la tarea...

# Actualizar estado cuando termines
curl -X POST https://api.fuq.tv/api/mcp/update_task_status \
  -H "Content-Type: application/json" \
  -d '{"taskId":"task-id","status":"ready_to_test"}'
```

---

## 🎯 Flujo de Trabajo Típico

1. **Conectar al terminal**: https://claude.fuq.tv

2. **Obtener tarea**:
   ```bash
   POD_NAME=$(hostname)
   curl -s -X POST https://api.fuq.tv/api/mcp/get_next_task \
     -H "Content-Type: application/json" \
     -d "{\"agentId\":\"$POD_NAME\"}" | jq .
   ```

3. **Clonar proyecto**:
   ```bash
   cd /workspace
   git clone https://git.fuq.tv/admin/proyecto.git
   cd proyecto
   ```

4. **Crear branch**:
   ```bash
   git checkout -b feature/nueva-funcionalidad
   ```

5. **Trabajar con Claude Code**:
   ```bash
   claude
   # Le explicas la tarea a Claude
   # Claude hace el trabajo
   ```

6. **Commit y push**:
   ```bash
   git add .
   git commit -m "Implement nueva funcionalidad"
   git push origin feature/nueva-funcionalidad
   ```

7. **Crear PR** (desde Claude o manualmente):
   ```bash
   curl -X POST https://api.fuq.tv/api/mcp/create_pull_request \
     -H "Content-Type: application/json" \
     -d '{
       "taskId":"task-id",
       "title":"Add nueva funcionalidad",
       "branchName":"feature/nueva-funcionalidad",
       "description":"Implemented nueva funcionalidad as requested"
     }'
   ```

8. **Actualizar estado**:
   ```bash
   curl -X POST https://api.fuq.tv/api/mcp/update_task_status \
     -H "Content-Type: application/json" \
     -d '{"taskId":"task-id","status":"ready_to_test"}'
   ```

---

## 🔑 Variables de Entorno Útiles

Dentro del agente, estas variables están disponibles:

```bash
BACKEND_URL=https://api.fuq.tv
MCP_ENDPOINT=https://api.fuq.tv/api/mcp
GITEA_URL=https://git.fuq.tv
GITEA_TOKEN=159a5de2a16d15f33e388b55b1276e431dbca3f3
POD_NAME=$(hostname)
```

---

## 🆘 Troubleshooting

### Terminal no carga
- Verifica que el pod esté corriendo: `kubectl get pods -n agents`
- Revisa logs: `kubectl logs -n agents claude-terminal`

### Claude Code pide API key cada vez
- La API key se guarda en `~/.config/claude/config.json`
- En tmux persistente, se mantiene entre sesiones

### No puedo hacer git push
```bash
# Configura git credentials
git config --global user.name "Tu Nombre"
git config --global user.email "tu@email.com"

# Usa el token de Gitea
git remote set-url origin https://admin:$GITEA_TOKEN@git.fuq.tv/admin/proyecto.git
```

### Workspace se borró
- El workspace en `/workspace` del pod claude-terminal es persistente (PVC)
- El workspace del deployment claude-agent es efímero (emptyDir)
- **Recomendación**: Usa claude.fuq.tv (terminal web) para trabajo persistente