Docs
We believe making things should feel like joy, not a race. As AI agents take on more of the work, we should get to enjoy the show. Agentopia turns each agent session into a desk in a cozy open-plan office in the browser. Each lead agent types away at its own desk, and its subagents join it as helpers. Their monitors pile up as the context fills, and a click shows the breakdown. When the agent needs your OK, it walks over and asks. A whiteboard on the wall tallies the tokens spent. Everything stays local. Pour a coffee and watch the office work.
This page covers everything the agentopia command does.
Install
Agentopia needs Node.js 20 or later, and Claude Code.
npm i -g agentopiahq # install the agentopia command
agentopia start # add the plugin (it asks), open the office
agentopia start asks once whether to install the agentopia plugin into Claude Code, then
serves the office in the background and opens it in your browser. Closing the terminal
leaves it open.
Restart the Claude Code desktop app, and any claude sessions already running, so they
load the plugin. From then on every new session is recorded, from the terminal or the
desktop app, and gets a desk in the office.
To look without installing anything, run npx agentopiahq watch.
Commands
| Command | What it does |
|---|---|
agentopia start | Install the plugin if it is missing (asks first), then serve the office in the background and open it |
agentopia status | Say whether the office is running, and at which address |
agentopia stop | Stop the office, however it was started |
agentopia watch | Serve the same office in this terminal, for as long as it stays open |
agentopia install | Install the agentopia plugin into Claude Code |
agentopia uninstall | Uninstall the plugin; new sessions are no longer recorded |
agentopia claude [args...] | Run Claude Code with the office recording attached, without installing the plugin |
agentopia update | Update now instead of waiting (--check only says whether there is a new version); alias upgrade |
agentopia doctor | Check the setup: the plugin, its hooks, and the agents on your PATH |
agentopia help | List the commands |
agentopia --version | Print the version |
Options
--yes(start): install the plugin without asking.--no-open(start,watch): serve the office without opening a browser tab.--check(update): say whether there is a new version, without installing it.--port <port>(start,watch): serve on this port. The default is 7777, or the next free one.
Anything after agentopia claude goes straight to Claude Code, so
agentopia claude --effort high works as claude --effort high does.
One office for every session
There is one office per machine. start, watch and agentopia claude all find an office
already running and use it, rather than opening a second one. Run agentopia status to see
its address.
Each live session gets a desk, up to eight; a ninth waits for one to free up. A session that goes quiet for five minutes naps, then leaves, and its desk is free for the next. To clear a desk by hand, click the desk and pick Clear this desk.
Updates
Agentopia keeps itself up to date. The office checks npm every few hours, downloads a new
release into ~/.agentopia/versions (checked against npm's integrity hash), and switches
over once no session is in the middle of a turn. Open tabs then offer a reload.
agentopia update does it straight away. To turn the automatic download off, set
AGENTOPIA_AUTO_UPDATE=0.
Recording sessions
The plugin's hooks append one line per event (a prompt, a tool call, a subagent, an approval) to a file for that session. The office follows those files as they grow.
- With the plugin installed (
agentopia install, or saying yes toagentopia start): every Claude Code session is recorded, the desktop app's too. - With the plugin installed from its marketplace (in Claude Code,
/plugin install agentopia --marketplace agentopiahq/agentopia): the same, kept up to date by Claude Code itself.agentopia startsees it and installs nothing more. Its hooks runnodefrom yourPATH, so if the desktop app can't find Node, useagentopia installinstead, which pins the Node that ran it. Keep one or the other. - Without it: only sessions started with
agentopia claudeare recorded.
Use one or the other. Running agentopia claude with the plugin installed records the
session once, not twice.
Where things are kept
Everything Agentopia writes stays in ~/.agentopia (set AGENTOPIA_HOME to use another
folder):
sessions/: one folder per recorded session, holding its event file.server.json: the office that is running (its process and port).server.log: what the background office prints.versions/: the releases it has downloaded for itself.
The office's usage board and each desk's context are read from Claude Code's own records on
your machine. Nothing is sent anywhere: the server only listens on 127.0.0.1.
Uninstall
agentopia uninstall # stop recording new sessions
agentopia stop # close the office
npm rm -g agentopiahq # remove the command
Recordings stay in ~/.agentopia until you delete the folder.
Troubleshooting
- The office is empty. Run
agentopia doctor. If the plugin is installed, restart the Claude Code desktop app and any runningclaudesessions so they load it. A session shows up as soon as it starts. - The browser did not open. Run
agentopia statusand open the address it prints. - Something else. Open an issue on GitHub or write to contact@agentopia.town.