Agentshire: an OpenClaw/QClaw plugin that turns agents into 3D townsfolk

Who Agentshire is for, and the problem it answers

Multi-agent runs are hard to read. A steward spawns sub-agents, hands out parallel steps, and the only evidence is text arriving in a chat pane. You cannot see which agent is idle, which one is stuck, or which one finished and is waiting. Agentshire's answer is spatial: every sub-agent becomes a 3D citizen with a name, appearance and personality, and the town is the status display.

The README frames it bluntly with the line "A town, not a chatbox." That is the whole pitch. The plugin targets people who already run OpenClaw or QClaw and want a second view onto the same sessions, not people looking for a standalone game. The repository describes a cinematic workflow of Summon, Rally, Assign, Enter Office, Code, Celebrate, Return to Town, so the visual layer tracks the lifecycle of a task rather than decorating an idle scene.

A second audience is the UGC crowd. The Citizen Workshop lets you pick or upload a 3D model, write a soul personality file, map eight animation slots, and publish the result as an independent agent. The Town Editor is a drag-and-drop map tool for buildings, roads, props and lights, with grouping, alignment, undo and JSON export. Both sit inside the same plugin, which makes Agentshire as much a content tool as a monitor.

How the plugin wires agents to 3D citizens

The architecture is a plugin plus a web frontend. The package's main entry is index.ts, the plugin manifest is openclaw.plugin.json, and the browser side lives in town-frontend, shipped pre-built in town-frontend/dist/. Supporting directories are town-data, town-souls and town-workspace. The TypeScript source sits in src/, and tests run through vitest.

The town is served over HTTP and driven by WebSockets. The README says the town opens automatically at http://localhost:55210 after you restart QClaw, and it lists WebSocket auto-reconnect with exponential backoff and work state recovery among the features. That matters because the browser view is a client of the agent runtime, not the runtime itself. If the socket drops, the town reconnects and tries to restore work state rather than starting the scene over.

The simulation layer has two modes, and the difference is cost. Algorithm-driven behavior is the default: a state machine, five behavior templates and more than 400 preset dialog lines, with what the README calls zero LLM cost. Soul Mode switches NPCs to AI-driven behavior with AgentBrain's three tiers (L1 daily plan, L2 tactical, L3 dialogue), multi-turn LLM conversations, a relationship graph and daily narrative summaries. If you enable Soul Mode across a large town you are paying for conversation, not just for task work, and the README does not give a token budget for that.

Ambience is generated rather than downloaded. The README states that rain, wind, birdsong, crickets, traffic and thunder are synthesized in real time through the Web Audio API with zero audio files, and that a four-track BGM set switches by weather, time period and scene with a 3.5s crossfade. The day/night cycle is a 24-hour clock across six periods, and there are 12 weather types.

Installing Agentshire on OpenClaw CLI or QClaw Desktop

Requirements are OpenClaw 2026.3.13, which the README marks as recommended, and Node.js 18 or newer. The compatibility table is the first thing to check, because it is unusually strict: OpenClaw CLI 2026.3.13 is recommended, QClaw Desktop 0.2.x is supported, OpenClaw CLI 2026.3.7 through 3.12 may work, and OpenClaw CLI 2026.4.x and later are listed as not yet supported because of a channel init regression.

On OpenClaw CLI the install is one command:

openclaw plugins install agentshire

The package's postinstall script prints a confirmation and tells you to restart the OpenClaw Gateway to activate the plugin, after which the town opens automatically in your browser. The frontend is pre-built, so there is no build step on the normal path.

On QClaw Desktop the route is different, and the README is emphatic about the directory. You clone into the QClaw extensions directory where built-in plugins live, not into ~/.qclaw/plugins/. On macOS the README gives this check:

ls ~/Library/Application\ Support/QClaw/openclaw/config/extensions/

That listing should show built-in plugins such as qclaw-plugin and lossless-claw. If it does, clone and install there:

cd <extensions-directory>
git clone https://github.com/Agentshire/Agentshire.git agentshire
cd agentshire && npm install

Restart QClaw afterwards and the town opens at http://localhost:55210. If you want to run the frontend from source instead of the pre-built bundle, package.json defines build:town, which changes into town-frontend, installs and builds, and dev:town, which starts the frontend dev server.

Where Agentshire breaks, and who should not install it

The version gate is the sharpest limitation. The README lists OpenClaw CLI 2026.4.x and later as not yet supported, with a channel init regression named as the cause. If you track OpenClaw's latest release, Agentshire may simply fail to initialize the channel, and there is no documented workaround beyond staying on 2026.3.13 or moving to QClaw Desktop 0.2.x.

