# Manual avanzado — AiAgentSetups

Guía completa de uso con **kiro-gateway + Sonnet 4.5** y alternativas.

---

## 1. ¿Qué programa (IDE) deberías usar?

### Recomendación por perfil

| Perfil | Programa | Por qué |
|--------|----------|---------|
| **Mejor equilibrio** | **VS Code + Cline** | Agente completo, localhost sin túnel, estable |
| **Ya usas Cursor** | **Cursor + Cline** | Mismo flujo agente; extensión Cline dentro de Cursor |
| **Máximo poder terminal** | **Claude Code CLI** | Agente oficial Anthropic, tools + subagentes |
| **Chat + completion ligero** | **Continue** | Menos “agente autónomo”, más asistente |
| **Solo chat Cursor nativo** | **Cursor Agent** | Requiere proyecto **03** (túnel HTTPS); más frágil |
| **Automatización YouTube/SaaS** | Proyectos **02** | Otro propósito, no Sonnet Kiro |

### Jerarquía recomendada (de más a menos potente para coding agent)

```
1. Claude Code CLI     → agente terminal, máxima autonomía
2. Cline (VS Code)     → agente visual, muy similar a Cursor Agent
3. Continue            → asistente con tools limitados
4. Cursor Agent nativo → solo si insistes en Cursor UI sin Cline
```

### Instalar extensiones

| Extensión | ID marketplace | Uso |
|-----------|----------------|-----|
| **Cline** | `saoudrizwan.claude-dev` | Agente principal |
| **Continue** | `continue.continue` | Alternativa chat |
| **Claude Code** | terminal `npm i -g @anthropic-ai/claude-code` | CLI agente |

---

## 2. Arquitectura

```
┌─────────────┐     HTTP local      ┌──────────────────┐     API Kiro    ┌─────────┐
│ IDE/CLI     │ ──────────────────► │ kiro-gateway     │ ──────────────► │ Kiro    │
│ Cline       │  127.0.0.1:PUERTO  │ (proxy Anthropic)│                 │ Sonnet  │
│ Claude Code │                     │ PROXY_API_KEY    │                 │ 4.5     │
└─────────────┘                     └──────────────────┘                 └─────────┘
                                              ▲
                                              │
                              kiro-auth-token.json (tras kiro login)
```

---

## 3. Puertos y conflictos

### Puerto por defecto: `8000`

Si ves `error 10048` / "solo se permite un uso de cada dirección":

**Causa habitual:** ya tienes un `python.exe` con kiro-gateway escuchando (no es otro programa malicioso).

### Ver quién usa el puerto

```powershell
cd C:\xampp\htdocs\AiAgentSetups\01-kiro-sonnet-agent
.\scripts\show-port-owner.ps1 -Port 8000
```

### Opción A — Usar el gateway que ya corre

Si el proceso es `python` del gateway → **no arranques otro**. Usa Cline o `claude` directamente.

### Opción B — Cambiar a puerto libre

```powershell
.\scripts\set-gateway-port.ps1 -Auto
# o puerto fijo:
.\scripts\set-gateway-port.ps1 -Port 8001
.\start-gateway.ps1
.\verify.ps1
```

Esto actualiza `.env`, `state.json` y **todos los IDEs** automáticamente.

### Opción C — Matar el proceso anterior

```powershell
Stop-Process -Id 23668 -Force   # sustituye por el PID real
.\start-gateway.ps1
```

---

## 4. Uso avanzado por herramienta

### 4.1 Cline (VS Code / Cursor) — Agente visual

**Config automática** (ya aplicada por `configure-ides.ps1`):

| Campo | Valor |
|-------|-------|
| Provider | Anthropic |
| Base URL | `http://127.0.0.1:PUERTO` |
| API Key | `PROXY_API_KEY` (ver `config/state.json`) |
| Model | `claude-sonnet-4-5` |

**Flujo de trabajo agente:**

1. Abre carpeta del proyecto en VS Code/Cursor.
2. Panel Cline → modo **Act** (no solo chat).
3. Ejemplos de prompts:
   - *"Refactoriza auth.php para usar prepared statements"*
   - *"Añade tests PHPUnit para UserService"*
   - *"Explica el flujo de checkout y dibuja un diagrama"*
4. Cline pedirá permiso antes de editar archivos o ejecutar comandos → aprueba o deniega.

**Modelos disponibles vía Kiro** (según tu tier):

- `claude-sonnet-4-5` — principal (coding)
- `claude-sonnet-4-6` — más nuevo
- `claude-haiku-4-5` — rápido/barato
- `claude-opus-4-6` — si tu tier lo incluye

**Cambiar modelo:** Settings Cline → Model ID.

---

### 4.2 Claude Code CLI — Agente terminal

```powershell
# Gateway debe estar corriendo
cd C:\tu\proyecto
claude
```

