Trabajar con agentes, paso a paso

1. Antes de empezar

• Un agente de código que lea AGENTS.md o CLAUDE.md: Claude Code, Codex y otros.
• idetea en tu PATH (el instalador lo hace). Los agentes usan los comandos idetea cuando los encuentran, y si no escriben los archivos ellos mismos.
• Un proyecto abierto en IDE TEA.

2. Enseña a los agentes del proyecto

1. Abre la paleta de comandos (Ctrl+Shift+P).
2. Ejecuta Interfaces: enseñar a los agentes de este proyecto.
3. El IDE escribe un bloque corto de instrucciones en el AGENTS.md y el CLAUDE.md que ya tienes, sin tocar el resto de cada archivo. Si no hay ninguno, crea un AGENTS.md y un CLAUDE.md que lo importa. Haz commit con el proyecto, o guárdalos para ti: tú eliges.

3. Ejecuta tu agente dentro del IDE

Abre la terminal (Ctrl+Shift+T) y arranca tu agente ahí, como en cualquier otro lugar:

claude        # o codex, o el agente que uses

Pide lo que quieras, como siempre. Cuando el agente necesita una decisión, usa el panel en vez del chat. También puedes decírselo directamente: "pregúntame en el panel del IDE".

4. Responde una pregunta

Cuando el agente pregunta algo, el panel Interfaces se abre con un formulario de verdad, y la barra de estado avisa que llegó una pregunta nueva.

1. Llena el formulario: opciones, casillas, campos de texto. Un botón que necesita algo antes dice qué falta.
2. Opcional: escribe un comentario para el agente (una salvedad, una pregunta de vuelta). Va junto con el botón que hagas clic.
3. Haz clic en un botón. La respuesta vuelve al agente, que sigue.

Los agentes también pueden mostrarte imágenes, galerías para elegir, sprites animados, sonidos con su forma de onda, archivos para editar (un mensaje de commit, la descripción de un PR) y listas de pasos para una prueba manual, con un botón de aprobar que espera a que hagas los pasos. Seleccionar texto, arriba de la interfaz, te deja copiar el texto.

Cada pregunta y tu respuesta quedan guardadas. Abre el Historial de las interfaces (paleta, o el enlace Historial arriba del panel) para ver primero las abiertas y luego las respondidas por día, con búsqueda. Una entrada se abre solo para ver, tal como respondiste, con la hora en que el agente la leyó.

5. Aprueba una terminal

Para ejecutar algo que deberías poder seguir (pruebas, un servidor de desarrollo, otro agente), el agente le pide una terminal al IDE. Una pestaña de pedido de terminal muestra exactamente qué se ejecutaría, y dónde.

1. Lee el comando. Ejecuta exactamente eso, con tus permisos, como si lo hubieras escrito tú.
2. Haz clic en Permitir y ejecutar, o en Rechazar. El agente sabe cuál elegiste.
3. El comando corre en su propia pestaña. Al terminar, la pestaña guarda la salida y el código hasta que presiones Enter; el agente recibe el código (y, si el comando escribió una, una respuesta en un archivo).

Cerrar la pestaña antes del final detiene el comando, y el agente se entera.

6. Sáltate la pregunta para comandos de confianza

Ponlos en tu configuración, ~/.config/idetea/config.toml:

[agents]
allow = ["npm run dev", "cargo test", "claude *"]

Una entrada es el comando exacto, o un comienzo seguido de *: ese comienzo más argumentos simples, sin ; & | $, comillas invertidas ni redirecciones.

7. Pásale trabajo a un agente ayudante

Tu agente puede arrancar otro, para una revisión o un arreglo aparte, en su propio worktree de git, para que los dos nunca editen los mismos archivos:

idetea run --title "Revisor" --worktree agent/review -- \
  claude -p 'Revisa el último commit. Escribe lo que encuentres en el archivo de $IDETEA_ANSWER.'

1. Apruebas el pedido, como en el paso 5. La pestaña muestra la rama que va a usar.
2. El IDE crea .idetea/worktrees/<nombre> en esa rama y ejecuta al ayudante ahí.
3. El ayudante escribe su respuesta en $IDETEA_ANSWER; tu agente principal la lee y trae el código de la rama de la forma habitual (con tu prueba y tu aprobación).
4. Al terminar, el worktree se borra si no tiene nada sin commit. La rama siempre queda.

8. Los comandos idetea

Los agentes los usan cuando idetea está en el PATH. Cada uno hace la ida y vuelta completa en una llamada. También puedes probarlos en la terminal del IDE.

Ejecuta cualquiera solo para ver todas las opciones.

9. Empieza un proyecto nuevo con un agente

Proyecto: nuevo… en la paleta (o idetea new) crea la carpeta, ejecuta git init, instala las skills de agente de una plantilla (vacía, Rust, sitio web, Python, FastAPI), escribe un pedido inicial en AGENTS.md y puede abrir tu agente en una terminal del IDE para que lo apruebes:

idetea new my-app --modelo rust --descricao "un conversor de unidades" --agente claude

10. Por dentro

Todo son archivos simples en la carpeta .idetea/ del proyecto. Estos quedan fuera de git:

• .idetea/ui/<nombre>.json: una pregunta; tu respuesta va a .idetea/ui/responses/.
• .idetea/agents/<nombre>.json: un pedido de terminal; su avance en <nombre>.status.json.
• .idetea/state.json: lo que tienes abierto, para idetea status.
• .idetea/history/: cada pregunta y respuesta, hasta que lo borres.

Así cualquier agente que lea y escriba archivos puede usarlo, y tú puedes leer cada mensaje. Los formatos completos (por ahora en portugués): el formato de las Interfaces y terminales de agente.