Todo sobre tu villa.

Pixlage convierte tus agentes de código en villagers de pixel art que viven en tu pantalla. Esta página muestra cómo instalarlo, conectar tus agentes y usar cada función. En tu equipo, la app se llama Agent Village.

Instalar

Hay dos formas de instalarlo. Las dos instalan la misma app y siempre la versión más reciente.

Requisitos

• macOS 12 (Monterey) o más reciente, en Macs con Apple Silicon o Intel.
• Windows 10 u 11, de 64 bits.
• Linux x64: paquete .deb para Ubuntu, Debian y derivados, o AppImage para las demás distribuciones.
• Al menos un agente de código instalado, como Claude Code o Codex. Mira la lista en Integraciones.

Desde la terminal

curl -fsSL https://pixlage.app/install.sh | sh

irm https://pixlage.app/install.ps1 | iex

curl -fsSL https://pixlage.app/install.sh | sh

Con el instalador

sudo apt install ./Agent-Village-Linux.deb

chmod +x Agent-Village-Linux.AppImage
./Agent-Village-Linux.AppImage

¿Por qué aparece un aviso de seguridad?

macOS y Windows muestran este aviso para toda app que todavía no tiene una firma digital de pago de Apple o de Microsoft. El aviso no significa que se haya encontrado un problema en la app, solo que el sistema no reconoce quién la publicó.

El sistema solo hace esta comprobación en archivos marcados como descargados por un navegador. Los archivos descargados con curl o PowerShell no reciben esa marca, por eso la instalación desde la terminal no muestra el aviso. La app instalada es exactamente la misma.

Actualizar

La app busca una versión nueva al abrirse, cada 6 horas y cuando haces clic en Buscar actualizaciones… en el menú del icono. Tus villagers, mesas y ajustes se conservan.

• Windows y Linux: la actualización se descarga en segundo plano y se instala cuando sales de la app, o en el momento con Reiniciar para actualizar en el menú. Con el .deb, el sistema pide tu contraseña.
• macOS: la app avisa de que hay una versión nueva. El aviso y la opción Descargar Agent Village… del menú abren el .dmg nuevo: arrástralo a Aplicaciones sobre el anterior. O ejecuta otra vez el comando de la terminal.

Desinstalar

1. Abre Personajes y ajustes… en el menú del icono, ve a la pestaña Conexiones y haz clic en Desconectar en cada agente. Esto quita los hooks de Pixlage de los archivos de configuración de tus agentes. Si te saltas este paso no se rompe nada: los hooks notan que la app no está abierta y terminan al instante.

2. Sal de la app desde el menú (Salir de Agent Village) y elimínala:

   • macOS: arrastra Agent Village de Aplicaciones a la Papelera.
   • Windows: Configuración › Aplicaciones › Aplicaciones instaladas › Agent Village › Desinstalar.
   • Linux: sudo apt remove agent-village, o borra el archivo AppImage.

3. Si también quieres borrar tus villagers y ajustes, elimina la carpeta de datos.

Primeros pasos

El icono y su menú

Pixlage no tiene ventana principal ni icono en el Dock. Vive en un icono de la barra de menús (macOS) o de la bandeja del sistema (Windows y Linux). En macOS, el número de solicitudes que te esperan aparece junto al icono; en Windows, en la información que se ve al pasar el ratón.

El menú del icono muestra los agentes que están en la villa y tiene:

• Mostrar villa: muestra u oculta los personajes en pantalla.
• Nueva tarea…: abre la ventana para enviar una tarea.
• Personajes y ajustes…: abre el editor, con las pestañas Villagers, Mesas, Conexiones y Ajustes.
• Crear agentes de demostración: cuatro agentes de mentira, uno en cada estado.
• Buscar actualizaciones… y Salir de Agent Village.

La ventana de la villa es transparente y queda por encima de todo, pero solo captura el ratón cuando el puntero está sobre un personaje, una mesa o una tarjeta. En el resto de la pantalla, haces clic en las apps de abajo como siempre.

Conectar tus agentes

