Habblaud

Habblaud is a free, open-source virtual office for Claude Code: every session on your machine becomes a pixel-art character, each project gets a room, and you see at a glance who is working, who finished and who is waiting for you. It is a local web app plus a small mod that ties your sessions to it, and you can answer permission requests from the office instead of hunting for the right terminal.

At a glance

• What it is: a web app you run on your computer, plus a mod and two companion plugins for Claude Code. OpenAI’s Codex sessions join the same office.
• Where you see it: in your browser at http://localhost:4747, optionally on your phone. In the terminal, the mod adds a line under the prompt when another session needs you.
• Tokens and network: no tokens. It reads files Claude Code already writes; outbound traffic is a GitHub release check and, only if you sign up, Habblaud World.
• Who it is for: anyone juggling several sessions, subagents or accounts on macOS or Linux, in English, Portuguese, Spanish or French.

What it does

• Rooms and characters. Every agent gets a name and a chip with its account letter. Subagents arrive by the elevator, hand their result to the agent that called them, and leave.
• States at a glance. Typing while working. Hand raised and a blinking alert when it waits for a permission or an answer. An hourglass and a timer while a shell command it started keeps running, then confetti or a rain cloud. Wandering to the kitchen or the lounge when idle.
• Plan usage. The top bar shows each account’s five-hour and weekly limits and when they reset. Several Claude Code accounts (~/.claude and any other ~/.claude* folder) appear side by side.
• Agent drawer. Activity, tasks, subagents, timeline and stats (tools, tokens, cost, lines changed, model, branch), plus a live view of the session’s conversation and a seven-day session history.
• Timelapse and My day. Replay the day at up to 600x, or see how long agents worked and how long they waited for you, by hour, project and account.
• Ambience. Day and night follow your clock; sounds are optional. Merged PRs drop confetti, failed CI sets off an alarm, and idle agents play ping-pong or bet fake coins. The automatic theme dresses the office for Halloween in October; choose None in Settings › Appearance to skip it.

The two companion plugins let the office act on sessions:

• habblaud-permissoes puts permission requests and the agent’s questions (AskUserQuestion) in the office, with buttons to approve, approve and stop asking (when Claude Code offers that rule), deny with a reason, or pick an answer. The terminal dialog stays open too, and the first answer wins.
• habblaud-mensagens adds a message box that types into the session as if you had typed in its terminal. If the agent is busy, the message waits for the turn to end.

Install

Needs Claude Code 2.1.287 or later, plus Node.js 22.12 or later with npm, on macOS or Linux (the author tests on macOS). Docker is optional.

git clone https://github.com/marmottajr/habblaud.git
cd habblaud
npm install
npm run docker:up
npm run mod:install

The README splits this into three steps:

1. Get the project: the clone and npm install.
2. Start the office: npm run docker:up builds a container that restarts with Docker and mounts only the account folders it needs, read-only. Without Docker, run npm run build and npm start. Then open http://localhost:4747.
3. Install the mod: npm run mod:install, from the same folder, adds the mod and both plugins to every account through claude plugin. Open sessions pick it up with /reload-plugins. If nothing shows, npm run mod:status checks your Claude Code version and each account’s plugins.

To leave a plugin out:

npm run mod:install -- --sem-permissoes
npm run mod:install -- --sem-mensagens

Start Claude Code in any project and your agent walks in. /habblaud prints a summary of the office, and ?mock=1 in the URL shows a simulated one. The mod loads from the clone: run npm run mod:install again if you move the folder, and npm run mod:uninstall before deleting it. To update, git pull, npm install and npm run docker:up, which also refreshes the mod.

What’s new since our first look

Since we covered it on 9 October, Habblaud has reached 1.0.3 (16 October), mod and plugins included:

• 1.0.0: Habblaud World, an online city of Habblaud offices (below).
• 0.11.0: phone access with login and HTTPS, a New agent button that starts a background Claude Code session in a folder you pick, local dictation with Whisper, and messages for Claude desktop app sessions.
• 0.10.0: the interface in English, Spanish and French, and the seasonal themes.
• 0.9.0: an interactive terminal that runs the real Claude Code in an office window and can take over or end a session open elsewhere. It and New agent stay off unless you set HABBLAUD_PTY=1.

Habblaud World

Habblaud World is an online pixel-art city where each Habblaud becomes a building, lit live while your agents work. You walk around with a character, visit other offices (view only, with made-up room names) and greet people with ready-made phrases; there is no free text.

