Tudo sobre a sua vila.

O Pixlage transforma os seus agentes de código em villagers de pixel art que vivem na sua tela. Esta página mostra como instalar, conectar os agentes e usar cada recurso. No seu computador, o app se chama Agent Village.

Instalar

Há duas formas de instalar. As duas instalam o mesmo app e sempre a versão mais recente.

Requisitos

• macOS 12 (Monterey) ou mais novo, em Macs com Apple Silicon ou Intel.
• Windows 10 ou 11, 64 bits.
• Linux x64: pacote .deb para Ubuntu, Debian e derivados, ou AppImage para as outras distribuições.
• Pelo menos um agente de código instalado, como o Claude Code ou o Codex. Veja a lista em Integrações.

Pelo terminal

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

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

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

Pelo instalador

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

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

Por que aparece um aviso de segurança?

O macOS e o Windows mostram esse aviso para todo app que ainda não tem uma assinatura digital paga da Apple ou da Microsoft. O aviso não quer dizer que foi encontrado algum problema no app: só que o sistema não reconhece quem o publicou.

O sistema só faz essa verificação em arquivos marcados como baixados por um navegador. Arquivos baixados pelo curl ou pelo PowerShell não recebem essa marca, por isso a instalação pelo terminal não mostra o aviso. O app instalado é exatamente o mesmo.

Atualizar

O app procura uma versão nova ao abrir, a cada 6 horas e quando você clica em Procurar atualizações… no menu do ícone. Os seus villagers, mesas e configurações são mantidos.

• Windows e Linux: a atualização é baixada em segundo plano e instalada quando você sai do app, ou na hora, pelo item Reiniciar para atualizar do menu. No .deb, o sistema pede a sua senha.
• macOS: o app avisa que há uma versão nova. O aviso e o item Baixar Agent Village… do menu abrem o .dmg novo: arraste para Aplicativos por cima do antigo. Ou rode de novo o comando do terminal.

Desinstalar

1. Abra Personagens e configurações… no menu do ícone, vá até a aba Conexões e clique em Desconectar em cada agente. Isso tira os hooks do Pixlage dos arquivos de configuração dos agentes. Se você pular esse passo, nada quebra: os hooks percebem que o app não está aberto e saem na hora.

2. Saia do app pelo menu (Sair do Agent Village) e remova-o:

   • macOS: arraste o Agent Village da pasta Aplicativos para o Lixo.
   • Windows: Configurações › Aplicativos › Aplicativos instalados › Agent Village › Desinstalar.
   • Linux: sudo apt remove agent-village, ou apague o arquivo AppImage.

3. Se quiser apagar também os seus villagers e configurações, apague a pasta de dados.

Primeiros passos

O ícone e o menu

O Pixlage não tem janela principal nem ícone no Dock. Ele vive no ícone da barra de menus (macOS) ou da bandeja do sistema (Windows e Linux). No macOS, o número de pedidos esperando por você aparece ao lado do ícone; no Windows, na dica que aparece ao passar o mouse.

O menu do ícone mostra os agentes que estão na vila e tem:

• Mostrar vila: liga e desliga os personagens na tela.
• Nova tarefa…: abre a janela para mandar uma tarefa.
• Personagens e configurações…: abre o editor, com as abas Villagers, Mesas, Conexões e Configurações.
• Criar agentes de demonstração: quatro agentes de mentira, um em cada estado.
• Procurar atualizações… e Sair do Agent Village.

A janela da vila é transparente e fica por cima de tudo, mas só captura o mouse quando ele passa sobre um personagem, uma mesa ou um card. No resto da tela, você clica normalmente nos apps por baixo.

Conectar os agentes

O Pixlage fica sabendo o que cada agente faz por meio de hooks: pequenos comandos que o próprio agente roda a cada passo. Para instalá-los:

1. Abra Personagens e configurações… e vá até a aba Conexões. Ela mostra os agentes encontrados no seu computador.

2. Clique em Conectar em cada agente que você usa. O card mostra Conectado quando todos os eventos estão instalados, Parcialmente conectado quando falta algum (clique em Reparar) e Não conectado quando não há nenhum.

3. Abra um chat novo no agente. Os agentes leem os hooks quando uma sessão começa, então um chat que já estava aberto precisa ser reiniciado.

Os hooks de outras ferramentas são preservados, e o Pixlage faz um backup de cada arquivo antes de alterá-lo pela primeira vez (<arquivo>.agent-village-backup). Se o app estiver fechado, o hook desiste em menos de 1 segundo e o agente segue normalmente.

Testar sem um agente

Quer ver como tudo funciona antes de conectar? Clique em Criar agentes de demonstração no menu do ícone (ou em Experimente, na aba Configurações). Aparecem quatro agentes de mentira, um em cada estado. Para tirá-los, use Remover no card de cada um.