Pixlage sabe lo que hace cada agente gracias a los hooks: pequeños comandos que el propio agente ejecuta en cada paso. Para instalarlos:

1. Abre Personajes y ajustes… y ve a la pestaña Conexiones. Muestra los agentes encontrados en tu equipo.

2. Haz clic en Conectar en cada agente que uses. La tarjeta dice Conectado cuando todos los eventos están instalados, Conectado parcialmente cuando falta alguno (haz clic en Reparar) y Sin conectar cuando no hay ninguno.

3. Abre un chat nuevo en el agente. Los agentes leen los hooks cuando empieza una sesión, así que un chat que ya estaba abierto tiene que reiniciarse.

Los hooks de otras herramientas se conservan, y Pixlage hace una copia de seguridad de cada archivo antes de cambiarlo por primera vez (<archivo>.agent-village-backup). Si la app está cerrada, el hook se rinde en menos de un segundo y el agente sigue con normalidad.

Probar sin un agente

¿Quieres ver cómo funciona antes de conectar nada? Haz clic en Crear agentes de demostración en el menú del icono (o en Pruébalo, en la pestaña Ajustes). Aparecen cuatro agentes de mentira, uno en cada estado. Para quitarlos, usa Eliminar en la tarjeta de cada uno.

Usar la villa

Qué significa cada animación

Cada agente abierto se convierte en un villager. Su animación muestra lo que está haciendo en ese momento:

El villager se va cuando cierras el chat en el IDE. Los chats que ya estaban abiertos antes de la app (en Claude Code y Codex) también reciben un villager.

La tarjeta del villager

Haz clic en un villager para abrir su tarjeta. La tarjeta muestra la tarea actual, las últimas acciones y las solicitudes abiertas. Desde ella también cambias el aspecto del villager, eliges su mesa, envías mensajes (en Claude Code y Codex) y lo quitas de la villa.

Arrastra un villager para dejarlo donde quieras en la pantalla. Recuerda el sitio.

Aprobar solicitudes

Cuando el agente pide permiso para ejecutar un comando o editar un archivo, el villager salta con un "!" y la tarjeta muestra la solicitud. Respondes ahí mismo:

• Permitir: permite solo esta solicitud.
• Permitir siempre: la permite y guarda la regla para solicitudes parecidas. Solo en Claude Code.
• Denegar: rechaza la solicitud.
• Responder en el IDE: devuelve la pregunta a la ventana habitual del agente.

Si no respondes en 300 segundos (puedes cambiarlo en Ajustes), la solicitud vuelve al IDE. Si respondes primero en el IDE, la solicitud desaparece de la tarjeta.

Aprobar desde el villager funciona en Claude Code, Codex, Qwen Code y Copilot CLI. Con los demás agentes, el villager muestra la solicitud y respondes en la propia herramienta.

Preguntas del agente

Cuando Claude Code hace una pregunta con opciones, la tarjeta muestra las opciones como botones (una o varias, según la pregunta) y un campo para una respuesta libre. Envía tus respuestas u omite la pregunta. En sesiones del IDE, gana quien responda primero: si respondes desde la villa, el diálogo del IDE se cierra solo.

Nombres

Cada villager usa el título del chat, el mismo que el IDE muestra en su lista de conversaciones. Hasta que exista el título (unos segundos después del primer mensaje), usa el nombre del proyecto. En Claude Code, un nombre puesto con /rename tiene prioridad.

Los nombres aparecen en chapas bajo los personajes. Para una pantalla más limpia, desactiva Mostrar nombres de agentes bajo los personajes en Ajustes: así el nombre solo aparece al pasar el ratón o con la tarjeta abierta.

La cinta Villa

En el borde derecho de la pantalla hay una cinta que dice Villa. Pasa el ratón por encima para abrir un menú rápido:

• Añadir: Nueva tarea, Nueva mesa y Nuevo aspecto.
• En pantalla: interruptores para mostrar la villa, los nombres de agentes y las alertas de aprobación.
• Abrir: atajos a las pestañas del editor.