It is on by default, pointing at server.habblaud.com, but nothing leaves your computer until you create an account, which joins a waiting list. Your building then sends the theme, one floor per open room under a random daily code, and each agent’s tool, status, look, a drawn name and a band of tasks done. Paths, project names, commands, messages, code, cost, model and your Claude account never leave, and See what was sent shows the last upload. HABBLAUD_WORLD=0 removes the feature.

How it works

The mod hooks three events. On session.start and each session.measure (after every turn, and when a limit moves a whole point) it writes the plan’s five-hour and weekly percentages, with reset times, to ~/.habblaud/usage/<account>.json; that file is all it saves. Every 5 seconds it asks the local server at http://127.0.0.1:4747/api/mod/summary who needs you, sending its account and session id so it can leave itself out; with the server down, it asks every 30 seconds. It does not read the conversation or call the model, so /habblaud costs no tokens. In claude -p and the Agent SDK it does not poll.

The server reads, every second, the session records and transcripts Claude Code writes in each account’s sessions/ and projects/, and builds activities, stats and GitHub events from them without calling GitHub. It also reads the email, organization and /usage cache from .claude.json, and only the alias lines that launch claude from your shell files, to letter each account. It reads no credentials and masks known token formats. It keeps character names, a 7-day timelapse timeline (HABBLAUD_TIMELINE=0 stops it) and 30 days of stats.

Nothing about your sessions leaves the machine unless you join Habblaud World. The release check, every 6 hours, shows GitHub your IP and version; HABBLAUD_UPDATE_CHECK=0 turns it off. The server listens on 127.0.0.1:4747 only.

Answering, messaging and the interactive terminal work only over localhost (or the phone login, if you set it up), so a website open in your browser cannot trigger them. Any program on your machine that reaches localhost:4747, an agent running a command included, can. On a shared computer or with unattended agents, leave those plugins and HABBLAUD_PTY off. A permission request reaches the office only while a Habblaud page is open, and returns to the terminal after 5 minutes without an answer.

Limitations

• The line under the prompt and the /habblaud reply are always in Portuguese, as is any interface text still untranslated.
• Claude Code’s session files are undocumented, so a Claude Code update can break Habblaud until it is adjusted.
• Usage figures need a subscription plan and arrive after each account’s next response.
• The timelapse and stats cover only the time the server was running.
• In Docker, a Claude Code process killed abruptly can leave its character behind; Node mode checks processes.
• Windows is not on the author’s list. Native Windows, without Docker or WSL, breaks in several places (issue #162); a pull request to fix it is open.

What people say

We found no Reddit or Hacker News threads yet. The talk is in the repository’s issues, mostly in Portuguese, where users ask for more agents in the office (OpenCode, Cursor, Kiro CLI).

• VS Code. The author says it works when Claude Code runs inside VS Code, but one user found the message box blocked from the VS Code chat until the session ran in a PowerShell terminal (issue #23).
• Ghost sessions. In Docker on Linux and WSL, one user counted 31 agents, 11 of them the same session, because stale session records pile up and the container cannot check live processes (issue #157).
• Dev servers. A dev server left running in the background keeps its agent “waiting on shell” for hours (issue #175).
• Docker security. A contributor reported, against 0.8.0, that in Docker the routes that act on sessions trust the Host header, so another container on the same Docker network could answer permissions or queue messages. The issue is still open (issue #70).

Common questions

Where is Habblaud on GitHub?

At github.com/marmottajr/habblaud, under the MIT license. It was called CodeTown up to version 0.3.2, and the old address redirects. The project’s site, habblaud.com, points to the same repository.

How do I switch Habblaud to English?

The interface follows your browser’s language, and Settings › Language pins one. Texts the server builds (activities, notices, terminal, logs) follow HABBLAUD_LANG or the system language, but an English system still gets Portuguese. Add HABBLAUD_LANG=en to the .env file in the Habblaud folder and run npm run docker:up again, or start Node mode with HABBLAUD_LANG=en npm start.

Is there a phone version?

No app: you open the office in your phone’s browser on the same Wi-Fi, and the layout adapts. The quick way is HABBLAUD_BIND=0.0.0.0 in .env (HABBLAUD_HOST in Node mode), but then anyone on the network sees commands, files and session titles, and answering switches off. To approve requests from the phone, run npm run remote:setup and npm run docker:up instead: that opens a second port with a username, a password and HTTPS, and HABBLAUD_REMOTE_ALLOW can add messages. The README also covers Tailscale for use away from home.