Everything about your village.

Pixlage turns your coding agents into pixel-art villagers that live on your screen. This page shows how to install it, connect your agents and use every feature. On your computer, the app is called Agent Village.

Install

There are two ways to install. Both install the same app, always the latest version.

Requirements

• macOS 12 (Monterey) or newer, on Apple Silicon or Intel Macs.
• Windows 10 or 11, 64-bit.
• Linux x64: a .deb package for Ubuntu, Debian and their derivatives, or an AppImage for other distributions.
• At least one coding agent installed, such as Claude Code or Codex. See the list under Integrations.

From the terminal

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

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

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

With the installer

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

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

Why is there a security prompt?

macOS and Windows show this prompt for every app that doesn't yet carry a paid digital signature from Apple or Microsoft. It doesn't mean a problem was found in the app, only that the system doesn't recognize who published it.

The system only runs this check on files marked as downloaded by a browser. Files downloaded by curl or PowerShell don't get that mark, which is why installing from the terminal shows no prompt. The installed app is exactly the same.

Update

The app looks for a new version when it opens, every 6 hours, and when you click Check for updates… in the icon's menu. Your villagers, tables and settings are kept.

• Windows and Linux: the update downloads in the background and installs when you quit the app, or right away with Restart to update in the menu. With the .deb, the system asks for your password.
• macOS: the app tells you a new version is out. The notification and the Download Agent Village… menu item open the new .dmg: drag it into Applications over the old one. Or run the terminal command again.

Uninstall

1. Open Characters & settings… from the icon's menu, go to the Connections tab and click Disconnect on each agent. This takes the Pixlage hooks out of your agents' configuration files. If you skip this step nothing breaks: the hooks notice the app isn't running and exit right away.

2. Quit the app from the menu (Quit Agent Village) and remove it:

   • macOS: drag Agent Village from Applications to the Trash.
   • Windows: Settings › Apps › Installed apps › Agent Village › Uninstall.
   • Linux: sudo apt remove agent-village, or delete the AppImage file.

3. To also erase your villagers and settings, delete the data folder.

First steps

The icon and its menu

Pixlage has no main window and no Dock icon. It lives in an icon in the menu bar (macOS) or the system tray (Windows and Linux). On macOS, the number of requests waiting for you shows next to the icon; on Windows, in the tooltip.

The icon's menu lists the agents in the village and has:

• Show village: shows or hides the characters on screen.
• New task…: opens the window to send a task.
• Characters & settings…: opens the editor, with the Villagers, Tables, Connections and Settings tabs.
• Spawn demo agents: four pretend agents, one in each state.
• Check for updates… and Quit Agent Village.

The village window is transparent and stays on top of everything, but it only takes the mouse when the pointer is over a character, a table or a card. Everywhere else, you click the apps underneath as usual.

Connect your agents

Pixlage learns what each agent is doing through hooks: small commands the agent itself runs at every step. To install them:

1. Open Characters & settings… and go to the Connections tab. It shows the agents found on your computer.

2. Click Connect on each agent you use. The card says Connected when every event is installed, Partly connected when some are missing (click Repair) and Not connected when there are none.

3. Open a new chat in the agent. Agents read their hooks when a session starts, so a chat that was already open needs to be restarted.

Hooks from other tools are kept, and Pixlage backs up each file before changing it for the first time (<file>.agent-village-backup). If the app is closed, the hook gives up in under a second and the agent carries on normally.

Try it without an agent

Want to see how it all works before connecting anything? Click Spawn demo agents in the icon's menu (or Try it in the Settings tab). Four pretend agents show up, one in each state. To take them away, use Remove on each card.

Using the village

What each animation means

Every open agent becomes a villager. Its animation shows what it's doing right now:

The villager leaves when you close the chat in your IDE. Chats that were already open before the app started (in Claude Code and Codex) get a villager too.

The villager's card

Click a villager to open its card. The card shows the current task, the latest actions and any open requests. From it you can also change the villager's look, pick its table, send messages (in Claude Code and Codex) and remove it from the village.

Drag a villager to put it anywhere on the screen. It remembers the spot.

Approve requests

When the agent asks permission to run a command or edit a file, the villager jumps with a "!" and the card shows the request. Answer right there:

• Allow: allows this request only.
• Always allow: allows it and saves the rule for similar requests. Claude Code only.
• Deny: refuses the request.
• Answer in the IDE: hands the question back to the agent's usual window.

If you don't answer within 300 seconds (you can change this in Settings), the request goes back to the IDE. If you answer in the IDE first, the request disappears from the card.

Approving from the villager works in Claude Code, Codex, Qwen Code and Copilot CLI. With the other agents, the villager shows the request and you answer in the tool itself.

Questions from the agent

When Claude Code asks a question with options, the card shows the options as buttons (one or several, depending on the question) and a field for a free answer. Send your answers or skip the question. In IDE sessions, whoever answers first wins: if you answer from the village, the IDE's dialog closes on its own.

Names

Each villager goes by its chat's title, the same one the IDE shows in its chat list. Until the title exists (a few seconds after the first message), it uses the project's name. In Claude Code, a name set with /rename wins.

Names show on badges under the characters. For a cleaner screen, turn off Show agent names under the characters in Settings: then a name only shows on hover or while its card is open.

The Village ribbon

On the right edge of the screen there's a ribbon that says Village. Hover over it for a quick menu:

• Quick add: New task, New table and New look.
• On screen: switches to show the village, the agent names and the approval alerts.
• Open: shortcuts to the editor's tabs.