Cuando algún agente te necesita, la cinta se pone dorada y muestra cuántas solicitudes esperan.

Enviar tareas

Puedes empezar un trabajo nuevo en Claude Code o Codex sin abrir el IDE. La tarea se ejecuta en segundo plano con tu sesión del CLI, sin API key.

Nueva tarea

Abre la ventana Nueva tarea desde el menú del icono, desde el enlace "Nueva tarea" de cualquier tarjeta o con el atajo, que funciona desde cualquier app:

Elige el agente, la carpeta del proyecto, el villager, los permisos y, si quieres, el modelo y el esfuerzo de razonamiento. En Claude Code, estos campos empiezan con lo que Claude usaría en ese proyecto. Escribe el prompt y envíalo.

El villager aparece al instante. Cuando la tarea termina, la tarjeta muestra el informe final del agente y una notificación te avisa (puedes desactivarla en Ajustes).

Seguir la conversación

La caja de mensajes está al pie de la tarjeta. Desde ella:

• envías el siguiente mensaje de la misma conversación;
• adjuntas archivos con el clip, pegándolos o soltándolos. Las imágenes (png, jpg, gif y webp, hasta 5 MB) llegan al modelo como imágenes;
• cambias el modelo, el esfuerzo de razonamiento y el modo de permisos, desde el botón que resume tu elección (p. ej. "Sonnet · esfuerzo low · Aceptar ediciones automáticamente"). La elección vale desde el siguiente mensaje.

Los mensajes enviados mientras el agente trabaja entran en una cola. Detener interrumpe el turno actual y vacía la cola. Las tareas siguen ahí después de reiniciar la app; Eliminar pide un segundo clic, porque olvida la conversación.

Hablar con un chat abierto en el IDE

La tarjeta de cualquier agente de Claude Code o Codex tiene la caja de mensajes, incluida la de un chat que abriste en el IDE. El mensaje entra en la misma conversación.

• Si el agente está en medio de un paso, el mensaje espera a que termine, para que los dos no escriban a la vez. Cancelar cola deja de esperar.
• El panel del IDE no se actualiza en directo: los mensajes enviados desde la villa aparecen allí cuando vuelves a abrir la conversación desde el historial.

Modos de permisos

Mesas

Una mesa agrupa a los villagers que trabajan juntos, como los agentes de un mismo producto. Se sientan a su alrededor, y el letrero con su nombre se pone dorado cuando alguno te necesita.

• Crear: usa Nueva mesa en la pestaña Mesas del editor o en la cinta, o elige + Nueva mesa en la tarjeta de un villager. Ponle nombre, aspecto y proyecto, y elige quién se sienta antes de crearla.
• Sentarse y levantarse: arrastra un villager hasta la mesa para sentarlo, o fuera de ella para levantarlo.
• Mover: arrastra la mesa y todos van con ella.
• Vincular un proyecto: en la tarjeta de la mesa, elige una carpeta abierta en tu IDE. Cada chat nuevo de esa carpeta se sienta solo en la mesa. Desvincular proyecto lo deshace.
• Nuevo agente: en la tarjeta de la mesa, crea un chat de Claude Code o Codex en la carpeta del proyecto, ya sentado allí. Eliges el villager, el modelo, el razonamiento y los permisos.
• Personalizar: en la pestaña Mesas, elige el estilo (café, reunión, oficina, pícnic, fogata), la madera, el mantel y un adorno.
• Quitar de la pantalla o eliminar: desde la tarjeta, la mesa sale de la pantalla pero sigue en la pestaña Mesas. Para borrarla del todo, usa Eliminar en la pestaña Mesas.

Una mesa vacía desaparece de la pantalla, salvo que Mantener en pantalla cuando no haya nadie esté activado.

Aspectos de los villagers

La pestaña Villagers del editor es el ropero de la villa. Cada aspecto combina cara, pelo, ropa, sombrero, accesorios, espalda, mascota y aura. El objeto más raro le da su título, como "The Arcane" o "The Caffeinated".

