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:

   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:

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

Dentro del pod:

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

   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

   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

   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

   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

   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:

# 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:

   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:

   cd /workspace
   git clone https://git.fuq.tv/admin/proyecto.git
   cd proyecto
   

4. Crear branch:

   git checkout -b feature/nueva-funcionalidad
   

5. Trabajar con Claude Code:

   claude
   # Le explicas la tarea a Claude
   # Claude hace el trabajo
   

6. Commit y push:

   git add .
   git commit -m "Implement nueva funcionalidad"
   git push origin feature/nueva-funcionalidad
   

7. Crear PR (desde Claude o manualmente):

   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:

   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:

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

# 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