When an agent needs you, the ribbon turns gold and shows how many requests are waiting.

Send tasks

You can start new work in Claude Code or Codex without opening your IDE. The task runs in the background with your CLI login, no API key needed.

New task

Open the New task window from the icon's menu, from the "New task" link on any card, or with the shortcut, which works from any app:

Pick the agent, the project folder, the villager, the permissions and, if you like, the model and reasoning effort. With Claude Code, these start out as what Claude would use in that project. Write your prompt and send it.

The villager shows up right away. When the task finishes, the card shows the agent's final report and a notification lets you know (you can turn it off in Settings).

Keep the conversation going

The message box sits at the bottom of the card. From it you:

• send the next message in the same conversation;
• attach files with the paperclip, by pasting or by dropping them. Images (png, jpg, gif and webp, up to 5 MB) reach the model as images;
• change the model, reasoning effort and permission mode, from the button that sums up your choice (e.g. "Sonnet · low effort · Auto-accept edits"). The choice applies from your next message.

Messages sent while the agent is working join a queue. Stop interrupts the current turn and clears the queue. Tasks are still there after the app restarts; Remove asks for a second click, because it forgets the conversation.

Talk to a chat open in your IDE

The card of any Claude Code or Codex agent has the message box, including a chat you opened in your IDE. The message goes into the same conversation.

• If the agent is in the middle of a step, the message waits for it to finish, so the two don't write at the same time. Cancel queued gives up waiting.
• The IDE's panel doesn't update live: messages sent from the village show up there when you reopen the conversation from its history.

Permission modes

Tables

A table groups villagers who work together, like the agents on one product. They sit around it, and its sign turns gold when one of them needs you.

• Create: use New table in the editor's Tables tab or on the ribbon, or pick + New table on a villager's card. Give it a name, a look and a project, and choose who sits there before creating it.
• Sit and stand: drag a villager onto the table to seat it, or off the table to stand it up.
• Move: drag the table and everyone comes along.
• Link a project: on the table's card, pick a folder open in your IDE. Every new chat in that folder sits at the table on its own. Unlink project undoes it.
• New agent: on the table's card, starts a Claude Code or Codex chat in the project folder, already seated there. You choose the villager, model, reasoning and permissions.
• Customize: in the Tables tab, pick the style (café, meeting, office, picnic, campfire), the wood, the cloth and a decoration.
• Take off screen or delete: from the card, the table leaves the screen but stays in the Tables tab. To erase it for good, use Delete in the Tables tab.

An empty table disappears from the screen, unless Keep on screen when nobody's around is on.

Villager looks

The editor's Villagers tab is the village wardrobe. Each look combines a face, hair, outfit, hat, gear, back item, pet and aura. The rarest item gives the look its title, like "The Arcane" or "The Caffeinated".

• Create new looks, roll random combinations and preview every pose (idle, walking, working, cheering, napping).
• A look only sets the appearance. The villager's name is still the chat's title.
• The same project keeps getting the same look. To change a villager's look, use its card.

Settings

Open Characters & settings… from the icon's menu and go to the Settings tab. After changing something, click Save settings.

Integrations

Hooks are global: they work for the agent in any IDE and in the terminal. The Connections tab installs each one in the agent's own file (~ is your user folder):

The tables' project picker recognizes folders open in VS Code, VS Code Insiders, Cursor, Windsurf, VSCodium, Antigravity, Kiro, Trae, Positron and the JetBrains IDEs.

Any other agent or script

Any program can put a villager in the village by sending events to the app, like an agent without hooks, a CI job or a scheduled task:

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

In PowerShell:

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

These villagers show status but don't take messages.

Data and privacy

• Everything stays on your computer. Villagers, positions, tables and settings are kept in agent-village.json, in the data folder:

  System	Data folder
  macOS	~/Library/Application Support/agent-village
  Windows	%APPDATA%\agent-village
  Linux	~/.config/agent-village

• Hook events arrive on a local port (127.0.0.1) that only accepts connections from your own computer and refuses requests coming from web pages.
• Tasks run through the official CLIs (claude and codex) with your login. Pixlage has no server of its own and never sees your code.
• The app only goes online to look for updates among the versions published on GitHub.

Troubleshooting

The villager doesn't show up

• Make sure the app is running: its icon should be in the menu bar or system tray.
• In the Connections tab, check that the agent is Connected. If it's partly connected, click Repair.
• Open a new chat: chats opened before connecting don't use the hooks.
• Check that Show village is on in the icon's menu.

The Codex card is yellow

Codex doesn't trust the hooks yet. Follow the steps in Connect your agents: run /hooks in Codex, trust the Agent Village ones and reload the IDE window.

macOS: "the app is damaged and can't be opened"

It's the same block as the security prompt, with a different message. Run this in Terminal and open the app again:

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

Windows: the installation was blocked

• If the PowerShell command fails to download, check your connection or company proxy and try again.
• If Windows 11's Smart App Control is on, it blocks apps without a digital signature, even when installed from the terminal. In that case, the app can't be installed on that computer yet.

Linux: the icon doesn't show in the tray

• On GNOME, install and enable the AppIndicator extension.
• The village's transparency needs a compositor; any modern desktop has one.
• On pure Wayland, global shortcuts and always-on-top windows depend on the compositor. With XWayland, they work as on X11.

Still stuck?

Read the release notes and make sure you're on the latest version with Check for updates… in the menu.