marmottajr/habblaud

Maintainer? Show your league in your README

Card: your league's emblem, from Copper to Legendary

[![bestofgithub](https://bestofgithub.dev/badge/marmottajr/habblaud.svg?style=card)](https://bestofgithub.dev/repo/marmottajr/habblaud)

Flat: fits beside your other badges

[![bestofgithub](https://bestofgithub.dev/badge/marmottajr/habblaud.svg)](https://bestofgithub.dev/repo/marmottajr/habblaud)

Loading README…

State	What you see
Working	At the desk, typing. The monitor and a bubble show the activity: 📖 reading, ✏️ editing, 💻 terminal, 🧪 tests, 🌐 searching…
Needs you	Rushes to the desk and raises a hand, with a blinking alert: it's waiting for a permission or an answer in the terminal.
Waiting on shell	Finished its turn but left a command running (tests, build, deploy…), so it stays at the desk with an hourglass flipping over its head and the terminal in progress: it eats popcorn while watching, after 3 min it crosses its arms and spins in its chair, after 10 min it gathers cobwebs and after 25 min it dozes off; when the command finishes, it stands up and celebrates with confetti (or gets a rain cloud, if it failed). After 40 s, if there are coworkers with nothing to do, it may head out to a hangout — with the hourglass over its head.
Idle	Finished its turn and wanders around: coffee in the kitchen, the water cooler, the restroom, the lounge couch, the phone on the beanbag, the mirror. With idle coworkers around, it joins a hangout: TV, video games, ping-pong, a kitchen chat, rock-paper-scissors (see Social life). After 10 min without moving, it dozes off — but a coworker may wake it up for a hangout.
Subagent done	Walks over to the agent that called it, delivers the result and leaves by elevator.
Session ended	Leaves; if it was the last one in the room, it turns off the lights on the way out.

Event	What happens
🎉 PR opened or merged, release published	Confetti falls in the room, everyone celebrates by hopping and a banner says why ("PR #12 merged!") for ~12 s.
🚨 Red CI	A rotating beacon flashing in the corners of the room, a reddish floor and a "!" bubble over whoever saw the failure, until a green CI in the room (which turns into a party) or for 10 min.
🚀 Push	Just the notice and the feed.

Source	How it works
Habblaud mod (recommended)	Live, as described above. Replaces the tap: `mod:install` removes the tap from the account.
Statusline tap (Claude Code older than 2.1.287)	Live, through the statusline command, in the same file.
`/usage` cache (always on)	Claude Code saves the last result of the `/usage` command. In Node mode, Habblaud rereads it every 60 s; in Docker, the value read at the last `npm run docker:up` applies. It only changes when someone runs `/usage`.

Variable	Default	What for
`HABBLAUD_PORT`	`4747`	HTTP port (in Docker, the port published on the host).
`HABBLAUD_HOST`	`127.0.0.1`	Server interface in Node mode. Anything other than `127.0.0.1`/`localhost` turns off the terminal (and answering and sending messages from the office).
`HABBLAUD_BIND`	`127.0.0.1`	Docker only (in `.env`): where the port is published. `0.0.0.0` opens it to the local network (and turns off the terminal and anything that acts on the sessions).
`HABBLAUD_CLAUDE_DIRS`	automatic detection	Account folders, comma-separated (e.g. `/caminho/conta1,/caminho/conta2`).
`HABBLAUD_DATA_DIR`	`~/.habblaud`	Where Habblaud keeps its own data (character and room names, the timelapse timeline and the My day stats).
`HABBLAUD_TIMELINE`	on	`0` turns off timeline recording (the days already recorded stay in the timelapse). In Docker it's always on.
`HABBLAUD_USAGE_DIR`	`~/.habblaud/usage`	Where the mod (or the statusline tap) writes usage.
`HABBLAUD_DEMO`	off	`1` turns on demo mode at startup.
`HABBLAUD_ALLOWED_HOSTS`	—	Extra names accepted in the address (e.g. `meu-mac.local`), besides `localhost` and IPs.
`HABBLAUD_TERMINAL`	on (local access only)	`0` turns off the terminal, answering and sending messages from the office, and the character editor. With the port exposed they're already off, with no way to turn them on.
`HABBLAUD_PTY`	off	`1` turns on the interactive terminal (open, take over and end Claude Code sessions from the office; local access only and outside Docker) and New agent (also in Docker, through `npm run codex:bridge`). Read the warning in Privacy and security.
`HABBLAUD_CLAUDE_BIN`	`claude` from PATH	The Claude Code executable that the interactive terminal and New agent run.
`HABBLAUD_REMOTE_ALLOW`	`permissions`	What the phone with login can do: `permissions`, `messages`, `terminal`, `spawn` (comma-separated) or `none`. The other `HABBLAUD_REMOTE_*` are written by `npm run remote:setup`.
`HABBLAUD_MENSAGENS`	on (with the terminal)	`0` turns off only messages from the office (the box in the terminal and in the agent's details).
`HABBLAUD_CODEX`	on	`0` turns off Codex in the office.
`HABBLAUD_CODEX_DIRS`	automatic detection	Codex folders, comma-separated (instead of `~/.codex*` and `CODEX_HOME`).
`HABBLAUD_CODEX_BIN`	`codex` from PATH (on Windows, `codex.exe`)	The Codex binary that delivers the messages (`codex queue`), in Node mode or in `npm run codex:bridge`.
`HABBLAUD_UPDATE_CHECK`	on	`0` turns off the new-version check (a request to the repository's releases on GitHub every 6 h).
`HABBLAUD_LANG`	system language (except English), otherwise `pt-BR`	Language of the texts the server builds (activities, notices, logs): `pt-BR`, `en`, `es` or `fr`. The interface follows the browser or the choice in Settings › Language. See Languages.
`HABBLAUD_ACCOUNTS`	—	JSON to customize name, letter or color, matched by the account folder name. E.g. `[{"id":".claude-conta2","name":"Trabalho","short":"T","color":"#5cc97b"}]`.

Variable	Default	What for
`HABBLAUD_WORLD_URL`	`https://server.habblaud.com`	World server address, `https://` or `wss://` only (no path).
`HABBLAUD_WORLD`	on	`0` turns off everything about the World (routes and interface) and nothing leaves your computer.
`HABBLAUD_WORLD_DEV`	off	`1` accepts a local world server without TLS: `http://127.0.0.1:<port>` (`npm run dev` already does) or, from inside Docker, `http://host.docker.internal:<port>`.


Agent details: current activity, tasks with progress, subagents, timeline and stats.	Day and night: the sky in the windows and the lighting follow local time.

Route	Description
`GET /api/stream`	SSE with the `snapshot`, `feed` and `notice` events (format in `shared/types.ts`).
`GET /api/snapshot`	Current state of the office.
`GET /api/agents/:id`	An agent's details, with up to 200 activities.
`GET /api/agents/:id/terminal`	Terminal SSE (`init` and `append` events); local access only.
`PUT /api/agents/:id/character`	Edit the character: `{name, seed, parts}` saves the main agent's name and look as the project's (the room's) character; local access only.
`DELETE /api/agents/:id/character`	"Back to random": deletes the project's character and the agent goes back to its random name; local access only.
`GET /api/sessions/recent`	Session history: sessions from the last 7 days across all accounts (up to 150); local access only.
`GET /api/sessions/:conta/:sessionId/terminal`	SSE of the conversation of a session from the history (same protocol as the terminal); local access only.
`GET /api/stats?day=AAAA-MM-DD`	My day stats (time per status, projects, accounts, hours, waits, tokens and cost).
`GET /api/stats/days`	Days with stats (the last 30).
`GET /api/timeline/days`	Days recorded for the timelapse, with size and the time of the first and last entries.
`GET /api/timeline/:dia`	A day's timeline (`AAAA-MM-DD`), in JSONL (gzipped).
`GET /api/health`	Health: version, demo, Docker, terminal, answering and sending messages from the office, sources and usage status of each account.
`POST /api/demo`	`{"enabled": true \| false}` turns the simulated agents on or off.
`POST /api/rooms/rename`	`{"id": sala, "name": nome}` renames the room (empty goes back to the folder name); the name is stored in `rooms.json`, in the data folder. Local access only.
`GET /api/mod/summary`	For the Claude Code mod: version, how many agents, how many are working and who needs you (without the demo and, with `?account=&session=`, without its own session).
`/api/permissions…`	Answering from the office: the permission hook registers the request (permission or question) and waits; the page fetches the details and decides or answers. Local access only.
`/api/messages…` and `/api/mod/inbox…`	Sending messages: the page puts the message in the queue and follows its delivery; the `habblaud-mensagens` plugin fetches it, delivers it to the session and confirms. Local access only.
`POST /api/codex/events`	Events from the Codex hooks (session opened, tool, approval, end of turn). Local access only.
`/api/codex/bridge/poll` and `/ack`	`npm run codex:bridge` fetches the messages for Codex and confirms delivery. Local access only.

Host	Container	What for
`<conta>/sessions/`	`/claude/<conta>/sessions` (read-only)	Open sessions and their status.
`<conta>/projects/`	`/claude/<conta>/projects` (read-only)	Transcripts of the sessions and subagents.
`~/.habblaud/usage/`	`/usage` (read-only)	Usage captured by the mod (or by the statusline tap).
`habblaud-data` volume	`/data`	Habblaud's own data (character names, the timelapse timeline and the My day stats).
`~/.habblaud/remote-tls/server/`	`/remote-tls` (read-only)	Only after `npm run remote:setup`: the server certificate and key of the phone with login (never the CA key).

Command	What it does
`npm run dev`	Server + Vite at http://localhost:4747, with hot reload.
`npm run dev:client`	Vite only, at http://localhost:5173 (open it with `?mock=1`; `/api` is proxied to port 4747).
`npm run demo`	`npm run dev` with demo mode on.
`npm run build` / `npm start`	Builds and runs the production version.
`npm test`	Tests (Vitest).
`npm run typecheck`	Type checking for the client, the server and the scripts.
`claude plugin test mod/habblaud`	Mod tests (no session, account or network); same for `mod/habblaud-mensagens`.
`claude plugin validate .`	Validates the marketplace (`.claude-plugin/marketplace.json`); with `mod/habblaud`, `mod/habblaud-permissoes` or `mod/habblaud-mensagens`, validates the plugin and lists the mod's events and calls.
`claude --plugin-dir mod/habblaud`	Opens a session with the mod from this folder, without installing it (edit and run `/reload-plugins`).
`npm run mod:status`	Shows, per account, the marketplace, the plugins and the installed versions.
`npm run demo:timeline`	Generates a made-up timeline (demo mode simulator) for the timelapse.
`npm run release`	Publishes the `package.json` version on GitHub (tag and release with the notes from `CHANGELOG.md`).

	Hangout	What happens
📺	TV in the lounge	Soccer, a soap opera or cartoons, with popcorn on the couch. During soccer the fans cheer along with the "GOL" flashing on the screen (or groan at the other team's goal); during the soap opera, little hearts and "No way! 😱". Nap lovers end up falling asleep on the couch.
🎮	Video games	Two on the couch with controllers, the TV in split screen (racing or fighting), best of 3, trash talk ("What's with this lag?!") and fans.
👾	Arcade	A duel at the lounge's two machines, a single match.
🏓	Ping-pong	Up to 5 points, with the ball going back and forth, the score in the bubbles ("3 × 2 🏓") and fans behind the table.
☕	Kitchen chat	Each one grabs a coffee (or water) and sits at the table: gossip with coworkers' names ("Did you see Rafaela's commit? 👀"), jokes (the group cracks up), work talk ("Deploy on a Friday? 😈") and topics about the day and the time ("TGIF! 🎉").
💬	Chat	Two coworkers standing in a corner of the lobby, the kitchen or the lounge.
✊	Rock-paper-scissors for coins	"Jo… Ken… Po!", the hand signs appear over their heads, the winner celebrates and the coins fly from one to the other; the loser gets upset and, if competitive, asks for a rematch. A tie goes again. Anyone walking by may stop to watch.
💄	Bathroom mirror	Lipstick or a comb, with the face reflected in the mirror and a sparkle at the end. Works alone or in pairs ("Can I borrow your comb?").


Rock-paper-scissors for coins. The bet comes from the personality (betting lovers bet big, penny-pinchers bet little) and never goes over the balance of whoever has less.	Kitchen chat. Whoever is more sociable talks more; the reactions depend on the topic (a big laugh at a joke, 👀 at gossip).

At the mirror. Vanity lovers stop by the restroom whenever they can — and show up reflected.	In the agent's details. What it's doing, the wallet, the score, the personality, friendships and rivalries (with the head-to-head record) and the statement.


Arrived at the office	🪙100 (subagents, 🪙30)
Task done (item on the task list)	+🪙10
Request handled (end of turn)	+🪙5
Subagent delivered the result	+🪙15
Bets (rock-paper-scissors; matches between rivals or with betting lovers)	whatever the loser loses goes to the winner

Habblaud

Contents

What it looks like

Installation

Requirements

1. Get the project

2. Start Habblaud

3. Install the Habblaud mod in Claude Code (recommended)

4. Codex in the office (optional)

Open on your phone (optional)

Phone with login and HTTPS (approving requests)

Updating

Coming from CodeTown

Uninstalling

How to use

What each character is doing

Interface

Office themes

Languages

Day, night and sounds

Terminal

Interactive terminal (take over, new session and end)

Day timelapse

Answering from the office

Sending messages

Editing the character

Codex

GitHub in the office

My day

Demo mode

Accounts and usage (5-hour and weekly)

Configuration

Habblaud World

How it works

Privacy and security

Development

Troubleshooting

Disclaimer

License

Social life

The hangouts

Personalities

Coins