Usar a vila

O que cada animação significa

Cada agente aberto vira um villager. A animação mostra o que ele está fazendo naquele momento:

O villager vai embora quando você fecha o chat na IDE. Chats que já estavam abertos antes do app (no Claude Code e no Codex) também ganham um villager.

O card do villager

Clique em um villager para abrir o card dele. O card mostra a tarefa atual, as últimas ações e os pedidos abertos. Por ele você também troca o visual do villager, escolhe a mesa dele, manda mensagens (no Claude Code e no Codex) e o remove da vila.

Arraste um villager para deixá-lo onde quiser na tela. Ele lembra do lugar.

Aprovar pedidos

Quando o agente pede permissão para rodar um comando ou editar um arquivo, o villager pula com um "!" e o card mostra o pedido. Você responde ali mesmo:

• Permitir: libera só este pedido.
• Sempre permitir: libera e guarda a regra para os próximos pedidos parecidos. Só no Claude Code.
• Negar: recusa o pedido.
• Responder na IDE: devolve a pergunta para a janela normal do agente.

Se você não responder em 300 segundos (dá para mudar em Configurações), o pedido volta para a IDE. Se você responder na IDE primeiro, o pedido some do card.

Aprovar pelo villager funciona no Claude Code, no Codex, no Qwen Code e no Copilot CLI. Nos outros agentes, o villager mostra o pedido e você responde na própria ferramenta.

Perguntas do agente

Quando o Claude Code faz uma pergunta com opções, o card mostra as opções como botões (uma ou várias, conforme a pergunta) e um campo para resposta livre. Envie as respostas ou pule a pergunta. Em sessões da IDE, vale quem responder primeiro: se você responder pela vila, o diálogo da IDE fecha sozinho.

Nomes

Cada villager usa o título do chat, o mesmo que a IDE mostra na lista de conversas. Até o título existir (alguns segundos depois da primeira mensagem), ele usa o nome do projeto. No Claude Code, um nome dado com /rename tem prioridade.

Os nomes aparecem em crachás embaixo dos personagens. Se preferir a tela mais limpa, desligue Mostrar nomes dos agentes em Configurações: aí o nome só aparece ao passar o mouse ou com o card aberto.

A fitinha Vila

Na borda direita da tela fica uma fitinha escrita Vila. Passe o mouse sobre ela para abrir um menu rápido:

• Adicionar: Nova tarefa, Nova mesa e Novo visual.
• Na tela: chaves para mostrar a vila, os nomes dos agentes e os alertas de aprovação.
• Abrir: atalhos para as abas do editor.

Quando algum agente precisa de você, a fitinha fica dourada e mostra o número de pedidos.

Mandar tarefas

Você pode começar um trabalho novo no Claude Code ou no Codex sem abrir a IDE. A tarefa roda em segundo plano com o seu login do CLI, sem API key.

Nova tarefa

Abra a janela Nova tarefa pelo menu do ícone, pelo link "Nova tarefa" de qualquer card ou pelo atalho, que funciona em qualquer app:

Escolha o agente, a pasta do projeto, o villager, as permissões e, se quiser, o modelo e o esforço de raciocínio. No Claude Code, esses campos já vêm com o que o Claude usaria naquele projeto. Escreva o prompt e envie.

O villager aparece na hora. Quando a tarefa termina, o card mostra o relatório final do agente, e uma notificação avisa (dá para desligar em Configurações).

Continuar a conversa

A caixa de mensagem fica no rodapé do card. Por ela você:

• manda a próxima mensagem da mesma conversa;
• anexa arquivos pelo clipe, colando ou arrastando. Imagens (png, jpg, gif e webp, até 5 MB) chegam ao modelo como imagem;
• troca o modelo, o esforço de raciocínio e o modo de permissão, pelo botão com o resumo da escolha (ex.: "Sonnet · esforço low · Aceitar edições automaticamente"). A escolha vale a partir da próxima mensagem.

Mensagens mandadas enquanto o agente trabalha entram numa fila. Parar interrompe a vez atual e esvazia a fila. As tarefas continuam lá depois de reiniciar o app; Remover pede um segundo clique, porque esquece a conversa.

Falar com um chat aberto na IDE

O card de qualquer agente do Claude Code ou do Codex tem a caixa de mensagem, inclusive o de um chat que você abriu na IDE. A mensagem entra na mesma conversa.

• Se o agente estiver no meio de uma etapa, a mensagem espera ela terminar, para os dois não escreverem ao mesmo tempo. Cancelar fila desiste da espera.
• O painel da IDE não atualiza ao vivo: as mensagens mandadas pela vila aparecem lá quando você reabrir a conversa pelo histórico.

Modos de permissão

Mesas