The Town Editor is the second gap, and the README is honest about it: JSON export exists, but runtime integration is described as in progress. So the editor can produce a map definition that the running town may not yet consume. Plan a custom town as an experiment, not as a deliverable. The Showroom scene type is likewise marked in development.

The last push to the repository was on 2026-04-15. The latest release listed is v2026.4.12 from 2026-04-11, and the initial release v0.1.0 is dated 2026-04-05 in the release line. That is a short release history, so treat the plugin as young and expect rough edges around version compatibility in particular.

Agentshire is also the wrong tool if your goal is headless throughput. Adding a 3D scene, a WebSocket client and an ambient audio layer does not make agent work faster. If you never watch the town, you are paying for a renderer you do not use. The default algorithm-driven NPC behavior exists partly for this reason, but the browser client still runs.

Agentshire against generative-agent research demos

The closest reference point in the search data is the Generative Agents line of work, the "Interactive Simulacra" paper and its small-town simulation. The approach there is a research artifact: a fixed town, a fixed cast, memory streams and reflection loops, built to study emergent social behavior. Agentshire inverts the purpose. The town is a view onto agents you already run for real work, and the social layer is optional.

That inversion shows up in the details. Agentshire's default NPC behavior is a state machine with preset dialog lines and explicitly zero LLM cost, which a research simulacra would not do because the LLM conversation is the object of study. Soul Mode is where the two overlap, with AgentBrain's three tiers and a relationship graph, but it is a switch you flip rather than the baseline.

The other difference is that Agentshire is a plugin, not a standalone application. It has no independent agent runtime. Remove OpenClaw or QClaw and there is nothing to visualize. A research demo can be run on its own; Agentshire cannot, and that dependency is the price of the integration.

Licence and the cost of keeping up

Agentshire is MIT licensed, and the repository carries a THIRD_PARTY_NOTICES.md file alongside LICENSE, which is where the bundled dependencies' terms are recorded. The package depends on @gltf-transform/core, @gltf-transform/extensions, @gltf-transform/functions, jsonrepair and ws, and the frontend bundle is shipped inside the published package under town-frontend/dist/. If you redistribute the plugin, read THIRD_PARTY_NOTICES.md rather than assuming MIT covers everything in the tarball. This is not legal advice.

Upgrade cost is dominated by the OpenClaw version pin. Because 2026.4.x is listed as unsupported, upgrading OpenClaw and upgrading Agentshire are not independent decisions. Check the compatibility table before either move. On the plugin side, releases are dated, with v0.1.0 on 2026-04-05 and v2026.4.12 on 2026-04-11, so the project version numbers track the OpenClaw line rather than a simple semantic sequence. The README also points to a Troubleshooting section for version-specific issues, which is the place to look first when the town does not appear.

What the town actually shows you during a run

The value proposition is legibility. Clicking an NPC opens a status card with avatar, persona, work logs, thinking stream and TODO, according to the README. AI responses appear above NPC heads with a typewriter effect, streaming updates and pagination. A ten-workstation office gives each NPC its own monitor with a real-time code animation, and the choreography covers entering, working and leaving.

The steward decomposes tasks into parallel steps with file boundary validation, and the README says multi-agent collaboration is automatic. When a project finishes, deliverable cards pop up with image lightbox, video and audio preview plus download, and games or websites launch directly in an iframe. Errors are not silent either: the effects list includes error lightning alongside summon shockwaves and completion fireworks.

There is also an escape hatch for the agents themselves. The README states that agents can control the town through tools, broadcasting messages, spawning NPCs, triggering effects and setting time or weather. That turns the visualization into something scriptable from inside a run, which is a more interesting design choice than a passive dashboard. The Banwei Buster mini-game, where NPCs generate orbs while working and you click to pop them, is the least serious feature and the one most likely to be either loved or turned off.

Editorial conclusion

Adopt Agentshire if you already run OpenClaw 2026.3.13 or QClaw 0.2.x and want to see multi-agent work as spatial movement rather than a scrolling log. Do not adopt it if you are on OpenClaw 2026.4.x or newer, since the README lists that range as not yet supported because of a channel init regression. Verify your OpenClaw version against the compatibility table and check whether the town editor's runtime integration has landed before you plan a custom map.

Frequently asked questions

Official sources

1. Agentshire/Agentshire on GitHub
2. Issues
3. License: MIT
4. README
5. Releases