**Comandos internos útiles:**

| Comando | Función |
|---------|---------|
| `/status` | Ver base URL y modelo |
| `/model` | Cambiar modelo (Sonnet/Opus/Haiku) |
| `/help` | Ayuda |

**Variables** (en `~/.claude/settings.json`, ya configuradas):

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8000",
    "ANTHROPIC_AUTH_TOKEN": "tu-PROXY_API_KEY",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5",
    "ENABLE_TOOL_SEARCH": "true"
  }
}
```

**Casos de uso avanzados:**

- Refactors multi-archivo con contexto completo del repo.
- Ejecutar tests y corregir fallos en bucle.
- Generar documentación desde código existente.

---

### 4.3 Continue — Asistente con contexto

Archivo: `C:\Users\Paterna\.continue\config.json`

- Chat lateral con contexto del archivo abierto.
- Menos autonomía que Cline; mejor para preguntas puntuales y completions.

---

### 4.4 Cursor Agent nativo (proyecto 03)

Solo si quieres el **agente integrado de Cursor** sin Cline:

```powershell
cd C:\xampp\htdocs\AiAgentSetups\03-cursor-tunnel-agent
.\install.ps1 -Backend kiro
.\start-tunnel.ps1   # ngrok → URL HTTPS pública
```

Cursor Settings → Override Base URL → URL del túnel.

**Limitación:** más frágil; los servidores de Cursor deben alcanzar tu proxy.

---

## 5. Proyecto 02 — Sin Kiro (alternativa gratuita)

```powershell
cd C:\xampp\htdocs\AiAgentSetups\02-free-agent-zero-cost
.\install.ps1 -Mode nim      # NVIDIA NIM gratis
.\start-proxy.ps1            # puerto 8082
```

- **No es Sonnet 4.5 real** — usa GLM/Nemotron u OpenRouter free.
- Misma interfaz agente (Claude Code + Cline).

Modo Puter:

```powershell
.\install.ps1 -Mode puter
# token de puter.com/dashboard
```

---

## 6. API directa (sin IDE) — para scripts

```powershell
$key = (Get-Content config\state.json | ConvertFrom-Json).proxyApiKey
$url = (Get-Content config\state.json | ConvertFrom-Json).gatewayUrl

$body = @{
  model = 'claude-sonnet-4-5'
  max_tokens = 1024
  messages = @(@{ role = 'user'; content = 'Hola' })
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Uri "$url/v1/messages" -Method Post `
  -Headers @{
    'Authorization' = "Bearer $key"
    'anthropic-version' = '2023-06-01'
    'content-type' = 'application/json'
  } -Body $body
```

**Endpoints útiles:**

| URL | Uso |
|-----|-----|
| `/health` | Estado |
| `/docs` | Swagger UI |
| `/v1/models` | Listar modelos |
| `/v1/messages` | API Anthropic |
| `/v1/chat/completions` | API OpenAI-compatible |

---

## 7. Mantenimiento

| Tarea | Comando |
|-------|---------|
| Verificar todo | `.\verify.ps1` |
| Re-detectar credenciales Kiro | `.\scripts\detect-kiro-credentials.ps1` |
| Reconfigurar IDEs | `.\configure-ides.ps1` |
| Cambiar puerto | `.\scripts\set-gateway-port.ps1 -Auto` |
| Tras `kiro login` de nuevo | detect + configure-ides |
| Ver API key | `config\state.json` → `proxyApiKey` |

---

## 8. Solución de problemas

| Síntoma | Solución |
|---------|----------|
| Puerto 8000 ocupado | `show-port-owner.ps1` o `set-gateway-port.ps1 -Auto` |
| 401 Unauthorized | `configure-ides.ps1` + verificar `PROXY_API_KEY` |
| No credentials | `kiro login` → `detect-kiro-credentials.ps1` |
| Modelo no disponible | Probar `claude-sonnet-4-6` o listar `/v1/models` |
| Cline no conecta | Reiniciar VS Code; revisar Base URL en settings |
| Tokens Kiro agotados | Esperar reset tier Kiro o usar proyecto 02 |

---

## 9. Seguridad

- Gateway en `127.0.0.1` solamente — no expongas a Internet sin túnel consciente.
- `PROXY_API_KEY` protege tu proxy local; no la compartas.
- No commitear `.env` ni `state.json` con keys.

---

## 10. Resumen ejecutivo

**Para ti, hoy:**

1. **Deja corriendo** el gateway en 8000 (o cambia puerto con `set-gateway-port.ps1 -Auto`).
2. **Usa VS Code + Cline** o **`claude` en terminal** — son las opciones más potentes y estables.
3. **Modelo:** `claude-sonnet-4-5`.
4. **No necesitas Cursor Agent nativo** salvo que quieras la UI específica de Cursor (entonces proyecto 03).