Uma mesa agrupa os villagers que trabalham juntos, como os agentes de um mesmo produto. Eles sentam em volta dela, e a placa com o nome fica dourada quando alguém ali precisa de você.

• Criar: use Nova mesa na aba Mesas do editor ou na fitinha, ou escolha + Nova mesa no card de um villager. Dê nome, visual, projeto e escolha quem senta nela antes de criar.
• Sentar e levantar: arraste um villager até a mesa para ele sentar, ou para fora dela para ele levantar.
• Mover: arraste a mesa, e todos vão junto.
• Ligar a um projeto: no card da mesa, escolha uma pasta aberta na sua IDE. Todo chat novo dessa pasta senta na mesa sozinho. Desvincular projeto desfaz.
• Novo agente: no card da mesa, cria um chat do Claude Code ou do Codex na pasta do projeto, já sentado ali. Você escolhe o villager, o modelo, o raciocínio e as permissões.
• Personalizar: na aba Mesas, escolha o estilo (café, reunião, escritório, piquenique, fogueira), a madeira, a toalha e um enfeite.
• Tirar da tela ou excluir: pelo card, a mesa sai da tela mas continua na aba Mesas. Para apagar de vez, use Excluir na aba Mesas.

Uma mesa vazia some da tela, a menos que Manter na tela quando não houver ninguém esteja ligado.

Visuais dos villagers

A aba Villagers do editor é o guarda-roupa da vila. Cada visual combina rosto, cabelo, roupa, chapéu, acessórios, costas, pet e aura. O item mais raro dá o título do visual, como "The Arcane" ou "The Caffeinated".

• Crie visuais novos, sorteie combinações e veja cada pose (parado, andando, trabalhando, comemorando, dormindo).
• O visual define só a aparência. O nome do villager continua sendo o título do chat.
• O mesmo projeto continua recebendo o mesmo visual. Para trocar o visual de um villager, use o card dele.

Configurações

Abra Personagens e configurações… no menu do ícone e vá até a aba Configurações. Depois de mudar algo, clique em Salvar configurações.

Integrações

Os hooks são globais: valem para o agente em qualquer IDE e no terminal. A aba Conexões instala cada um no arquivo do próprio agente (~ é a sua pasta de usuário):

O seletor de projeto das mesas reconhece as pastas abertas no VS Code, VS Code Insiders, Cursor, Windsurf, VSCodium, Antigravity, Kiro, Trae, Positron e nas IDEs da JetBrains.

Qualquer outro agente ou script

Qualquer programa pode colocar um villager na vila mandando eventos para o app, como um agente sem hooks, um job de CI ou uma tarefa agendada:

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

No PowerShell:

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

Esses villagers mostram o status, mas não recebem mensagens.

Dados e privacidade

• Tudo fica no seu computador. Os villagers, posições, mesas e configurações ficam em agent-village.json, na pasta de dados:

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

• Os eventos dos hooks chegam por uma porta local (127.0.0.1) que só aceita conexões do próprio computador e recusa pedidos vindos de páginas da web.
• As tarefas rodam pelos CLIs oficiais (claude e codex) com o seu login. O Pixlage não tem servidor próprio e não vê o seu código.
• O app só acessa a internet para procurar atualizações nas versões publicadas no GitHub.

Solução de problemas

O villager não aparece

• Confira se o app está aberto: o ícone precisa estar na barra de menus ou na bandeja.
• Na aba Conexões, veja se o agente está Conectado. Se estiver parcial, clique em Reparar.
• Abra um chat novo: chats abertos antes de conectar não usam os hooks.
• Confira se Mostrar vila está ligado no menu do ícone.

O card do Codex está amarelo

O Codex ainda não confia nos hooks. Siga os passos em Conectar os agentes: rode /hooks no Codex, confie nos do Agent Village e recarregue a janela da IDE.

macOS: "o app está danificado e não pode ser aberto"

É o mesmo bloqueio do aviso de segurança, com outra mensagem. Rode no Terminal e abra o app de novo:

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

Windows: a instalação foi bloqueada

• Se o comando do PowerShell falhar ao baixar, verifique a conexão ou o proxy da empresa e tente de novo.
• Se o Controle Inteligente de Aplicativos do Windows 11 estiver ligado, ele bloqueia apps sem assinatura digital, mesmo instalados pelo terminal. Nesse caso, o app ainda não pode ser instalado nesse computador.

Linux: o ícone não aparece na bandeja

• No GNOME, instale e ative a extensão AppIndicator.
• A transparência da vila precisa de um compositor; qualquer desktop moderno tem um.
• No Wayland puro, os atalhos globais e as janelas sempre no topo dependem do compositor. Com XWayland, funcionam como no X11.

Ainda com problemas?

Veja as notas das versões e confira se você está na mais recente pelo item Procurar atualizações… do menu.