• Crea aspectos nuevos, sortea combinaciones y mira cada pose (quieto, caminando, trabajando, celebrando, durmiendo).
• El aspecto solo define la apariencia. El nombre del villager sigue siendo el título del chat.
• El mismo proyecto sigue recibiendo el mismo aspecto. Para cambiar el aspecto de un villager, usa su tarjeta.

Ajustes

Abre Personajes y ajustes… en el menú del icono y ve a la pestaña Ajustes. Después de cambiar algo, haz clic en Guardar ajustes.

Integraciones

Los hooks son globales: valen para el agente en cualquier IDE y en la terminal. La pestaña Conexiones instala cada uno en el archivo del propio agente (~ es tu carpeta de usuario):

El selector de proyecto de las mesas reconoce las carpetas abiertas en VS Code, VS Code Insiders, Cursor, Windsurf, VSCodium, Antigravity, Kiro, Trae, Positron y los IDE de JetBrains.

Cualquier otro agente o script

Cualquier programa puede poner un villager en la villa enviando eventos a la app, como un agente sin hooks, un job de CI o una tarea programada:

curl -s localhost:47321/events -H 'Content-Type: application/json' \
  -d '{"sessionId":"nightly","project":"inventory","title":"Sync de stock","activity":"working","task":"Sincronizando stock"}'

En PowerShell:

Invoke-RestMethod http://localhost:47321/events -Method Post -ContentType 'application/json' `
  -Body '{"sessionId":"nightly","title":"Sync de stock","activity":"working"}'

Estos villagers muestran el estado, pero no reciben mensajes.

Datos y privacidad

• Todo se queda en tu equipo. Los villagers, posiciones, mesas y ajustes se guardan en agent-village.json, en la carpeta de datos:

  Sistema	Carpeta de datos
  macOS	~/Library/Application Support/agent-village
  Windows	%APPDATA%\agent-village
  Linux	~/.config/agent-village

• Los eventos de los hooks llegan por un puerto local (127.0.0.1) que solo acepta conexiones de tu propio equipo y rechaza solicitudes que vienen de páginas web.
• Las tareas se ejecutan con los CLI oficiales (claude y codex) y tu sesión. Pixlage no tiene servidor propio y no ve tu código.
• La app solo se conecta a internet para buscar actualizaciones entre las versiones publicadas en GitHub.

Solución de problemas

El villager no aparece

• Comprueba que la app esté abierta: su icono tiene que estar en la barra de menús o en la bandeja.
• En la pestaña Conexiones, mira si el agente está Conectado. Si está parcial, haz clic en Reparar.
• Abre un chat nuevo: los chats abiertos antes de conectar no usan los hooks.
• Comprueba que Mostrar villa esté activado en el menú del icono.

La tarjeta de Codex está amarilla

Codex todavía no confía en los hooks. Sigue los pasos de Conectar tus agentes: ejecuta /hooks en Codex, confía en los de Agent Village y recarga la ventana del IDE.

macOS: "la app está dañada y no se puede abrir"

Es el mismo bloqueo del aviso de seguridad, con otro mensaje. Ejecuta esto en la Terminal y abre la app otra vez:

xattr -dr com.apple.quarantine "/Applications/Agent Village.app"

Windows: la instalación se bloqueó

• Si el comando de PowerShell no consigue descargar, revisa tu conexión o el proxy de la empresa e inténtalo de nuevo.
• Si el Control inteligente de aplicaciones de Windows 11 está activado, bloquea las apps sin firma digital, aunque se instalen desde la terminal. En ese caso, la app todavía no se puede instalar en ese equipo.

Linux: el icono no aparece en la bandeja

• En GNOME, instala y activa la extensión AppIndicator.
• La transparencia de la villa necesita un compositor; cualquier escritorio moderno tiene uno.
• En Wayland puro, los atajos globales y las ventanas siempre encima dependen del compositor. Con XWayland, funcionan como en X11.

¿Sigues con problemas?

Lee las notas de las versiones y comprueba que tienes la más reciente con Buscar actualizaciones… en el menú.