Agentshire: a 3D town for OpenClaw and QClaw agents
OpenClaw / QClaw plugin that visualizes AI agents as 3D NPCs in a game town — with social simulation, a map editor, and a character workshop.
At a glance
- What is it?
- Agentshire is an MIT-licensed OpenClaw/QClaw plugin that renders sub-agents as 3D NPCs in a low-poly town with a day/night cycle, weather, a map editor and a character workshop. The idea is legible, but the compatibility table and the 'runtime integration in progress' note deserve attention before you install it.
- Who is it for?
- Adopt Agentshire if you run OpenClaw CLI 2026.3.13 or QClaw Desktop 0.2.x and want a spatial read on multi-agent work rather than another chat transcript. Skip it if you are on OpenClaw 2026.4.x, since the README lists that range as not yet supported because of a channel init regression, or if you need a finished map pipeline rather than an editor that exports JSON.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 154 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Agentshire tries to solve
Multi-agent runs are hard to read. A steward decomposes a task, several sub-agents work in parallel, and the only artefact is a scrolling log where you cannot tell who is waiting, who is blocked and who has already finished. Agentshire's answer is spatial: every sub-agent becomes a 3D citizen in a low-poly town, and the workflow is staged as a sequence of scenes. The README describes the choreography as Summon, Rally, Assign, Enter Office, Code, Celebrate, Return to Town. An agent that is coding is at a workstation in the Office scene; an agent that is idle is walking around town.
The intended user is someone who already runs OpenClaw or QClaw and wants a second view onto the same sessions, not a replacement interface. The plugin ships a Chat Mode alongside Town Mode, with an agent list showing steward and citizens, online status, message history, and commands such as /new, /help and /stop. That dual-mode layout is the tell: the town is an addition to the chat client, not a substitute for it. If you do not already have OpenClaw or QClaw installed and working, Agentshire has nothing to attach to.
How the simulation actually runs
The README draws a line between two behaviour modes for NPCs. The default is algorithmic: a state machine, five behaviour templates and more than 400 preset dialog lines, which the README states costs zero LLM tokens. Soul Mode is the opt-in alternative, where behaviour is driven by AgentBrain with three decision tiers (L1 daily plan, L2 tactical, L3 dialogue), multi-turn LLM conversations, a relationship graph and daily narrative summaries. That split is the most consequential design decision in the project, because it means the town can run continuously at no inference cost and only spend tokens when you deliberately switch a citizen to AI-driven behaviour.
Around that core sit the environmental systems. There is a 24-hour clock split into six periods with real-time lighting and automatic street and window lights. Twelve weather types are listed, including clear, fog, drizzle, storm, blizzard, sandstorm and aurora, with a daily random theme. Ambient sound is synthesised at runtime through the Web Audio API rather than loaded from files, and the README claims zero audio files. Background music is four tracks (day, dusk, night, work) that switch on weather, time period and scene with a 3.5 second crossfade.
Interaction is routed per citizen. Clicking an NPC opens a status card with avatar, persona, work logs, thinking stream and TODO list, and starting a conversation routes to that citizen's independent agent session. There is also a group discussion mode with structured turn-taking and an AI moderator. Tool control runs the other direction: the README states agents can broadcast messages, spawn NPCs, trigger effects and set time or weather through tools.
Install paths and the version trap
On OpenClaw CLI the install is a single command:
openclaw plugins install agentshire
On QClaw Desktop the plugin is not installed through a package manager. You clone it into the QClaw extensions directory, the one that holds built-in plugins such as qclaw-plugin and lossless-claw. The README is explicit that this is not ~/.qclaw/plugins/. On macOS the example used to locate it is:
ls ~/Library/Application\ Support/QClaw/openclaw/config/extensions/
Then clone into that directory, install dependencies and restart QClaw:
cd <extensions-directory> git clone https://github.com/Agentshire/Agentshire.git agentshire cd agentshire && npm install
The README states the town opens at http://localhost:55210 after the restart, and that the frontend ships pre-built in town-frontend/dist/ so no build step is needed. Node.js 18 or later is required.
The version table is the part to read twice. OpenClaw CLI 2026.3.13 is marked recommended, QClaw Desktop 0.2.x supported, OpenClaw CLI 2026.3.7 through 3.12 may work, and OpenClaw CLI 2026.4.x and later are marked not yet supported because of what the README calls a channel init regression. That last row is unusual for a project whose most recent release is dated 2026-04-11 and whose last push is 2026-04-15. The plugin is being released into a version range of its host that the README says it does not yet work with.
Where Agentshire is the wrong tool
The clearest limitation is stated by the project itself: the Town Editor's JSON export has runtime integration in progress. In practice that means the drag-and-drop map editor, with grouping, alignment and undo, produces a file that the running town does not yet consume. If your reason for looking at Agentshire is to author custom maps and play in them, the editor is not finished. The README also lists Showroom as a scene type marked in development, so one of the three scenes is not a shipped feature.
The second limitation is the host dependency. Agentshire is a plugin, not a standalone application. It has no homepage, and the install instructions assume an existing OpenClaw or QClaw installation. If you are evaluating it as a way to visualise agents from some other framework, there is nothing in the material to suggest that path exists.
The third is cost shape rather than cost size. The default algorithmic mode is free of inference, but Soul Mode adds three tiers of LLM decision-making plus multi-turn conversation per citizen. The README does not give token budgets, rate guidance or a way to cap Soul Mode spending. With a town of many citizens, the difference between the two modes is not a setting you can flip casually without thinking about what each NPC's decisions cost per hour.
How it compares to watching the same run in a terminal
The obvious alternative is the interface you already have: the OpenClaw CLI transcript or the QClaw chat window. Those show the same agent sessions as text, in order, with no rendering layer. Agentshire does not replace them, it wraps them. The README's Chat Mode is an IM-style view with the agent list, online status, multimodal support and slash commands, and Town Mode is the spatial view of the same activity.
The difference in approach is what each view is good at. A transcript is precise and greppable; it tells you exactly what an agent said and in what order. A town is ambient and parallel; it tells you at a glance that three citizens are at workstations and one is still in the square. The cinematic workflow, the dialog bubbles with typewriter effect above NPC heads, and the deliverable cards with image lightbox, video and audio preview are all aimed at the second kind of question. If your actual problem is finding a specific line of output, the transcript wins and Agentshire adds nothing. If your problem is noticing that one sub-agent never left the rally stage, the town is the better instrument.
UGC surface and what it commits you to
Two tools define the user-generated content story. The Citizen Workshop creates and configures characters: you select or upload a 3D model, edit the soul personality file with optional AI generation, map eight animation slots, and publish the result as an independent agent. The Soul System is a Markdown file per NPC defining character traits, speaking style, expertise and work approach. That is a plain-text format, which means personas are diffable and reviewable rather than locked in a binary asset.
The Town Editor is the visual counterpart: place buildings, roads, props and lights on a map with grouping, alignment and undo, then export JSON. There is also an Editor Preview that opens a game-level window with WASD controls, the full day/night and weather system, vehicle animations and audio. The preview works; the runtime consumption of the exported JSON is the part marked in progress. Treat the editor as a preview tool for now, not a level pipeline.
One more feature worth naming because it is not simulation at all: the Banwei Buster mini-game, where NPCs generate banwei orbs while working and you click to pop them, with a combo system, boss battles and NPC stress mechanics. It is a deliberate piece of play layered on top of the work view. Whether that belongs in a tool you use to monitor agents is a judgement call, and the README presents it without apology.
Licence, maintenance and upgrade cost
Agentshire is MIT-licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement, and it means you can fork the plugin if a host version breaks it. It does not give you any warranty, and this article is not legal advice; read the LICENSE file in the repository for the actual terms.
The maintenance picture is mixed. The project is active: v0.1.0 landed on 2026-04-05, v2026.4.12 on 2026-04-11, and the last push is 2026-04-15. But the release cadence is fast enough that version strings are date-based, and the README already documents a regression against OpenClaw 2026.4.x. If you pin to OpenClaw 2026.3.13 as recommended, you are pinning your host to keep the plugin working, and that is a real cost if you wanted to track OpenClaw releases.
Upgrade cost on the QClaw path is the manual clone-and-npm-install flow. There is no plugin update command documented for that route, so keeping the extension current means pulling the repository and reinstalling dependencies yourself. On the OpenClaw CLI path, openclaw plugins install agentshire is the documented entry point, but the README does not describe an upgrade or uninstall procedure for it. Budget for reading release notes before each bump.
Editorial conclusion
Adopt Agentshire if you run OpenClaw CLI 2026.3.13 or QClaw Desktop 0.2.x and want a spatial read on multi-agent work rather than another chat transcript. Skip it if you are on OpenClaw 2026.4.x, since the README lists that range as not yet supported because of a channel init regression, or if you need a finished map pipeline rather than an editor that exports JSON. Before installing, confirm your OpenClaw version against the compatibility table and check that the QClaw extensions directory contains qclaw-plugin or lossless-claw, because the clone target is that directory and not ~/.qclaw/plugins/.
Community notes