busybits 0.0.0-stage → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (111) hide show
  1. package/.claude-plugin/marketplace.json +26 -0
  2. package/CHANGELOG.md +675 -0
  3. package/LICENSE +21 -0
  4. package/README.es.md +1457 -0
  5. package/README.fr.md +1435 -0
  6. package/README.md +1605 -2
  7. package/README.pt-BR.md +1373 -0
  8. package/dist/build.json +5 -0
  9. package/dist/cli/busybits.js +14708 -0
  10. package/dist/client/assets/art/framed/painting-abstract.png +0 -0
  11. package/dist/client/assets/art/framed/painting-beach.png +0 -0
  12. package/dist/client/assets/art/framed/painting-cat.png +0 -0
  13. package/dist/client/assets/art/framed/painting-city-night.png +0 -0
  14. package/dist/client/assets/art/framed/painting-mountains.png +0 -0
  15. package/dist/client/assets/art/framed/painting-rio.png +0 -0
  16. package/dist/client/assets/art/framed/painting-sunflowers.png +0 -0
  17. package/dist/client/assets/art/framed/painting-wave.png +0 -0
  18. package/dist/client/assets/art/framed/painting-wide-aurora.png +0 -0
  19. package/dist/client/assets/art/framed/painting-wide-color-fields.png +0 -0
  20. package/dist/client/assets/art/framed/painting-wide-forest-lake.png +0 -0
  21. package/dist/client/assets/art/painting-abstract.png +0 -0
  22. package/dist/client/assets/art/painting-beach.png +0 -0
  23. package/dist/client/assets/art/painting-cat.png +0 -0
  24. package/dist/client/assets/art/painting-city-night.png +0 -0
  25. package/dist/client/assets/art/painting-mountains.png +0 -0
  26. package/dist/client/assets/art/painting-rio.png +0 -0
  27. package/dist/client/assets/art/painting-sunflowers.png +0 -0
  28. package/dist/client/assets/art/painting-wave.png +0 -0
  29. package/dist/client/assets/art/painting-wide-aurora.png +0 -0
  30. package/dist/client/assets/art/painting-wide-color-fields.png +0 -0
  31. package/dist/client/assets/art/painting-wide-forest-lake.png +0 -0
  32. package/dist/client/assets/art/poster-bug.png +0 -0
  33. package/dist/client/assets/art/poster-cat.png +0 -0
  34. package/dist/client/assets/art/poster-code.png +0 -0
  35. package/dist/client/assets/art/poster-coffee.png +0 -0
  36. package/dist/client/assets/art/poster-rocket.png +0 -0
  37. package/dist/client/assets/art/poster-ship-it.png +0 -0
  38. package/dist/client/assets/brand/apple-touch-icon.png +0 -0
  39. package/dist/client/assets/brand/favicon-16.png +0 -0
  40. package/dist/client/assets/brand/favicon-32.png +0 -0
  41. package/dist/client/assets/brand/icon-192.png +0 -0
  42. package/dist/client/assets/brand/icon-512.png +0 -0
  43. package/dist/client/assets/brand/logo-detailed.png +0 -0
  44. package/dist/client/assets/brand/logo-mark.png +0 -0
  45. package/dist/client/assets/brand/logo-mark@4x.png +0 -0
  46. package/dist/client/assets/brand/signage.png +0 -0
  47. package/dist/client/assets/brand/signage@4x.png +0 -0
  48. package/dist/client/assets/emoji/LICENSE-SerenityOS.txt +28 -0
  49. package/dist/client/assets/emoji/sheet.png +0 -0
  50. package/dist/client/assets/illustrations/empty-office.png +0 -0
  51. package/dist/client/assets/manifest.json +260 -0
  52. package/dist/client/assets/og-image.png +0 -0
  53. package/dist/client/bundle/app-AwZeKIeu.js +24 -0
  54. package/dist/client/bundle/app-CoDOLwxe.css +1 -0
  55. package/dist/client/bundle/city-DPTwQLdi.css +1 -0
  56. package/dist/client/bundle/city-YoIG0FsX.js +1 -0
  57. package/dist/client/bundle/daystats-DGzYOP8l.js +1 -0
  58. package/dist/client/bundle/dom-D2vx0KTo.js +1 -0
  59. package/dist/client/bundle/en-DBfNt5uV.js +169 -0
  60. package/dist/client/bundle/es-pnWdszTE.js +169 -0
  61. package/dist/client/bundle/format-C7qb6Cn-.js +1 -0
  62. package/dist/client/bundle/fr-CY8q9pj4.js +169 -0
  63. package/dist/client/bundle/main-DktU0GfB.js +2 -0
  64. package/dist/client/bundle/pixelify-sans-cyrillic-400-normal-Ckz2YJkH.woff2 +0 -0
  65. package/dist/client/bundle/pixelify-sans-cyrillic-400-normal-DfOZNMlW.woff +0 -0
  66. package/dist/client/bundle/pixelify-sans-cyrillic-500-normal--wrb4dVK.woff2 +0 -0
  67. package/dist/client/bundle/pixelify-sans-cyrillic-500-normal-CR9SIKMr.woff +0 -0
  68. package/dist/client/bundle/pixelify-sans-cyrillic-600-normal-B3EuUOZG.woff +0 -0
  69. package/dist/client/bundle/pixelify-sans-cyrillic-600-normal-BhqNJYOZ.woff2 +0 -0
  70. package/dist/client/bundle/pixelify-sans-cyrillic-700-normal-BrZTw8tu.woff +0 -0
  71. package/dist/client/bundle/pixelify-sans-cyrillic-700-normal-CYtG5Rfp.woff2 +0 -0
  72. package/dist/client/bundle/pixelify-sans-latin-400-normal-DLrIX9QE.woff2 +0 -0
  73. package/dist/client/bundle/pixelify-sans-latin-400-normal-JapMNN6Z.woff +0 -0
  74. package/dist/client/bundle/pixelify-sans-latin-500-normal-Bq6pAlou.woff +0 -0
  75. package/dist/client/bundle/pixelify-sans-latin-500-normal-DC052d-m.woff2 +0 -0
  76. package/dist/client/bundle/pixelify-sans-latin-600-normal-BNlgYbDL.woff +0 -0
  77. package/dist/client/bundle/pixelify-sans-latin-600-normal-Dd_Dy7u5.woff2 +0 -0
  78. package/dist/client/bundle/pixelify-sans-latin-700-normal-BctWAS0u.woff +0 -0
  79. package/dist/client/bundle/pixelify-sans-latin-700-normal-D3Xxx3QE.woff2 +0 -0
  80. package/dist/client/bundle/pixelify-sans-latin-ext-400-normal-BkfTUL4s.woff +0 -0
  81. package/dist/client/bundle/pixelify-sans-latin-ext-400-normal-DdH6zlBQ.woff2 +0 -0
  82. package/dist/client/bundle/pixelify-sans-latin-ext-500-normal-BHT4w5qI.woff2 +0 -0
  83. package/dist/client/bundle/pixelify-sans-latin-ext-500-normal-Bkr-oq6R.woff +0 -0
  84. package/dist/client/bundle/pixelify-sans-latin-ext-600-normal-CDaIumwU.woff +0 -0
  85. package/dist/client/bundle/pixelify-sans-latin-ext-600-normal-Dha6RiOG.woff2 +0 -0
  86. package/dist/client/bundle/pixelify-sans-latin-ext-700-normal-BadXkHzZ.woff +0 -0
  87. package/dist/client/bundle/pixelify-sans-latin-ext-700-normal-ClyJstAh.woff2 +0 -0
  88. package/dist/client/bundle/ptypane-BrP-ENHg.css +1 -0
  89. package/dist/client/bundle/ptypane-NIZ2Y8QM.js +16 -0
  90. package/dist/client/bundle/room-name-CFJfHE5L.js +1 -0
  91. package/dist/client/bundle/simulator-BnBPS_Ws.js +7 -0
  92. package/dist/client/bundle/world-model-BIYmgAWC.js +1 -0
  93. package/dist/client/bundle/world-stream-BRkL9Eme.js +1 -0
  94. package/dist/client/index.html +41 -0
  95. package/dist/client/manifest.webmanifest +17 -0
  96. package/dist/server/index.js +40327 -0
  97. package/mod/README.md +193 -0
  98. package/mod/habblaud/.claude-plugin/plugin.json +11 -0
  99. package/mod/habblaud/hooks/hooks.json +4 -0
  100. package/mod/habblaud/hooks/register.ts +517 -0
  101. package/mod/habblaud-codex/hook.mjs +274 -0
  102. package/mod/habblaud-mensagens/.claude-plugin/plugin.json +11 -0
  103. package/mod/habblaud-mensagens/hooks/hooks.json +4 -0
  104. package/mod/habblaud-mensagens/hooks/register.ts +384 -0
  105. package/mod/habblaud-permissoes/.claude-plugin/plugin.json +11 -0
  106. package/mod/habblaud-permissoes/hooks/hooks.json +18 -0
  107. package/mod/habblaud-permissoes/hooks/permission-hook.mjs +265 -0
  108. package/mod/habblaud-pi/core.ts +325 -0
  109. package/mod/habblaud-pi/extension.ts +119 -0
  110. package/mod/habblaud-pi/package.json +12 -0
  111. package/package.json +96 -4
package/README.es.md ADDED
@@ -0,0 +1,1457 @@
1
+ <p align="center">
2
+ <img src="client/public/assets/brand/logo-mark@4x.png" width="96" alt="Logo de Busybits: un mosaico de pequeños bloques en pixel art" />
3
+ </p>
4
+
5
+ <h1 align="center">Busybits</h1>
6
+
7
+ <p align="center">
8
+ <b>La oficina virtual de tus agentes de Claude Code (y de Codex).</b><br />
9
+ Cada proyecto se convierte en una sala, y cada agente, en un personaje en pixel art que muestra en tiempo real lo que está haciendo.
10
+ </p>
11
+
12
+ <p align="center"><a href="README.md">English</a> · <a href="README.pt-BR.md">Português</a> · <b>Español</b> · <a href="README.fr.md">Français</a></p>
13
+
14
+ <p align="center"><sub>Basado en <a href="https://github.com/marmottajr/habblaud">Habblaud</a>, de Márcio Junior (MIT).</sub></p>
15
+
16
+ <p align="center">
17
+ <img alt="Node.js 22.12+" src="https://img.shields.io/badge/node-%E2%89%A522.12-5fa04e?logo=node.js&logoColor=white" />
18
+ <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-7-3178c6?logo=typescript&logoColor=white" />
19
+ <img alt="Docker" src="https://img.shields.io/badge/Docker-listo-2496ed?logo=docker&logoColor=white" />
20
+ <img alt="Cero dependencias de runtime" src="https://img.shields.io/badge/dependencias%20de%20runtime-0-f08a3c" />
21
+ <img alt="Interfaz en portugués, inglés, español y francés" src="https://img.shields.io/badge/interface-PT%20%C2%B7%20EN%20%C2%B7%20ES%20%C2%B7%20FR-4aa8e8" />
22
+ </p>
23
+
24
+ <p align="center">
25
+ <img src="docs/screenshots/office.gif" width="820" alt="Animación de una sala de Busybits: personajes tecleando en los escritorios, subagentes con gafete y globos de actividad" />
26
+ </p>
27
+
28
+ ---
29
+
30
+ Abres Claude Code en varios proyectos, lanzas subagentes, dejas tareas en marcha… y pierdes la noción de quién está
31
+ haciendo qué. **Busybits** convierte todo eso en una oficina que se entiende de un vistazo: quién está tecleando,
32
+ quién levantó la mano porque **te necesita**, quién entregó el trabajo y se fue, quién salió a tomar un café
33
+ mientras espera la próxima instrucción, y cuánto llevas gastado de cada cuenta en la sesión de 5 horas y en la semana.
34
+
35
+ Y cuando dos o más agentes no tienen nada que hacer, la oficina cobra **vida social**: cada uno tiene su propia
36
+ personalidad, y ven fútbol juntos en el salón, juegan videojuegos y ping-pong, chismean en la cocina, se arreglan
37
+ frente al espejo y se apuestan monedas a piedra, papel o tijera. Míralo en [Vida social](#vida-social).
38
+
39
+ Todo se ejecuta en tu máquina, leyendo los archivos que el propio Claude Code ya guarda (y solo las líneas `alias` de
40
+ tu shell, para asignarle una letra a cada cuenta). Nada sale de tu computadora: Busybits no lee credenciales ni hace
41
+ llamadas externas.
42
+
43
+ ## Índice
44
+
45
+ - [Cómo se ve](#cómo-se-ve)
46
+ - [Instalación](#instalación)
47
+ - [Cómo usar](#cómo-usar)
48
+ - [Cuentas y uso (5 horas y semanal)](#cuentas-y-uso-5-horas-y-semanal)
49
+ - [Configuración](#configuración)
50
+ - [Habblaud World](#habblaud-world)
51
+ - [Cómo funciona](#cómo-funciona)
52
+ - [Privacidad y seguridad](#privacidad-y-seguridad)
53
+ - [Desarrollo](#desarrollo)
54
+ - [Solución de problemas](#solución-de-problemas)
55
+ - [Aviso](#aviso)
56
+ - [Licencia](#licencia)
57
+ - [Vida social](#vida-social)
58
+
59
+ ## Cómo se ve
60
+
61
+ **Vista general.** El edificio tiene recepción con ascensores, cocina, baños y salón; cada proyecto con una sesión
62
+ abierta tiene su propia sala a lo largo del pasillo. Arriba, los contadores y el uso de cada cuenta; a la izquierda,
63
+ las salas y los agentes; abajo, el feed de actividad.
64
+
65
+ ![Vista general de Busybits: edificio con recepción, cocina, baños, salón y salas de proyecto; barra lateral con salas y agentes; uso de las cuentas arriba; feed de actividad abajo](docs/screenshots/overview.png)
66
+
67
+ <table>
68
+ <tr>
69
+ <td width="50%"><img src="docs/screenshots/agent-details.png" alt="Panel de detalles de un agente con tareas, subagentes, línea de tiempo y estadísticas" /></td>
70
+ <td width="50%"><img src="docs/screenshots/night.png" alt="La oficina de noche, con los faroles encendidos y las salas iluminadas" /></td>
71
+ </tr>
72
+ <tr>
73
+ <td><b>Detalles del agente:</b> actividad actual, tareas con su progreso, subagentes, línea de tiempo y estadísticas.</td>
74
+ <td><b>Día y noche:</b> el cielo en las ventanas y la iluminación siguen la hora local.</td>
75
+ </tr>
76
+ </table>
77
+
78
+ <table>
79
+ <tr>
80
+ <td width="42%"><img src="docs/screenshots/collab.png" alt="Subagente entregando el resultado al agente principal mientras otra agente pide permiso" /></td>
81
+ <td width="58%">
82
+ <b>Colaboración a la vista.</b> Los subagentes son compañeros con nombre propio y gafete: llegan por el ascensor,
83
+ trabajan en la sala del proyecto y, al terminar, van hasta el agente que los llamó a entregarle el resultado (📦)
84
+ antes de irse.<br /><br />
85
+ <b>Te necesita.</b> Cuando un agente espera un permiso o una respuesta en la terminal, corre a su escritorio y
86
+ levanta la mano, con una alerta parpadeando, y aparece un aviso en pantalla (opcionalmente con sonido y notificación
87
+ del navegador). Desde ahí mismo puedes aprobar, responder la pregunta o enviarle la siguiente instrucción.
88
+ </td>
89
+ </tr>
90
+ </table>
91
+
92
+ <table>
93
+ <tr>
94
+ <td width="58%">
95
+ <b>Esperando el shell.</b> Cuando el agente termina su turno pero deja un comando en ejecución (pruebas, build,
96
+ deploy…), no sale a pasear: se queda en su escritorio con un reloj de arena girando sobre la cabeza, la terminal
97
+ mostrando el progreso y un globo con el comando y el tiempo. Y la espera se vuelve comedia: primero come palomitas
98
+ mirando la terminal; a los 3 min se cruza de brazos y da vueltas en la silla; a los 10 min junta telarañas; a los
99
+ 25 min se queda dormido. Cuando el comando termina, se levanta y lo celebra con confeti, o le cae una nube de
100
+ lluvia si falló. En la lista lateral y en los detalles, un cronómetro muestra cuánto tiempo lleva cada comando en
101
+ ejecución.
102
+ </td>
103
+ <td width="42%"><img src="docs/screenshots/shell-wait.png" alt="Agente comiendo palomitas en su escritorio, con un reloj de arena sobre la cabeza y el globo 'Ejecutar la suite de pruebas · 1 min'; en la fila de adelante, una compañera lleva más tiempo esperando, con telarañas en la silla y la terminal mostrando el progreso" /></td>
104
+ </tr>
105
+ </table>
106
+
107
+ **La luz se apaga.** Cuando cierras la última sesión de un proyecto, el último personaje va hasta el interruptor,
108
+ apaga la luz y sale por el ascensor; luego la sala se desmonta y se convierte en jardín hasta que llegue un proyecto
109
+ nuevo. Si el jardín quedó entre dos salas, la sala más lejana se muda ahí: se monta en el lugar libre, el equipo
110
+ camina hasta ella y la dirección antigua se apaga y se desmonta. Así el edificio no se queda con huecos y se encoge
111
+ solo.
112
+
113
+ | 1. La sala se monta, todavía a oscuras | 2. Alguien enciende la luz y todos trabajan | 3. El último sale y apaga la luz | 4. La sala se convierte en jardín |
114
+ | --- | --- | --- | --- |
115
+ | ![Sala montándose, con los muebles apareciendo y la luz apagada](docs/screenshots/lifecycle-1.png) | ![Sala iluminada con tres agentes trabajando en sus escritorios](docs/screenshots/lifecycle-2.png) | ![Sala con la luz apagada y los muebles todavía en su lugar, después de que todos salieron](docs/screenshots/lifecycle-3.png) | ![El lote de la sala convertido en jardín](docs/screenshots/lifecycle-4.png) |
116
+
117
+ <table>
118
+ <tr>
119
+ <td width="34%"><img src="docs/screenshots/mobile.png" alt="Busybits en el celular, con el uso de las cuentas arriba" /></td>
120
+ <td>
121
+ <b>También en el celular.</b> La interfaz se adapta a pantallas pequeñas: el uso de las cuentas queda arriba, la
122
+ lista de salas se convierte en un panel deslizable y los detalles se abren de abajo hacia arriba. Mira cómo
123
+ habilitar el acceso desde la red local en <a href="#abrir-en-el-celular-opcional">Abrir en el celular</a>.
124
+ </td>
125
+ </tr>
126
+ </table>
127
+
128
+ > Las imágenes de arriba usan el **modo demostración** (proyectos, personas y cuentas ficticios).
129
+
130
+ ## Instalación
131
+
132
+ ### Instalar (npm)
133
+
134
+ Necesita **Node.js 22.12+** y npm. Sin clonar y sin compilar:
135
+
136
+ ```bash
137
+ npx busybits setup --service
138
+ # o, para dejar el comando instalado:
139
+ npm i -g busybits && busybits setup --service
140
+ ```
141
+
142
+ `busybits setup` instala la versión empaquetada en `~/.busybits`, instala el mod de Claude Code, la extensión de Pi y
143
+ los hooks de Codex (cada uno solo si la herramienta existe) y, con `--service`, un servicio de usuario siempre activo
144
+ (`busybits.service` en Linux, `com.busybits.server` en macOS). Luego abre **http://localhost:4747**. Opciones de setup:
145
+ `--service`, `--port <n>`, `--no-claude`, `--no-pi`, `--no-codex`, `--dry-run`, `--ignore-node`.
146
+
147
+ | Comando | Qué hace |
148
+ | --- | --- |
149
+ | `busybits status` | muestra la instalación y el estado del servicio |
150
+ | `busybits start` | ejecuta el servidor en primer plano |
151
+ | `busybits update` | actualiza a la última versión (ver [Actualizar](#actualizar)) |
152
+ | `busybits update --rollback` | vuelve a la versión anterior |
153
+ | `busybits uninstall` | quita extensiones y servicios (`--purge` borra también los datos) |
154
+ | `busybits pair` | empareja esta máquina como satélite de un Busybits central |
155
+
156
+ **Dónde queda cada cosa**
157
+
158
+ - `~/.busybits` (`BUSYBITS_HOME` lo cambia): las versiones instaladas, los shims del comando y el marketplace.
159
+ - Los datos siguen en `~/.habblaud` y el archivo de entorno en `~/.config/habblaud/env`, como antes; una instalación
160
+ desde un clon se asume en el sitio y conserva su emparejamiento y su estado TLS.
161
+ - `habblaud.service` / `com.habblaud.server` pasan a ser `busybits.service` / `com.busybits.server` (setup quita los
162
+ antiguos).
163
+
164
+ **Conviene saber**
165
+
166
+ - **Codex:** tras la primera toma de control, vuelve a aprobar los hooks de Busybits en `/hooks` de Codex.
167
+ - **Linux:** `node-pty` (toma de control de la terminal) solo compila con herramientas de compilación (una cadena de
168
+ herramientas C/C++ y Python, para node-gyp); sin ellas la instalación funciona y la toma de control queda desactivada.
169
+ - **Node y el servicio:** el servicio empaquetado arranca mediante un shim que busca Node en cada inicio, así que
170
+ cambiar de versión de Node es seguro. Un servicio instalado **desde un clon** fija el Node que ejecutó `npm run
171
+ setup`; vuelve a ejecutar setup tras cambiar de Node.
172
+ - **Windows:** `busybits setup`, `update` y `uninstall` se niegan allí y señalan `scripts/windows/install-satellite.ps1`
173
+ (desde un clon).
174
+
175
+ ### Desde un clon (desarrollo)
176
+
177
+ En una máquina nueva, desde un clon del repositorio:
178
+
179
+ ```bash
180
+ git clone https://github.com/marmottajr/habblaud.git
181
+ cd habblaud
182
+ npm run setup
183
+ ```
184
+
185
+ `npm run setup` hace lo que falte de lo que sigue y se salta lo que ya está hecho, así que se puede ejecutar de nuevo sin riesgo:
186
+
187
+ 1. comprueba Node (22.12+ o 24; si no, te indica cómo conseguirlo con [nvm](https://github.com/nvm-sh/nvm):
188
+ `nvm install 24 && nvm use 24`);
189
+ 2. `npm ci` (solo si falta `node_modules` o es más viejo que `package-lock.json`) y `npm run build` (solo si falta
190
+ `dist/` o es más viejo que el código);
191
+ 3. escribe `~/.config/habblaud/env` (`HABBLAUD_ENV_FILE` o `XDG_CONFIG_HOME` cambian el lugar) con el puerto y las
192
+ cuentas de Claude Code, **sin** carpetas sobrantes como `.claude.retired` o `.claude.backup-…`, que si no
193
+ aparecerían como cuentas fantasma. El servidor lee este archivo solo al arrancar (lo que ya esté en el entorno
194
+ manda); solo se reescribe el bloque entre las marcas `habblaud setup`;
195
+ 4. instala el mod de Claude Code en esas cuentas (`npm run mod:install`), si `claude` está en el `PATH`;
196
+ 5. instala la extensión **habblaud-pi** en Gentle Shell (`~/.gentle-shell/agent`) y en Pi (`~/.pi/agent`), las que
197
+ existan (`npm run pi:install`): los mensajes de la oficina llegan a la sesión y, cuando Pi abre una caja de pregunta
198
+ (por ejemplo *"Allow guarded git push? Yes/No"* de gentle-pi), el agente aparece en la oficina esperando, con el
199
+ comando; la respuesta se da en la terminal;
200
+ 6. con `npm run setup -- --service`, instala un servicio de **usuario** siempre activo (sin sudo): una unidad de
201
+ usuario de systemd en Linux (`~/.config/systemd/user/busybits.service`) o un LaunchAgent en macOS
202
+ (`com.busybits.server`) que ejecuta el servidor compilado con ese entorno. Windows no tiene servicio: usa `npm start`.
203
+
204
+ ```bash
205
+ npm run setup -- --dry-run # muestra lo que haría, no cambia nada
206
+ npm run setup:status # qué está listo y qué falta
207
+ npm run setup:uninstall # quita el servicio, la extensión de Pi y el mod (--purge borra también el archivo de entorno)
208
+ ```
209
+
210
+ Otras opciones: `--port <n>`, `--no-claude`, `--no-pi`, `--rebuild`, `--ignore-node`. Luego ejecuta `npm start` (o deja
211
+ que el servicio lo arranque) y abre **http://localhost:4747**. Los pasos de abajo son la versión manual de lo mismo.
212
+
213
+ ### Requisitos
214
+
215
+ - **macOS** (probado) o Linux.
216
+ - **[Claude Code](https://code.claude.com)** instalado, con una o más cuentas (2.1.287 o más reciente para el mod).
217
+ - **Node.js 22.12+** y **npm** (desarrollado con Node 24; Docker ya usa Node 24).
218
+ - **Docker Desktop** (o Docker Engine con Compose v2), si lo vas a ejecutar en un contenedor.
219
+
220
+ ### 1. Descarga el proyecto
221
+
222
+ ```bash
223
+ git clone https://github.com/marmottajr/habblaud.git
224
+ cd habblaud
225
+ npm install
226
+ ```
227
+
228
+ > `npm install` solo descarga herramientas de compilación (Vite, TypeScript, tsx…). El servidor de Busybits no tiene
229
+ > dependencias de runtime: usa solo módulos nativos de Node.
230
+
231
+ ### 2. Inicia Busybits
232
+
233
+ **Opción A: Docker (recomendado para dejarlo siempre encendido)**
234
+
235
+ ```bash
236
+ npm run docker:up
237
+ ```
238
+
239
+ El script detecta tus cuentas de Claude Code, monta solo las carpetas necesarias (en modo de solo lectura), construye
240
+ la imagen e inicia el contenedor, que se reinicia solo junto con Docker. Abre **http://localhost:4747**.
241
+
242
+ **Opción B: Node, sin Docker**
243
+
244
+ ```bash
245
+ npm run build
246
+ npm start
247
+ ```
248
+
249
+ Abre **http://localhost:4747**. Para desarrollar, usa `npm run dev` (servidor + Vite con recarga automática).
250
+
251
+ Ahora abre Claude Code en cualquier proyecto y mira cómo tu agente llega por el ascensor. 🎉
252
+
253
+ ### 3. Instala el mod de Busybits en Claude Code (recomendado)
254
+
255
+ ```bash
256
+ npm run mod:install # o mod e os plugins de permissões e de mensagens, em cada conta
257
+ npm run mod:install -- --sem-permissoes # sem responder permissões e perguntas pelo escritório
258
+ npm run mod:install -- --sem-mensagens # sem mandar mensagens aos agentes pelo escritório
259
+ ```
260
+
261
+ Busybits incluye un [mod](https://code.claude.com/docs/en/plugins/mods/overview) (un plugin que se ejecuta dentro de
262
+ Claude Code) y lo instala en cada cuenta, con el propio `claude plugin`, a partir de esta carpeta. Con él:
263
+
264
+ - el **uso de 5 horas y semanal** de cada cuenta aparece en vivo en Busybits;
265
+ - la terminal muestra una línea cuando **otra sesión te necesita** (permiso o respuesta);
266
+ - el comando **`/busybits`** pasa a existir en Claude Code;
267
+ - puedes **aprobar o rechazar desde la oficina** las solicitudes de permiso ("Do you want to…") y **responder las
268
+ preguntas** del agente, con el plugin `busybits-permissions` (consulta [Responder desde la oficina](#responder-desde-la-oficina));
269
+ - puedes **enviarle mensajes** al agente desde la oficina, como si escribieras en su terminal, con el plugin
270
+ `busybits-messages` (consulta [Enviar mensajes](#enviar-mensajes)).
271
+
272
+ Requiere **Claude Code 2.1.287 o más reciente** (`claude --version`). El mod se ejecuta dentro de cada sesión, con tus
273
+ permisos, y accede solo a lo que está listado en [`mod/README.md`](mod/README.md); para revisarlo sin ejecutar nada,
274
+ `claude plugin validate mod/habblaud` muestra los eventos que maneja y las llamadas que hace. Las sesiones ya abiertas
275
+ cargan el mod con `/reload-plugins` (o al volver a abrirlas). Si la cuenta tenía el método antiguo (abajo), `mod:install`
276
+ quita el tap y el hook del `settings.json` (con copia de seguridad), porque el mod hace lo mismo. Compruébalo con
277
+ `npm run mod:status`; para deshacerlo: `npm run mod:uninstall`.
278
+
279
+ > El mod se lee desde esta carpeta. Si mueves la carpeta, vuelve a ejecutar `npm run mod:install`.
280
+
281
+ <details>
282
+ <summary><b>Claude Code anterior a 2.1.287: el método antiguo</b></summary>
283
+
284
+ Sin mods, el uso en vivo y responder desde la oficina vienen de dos instaladores que editan el `settings.json` de cada
285
+ cuenta (con una copia de seguridad antes):
286
+
287
+ ```bash
288
+ npm run usage:install # põe um "tap" na frente do statusline de cada conta, que captura o uso de 5h/semanal
289
+ npm run hooks:install # acrescenta o hook PermissionRequest, para responder permissões pelo escritório
290
+ ```
291
+
292
+ Tu statusline se sigue viendo igual. Para deshacerlo: `npm run usage:uninstall` y `npm run hooks:uninstall`.
293
+ Los dos apuntan a esta carpeta: si la mueves, vuelve a ejecutarlos (mientras tanto, el statusline de las cuentas
294
+ muestra un error). Cuando actualices Claude Code, cámbialos por el mod: `npm run mod:install` quita el tap y el hook
295
+ antiguos (con copia de seguridad) para que no queden dos capturando el uso o respondiendo la misma solicitud.
296
+
297
+ </details>
298
+
299
+ ### 4. Codex en la oficina (opcional)
300
+
301
+ Si también usas **Codex** de OpenAI (la CLI `codex` o la app), sus sesiones entran en la misma oficina: cada
302
+ proyecto es una sala (la misma sala de Claude Code, cuando los dos están abiertos en el mismo proyecto) y cada sesión,
303
+ un personaje con el sello **CODEX**. Busybits encuentra solo la carpeta de Codex (`~/.codex`, `CODEX_HOME` o
304
+ `~/.codex*`) y lee las conversaciones, sin instalar nada. Para ver Codex **en vivo** (qué está haciendo ahora, quién
305
+ te necesita) y aprobar comandos desde la oficina, instala los hooks:
306
+
307
+ ```bash
308
+ npm run codex:install # acrescenta os hooks do Busybits em ~/.codex/hooks.json (backup antes; os outros ficam)
309
+ npm run codex:status # confere
310
+ ```
311
+
312
+ Después, **abre Codex y aprueba los hooks de Busybits en `/hooks`**: Codex solo ejecuta un hook nuevo después de que
313
+ lo apruebas (Busybits nunca guarda esa aprobación). Con Busybits en Docker, para enviar mensajes a las sesiones de
314
+ Codex deja también `npm run codex:bridge` en ejecución en el Mac (consulta [Codex](#codex)).
315
+
316
+ ### Abrir en el celular (opcional)
317
+
318
+ Por defecto, Busybits solo acepta conexiones de la propia computadora. Para abrirlo en el celular (en la misma red
319
+ Wi-Fi), con Docker:
320
+
321
+ ```bash
322
+ printf 'HABBLAUD_BIND=0.0.0.0\n' > .env
323
+ npm run docker:up -- --no-build
324
+ ```
325
+
326
+ Luego abre `http://<ip-do-computador>:4747` en el celular (en macOS: `ipconfig getifaddr en0`; si sale vacío,
327
+ `ipconfig getifaddr en1`). En modo Node, usa `HABBLAUD_HOST=0.0.0.0 npm start`.
328
+
329
+ > ⚠️ Con esto, cualquier dispositivo de la red ve la actividad de los agentes (comandos, archivos, títulos de las
330
+ > sesiones). Úsalo solo en redes de confianza. La [terminal](#terminal) (y con ella responder y enviar mensajes desde
331
+ > la oficina) queda desactivada mientras el puerto esté expuesto. Para volver atrás: borra el `.env` y ejecuta
332
+ > `npm run docker:up -- --no-build`.
333
+
334
+ #### Celular con inicio de sesión y HTTPS (aprobar solicitudes)
335
+
336
+ En lugar de exponer el puerto principal, abre un **segundo puerto con usuario, contraseña y HTTPS**. El 4747 queda solo
337
+ en la computadora (los hooks, los plugins y tu navegador siguen funcionando sin iniciar sesión); el puerto remoto va a
338
+ la red y toda solicitud en él exige iniciar sesión. Lo que separa a los dos es el puerto por el que llegó la conexión,
339
+ nunca el encabezado Host. Nada de esto existe antes del setup: sin él, no se publica ningún puerto extra.
340
+
341
+ ```bash
342
+ npm run remote:setup # usuário, senha, nome do endereço e (opcional) um endereço próprio
343
+ npm run docker:up
344
+ ```
345
+
346
+ `remote:setup` guarda en el `.env` solo el **hash** de la contraseña (scrypt), crea una CA local y el certificado del
347
+ servidor en `~/.habblaud/remote-tls` y deja un servicio que anuncia `<nome>.local` en la red (mDNS; LaunchAgent en
348
+ macOS, systemd en Linux). Abre `https://<nome>.local` en el celular (con `:4748` si el puerto 443 estaba ocupado). La
349
+ primera vez, acepta el aviso, toca **Instala el certificado de Busybits** y confía en él (iPhone: Configuración ›
350
+ Perfil descargado › Instalar y luego Configuración › General › Información › Configuración de confianza de
351
+ certificados; Android: Seguridad › Encriptación y credenciales › Instalar un certificado › Certificado de CA),
352
+ comprobando la huella digital que mostró el setup.
353
+
354
+ - **CA restringida:** solo firma `localhost`, nombres `.local`, tu dirección propia e IP de red privada. Aunque su
355
+ clave se filtrara, el celular que confía en ella rechazaría un certificado para cualquier otro sitio. Cambiar la
356
+ dirección propia crea una CA nueva (vuelve a instalar el certificado en el celular). La clave de la CA nunca entra en
357
+ el contenedor.
358
+ - **Dirección propia** (p. ej., `meuclaude.home`): entra en el certificado, pero el celular solo la encuentra con una
359
+ entrada en el DNS del router que apunte a la IP de la computadora. `<nome>.local` funciona sin configurar nada.
360
+ - **Qué puede hacer el celular:** por defecto, aprobar y rechazar solicitudes de permiso. `HABBLAUD_REMOTE_ALLOW` en
361
+ el `.env` acepta `permissions`, `messages`, `terminal` y `spawn`, separados por comas, o `none` (solo ver). La
362
+ terminal interactiva nunca funciona desde el celular.
363
+ - **Entregas** (celular, con `terminal` permitido): el botón de la cajita en la barra superior lista lo que terminó
364
+ cada agente, con un resumen y adjuntos (capturas de pantalla, PDFs, archivos que envió) que se abren con un toque.
365
+ - **Nuevo agente** (el botón **+**): inicia una sesión de Claude Code en segundo plano en la computadora (`claude --bg`,
366
+ en la carpeta elegida), que aparece en la oficina y recibe mensajes y solicitudes de permiso a través de Busybits. En
367
+ una carpeta en la que Claude Code todavía no confía, abre ya completada la pantalla de sesión nueva de la app de
368
+ Claude, y tú presionas Enter allí. **Viene desactivado:** necesita `HABBLAUD_PTY=1` (la misma activación que la
369
+ [terminal interactiva](#terminal-interactiva-tomar-el-control-nueva-sesión-y-cerrar); en Docker, ponla en el `.env` y
370
+ deja `npm run codex:bridge` en ejecución en la computadora) y, desde el celular, también `spawn` en
371
+ `HABBLAUD_REMOTE_ALLOW`.
372
+ - **Nuevo agente en herdr:** el diálogo ofrece los proveedores instalados en la computadora (Claude Code, Gentle Shell
373
+ y Codex) y dónde abrir la sesión: en segundo plano (solo Claude Code, como arriba), en una pestaña nueva de herdr en
374
+ el workspace que elijas, o en una división a la derecha o abajo de un panel existente de herdr. La división siempre
375
+ crea un panel nuevo y nunca toca el elegido; la carpeta elegida en el diálogo manda sobre la del panel. Necesita
376
+ herdr abierto en la computadora, Habblaud fuera de Docker y la sesión `default` de herdr; si no, esas opciones
377
+ aparecen desactivadas con una pista. **Tomar el control aquí** en una sesión abierta allí enfoca su panel de herdr.
378
+ Si herdr retoma estas sesiones tras reiniciarlo **todavía no está verificado** para ninguno de los tres
379
+ proveedores (mira [`docs/herdr-resume-verification.md`](docs/herdr-resume-verification.md)). En Gentle Shell,
380
+ herdr solo registra la sesión con su integración pi: `herdr integration install pi` es la forma de activar la
381
+ retomada, también sin verificar.
382
+ Con herdr abierto y nada elegido antes, el diálogo preselecciona una pestaña nueva de herdr, también para Claude
383
+ Code, para que las sesiones nuevas queden donde herdr puede retomarlas; recuerda el último proveedor y destino.
384
+ - **Dictado** (en Nuevo agente y en el cuadro de mensaje): necesita `whisper-cli` y `ffmpeg` (`brew install whisper-cpp
385
+ ffmpeg`) y un modelo multilingüe en `~/.local/share/whisper/` (`ggml-small.bin` acierta más que `ggml-base.bin`; los
386
+ `.en` solo entienden inglés). Sin ellos, el botón Dictar no aparece. La voz nunca sale de la computadora.
387
+ `HABBLAUD_WHISPER_BIN`, `HABBLAUD_FFMPEG_BIN`, `HABBLAUD_WHISPER_MODEL` y `HABBLAUD_DICTATION_LANGS` (por defecto
388
+ `pt,en`) lo ajustan.
389
+ - **Fuera de casa (Tailscale):** con Tailscale en la computadora y en el celular, `tailscale serve --bg --https=443
390
+ https+insecure://127.0.0.1:443` publica el puerto remoto (con inicio de sesión) solo para tus dispositivos, con un
391
+ certificado válido en `https://<computador>.<tailnet>.ts.net`; agrega ese nombre a `HABBLAUD_ALLOWED_HOSTS`. Apunta
392
+ siempre al puerto remoto, nunca al 4747 (que no pide iniciar sesión).
393
+ - **Sesión:** 30 días; cambiar la contraseña (ejecutar el setup de nuevo) las cierra todas, y **Configuración ›
394
+ Acceso desde el celular › Salir** cierra la de ese dispositivo. Después de 5 contraseñas incorrectas seguidas, cada nuevo intento espera de
395
+ 1 s a 5 min.
396
+ - **¿Cambió la IP?** `docker:up` vuelve a emitir el certificado del servidor cuando falta la IP nueva o cuando faltan
397
+ 30 días para que venza, con la misma CA (el celular sigue confiando en ella); el servidor cambia el certificado sin
398
+ reiniciarse.
399
+ - **Desactivar:** `npm run remote:setup -- --off` y `npm run docker:up`.
400
+
401
+ Sin HTTPS, el puerto remoto no se inicia; `HABBLAUD_REMOTE_INSECURE_HTTP=1` fuerza HTTP plano (contraseña y cookie a
402
+ la vista en la red). En modo Node: `HABBLAUD_REMOTE_PORT` y `HABBLAUD_REMOTE_HOST` (por defecto `0.0.0.0:4748`) y
403
+ `HABBLAUD_REMOTE_TLS_DIR` (por defecto `~/.habblaud/remote-tls/server`).
404
+
405
+ ### Actualizar
406
+
407
+ La versión en uso aparece en la barra superior, junto a "Conectado", y en **Ajustes › Acerca de**. En una instalación
408
+ empaquetada, Busybits consulta npm cada 6 horas por defecto (clon y Docker: desactivado; `HABBLAUD_UPDATE_CHECK=1` o `0`
409
+ lo cambia). Cuando hay una versión nueva, el sello verde **Nueva versión** aparece en lugar del número. **Acerca de**
410
+ tiene el enlace a lo que cambió (también en [`CHANGELOG.md`](CHANGELOG.md)), el botón **Comprobar ahora** y, en una
411
+ instalación empaquetada, **Actualizar ahora**, que ejecuta `busybits update` fuera del servicio. Desde una terminal:
412
+
413
+ ```bash
414
+ busybits update # a la última versión
415
+ busybits update --check # solo muestra la versión actual y la última
416
+ busybits update --to 1.2.0 # a una versión concreta
417
+ busybits update --global # actualiza también el comando busybits global
418
+ busybits update --rollback # vuelve a la versión anterior
419
+ ```
420
+
421
+ - Se niega a empezar mientras otra actualización está en curso (archivo de bloqueo `~/.busybits/update.lock`; si no hay
422
+ ninguna de verdad, bórralo).
423
+ - Si la versión nueva falla en su setup o no responde a `/api/health` en 30 s, vuelve a la anterior (la comprobación de `/api/health` y su reversión solo ocurren si hay un servicio en segundo plano instalado; un fallo del setup siempre revierte).
424
+ - Interrumpirlo con Ctrl-C durante la espera de salud normalmente deja activa la versión **nueva**: ejecuta
425
+ `busybits update --rollback` para volver.
426
+ - Windows: `busybits update` no está disponible; ver la sección de instalación.
427
+
428
+ **Desde un clon** (o Docker):
429
+
430
+ ```bash
431
+ git pull
432
+ npm install
433
+ npm run docker:up # ou: npm run build && npm start (e depois npm run mod:install)
434
+ ```
435
+
436
+ > Si `git pull` se detiene con "Your local changes to the following files would be overwritten by merge:
437
+ > package-lock.json", ejecuta `git checkout -- package-lock.json` y repite: hasta la 0.4.0, `npm install` modificaba ese
438
+ > archivo.
439
+
440
+ `docker:up` también actualiza el mod en las cuentas donde ya está instalado (nunca lo instala por su cuenta) y avisa:
441
+ "Mod actualizado a 0.3.0 en Cuenta D; sesiones abiertas: /reload-plugins". En modo Node, ejecuta `npm run mod:install`
442
+ después de actualizar. Para que Busybits consulte npm, usa `HABBLAUD_UPDATE_CHECK=1` (en el `.env`, para Docker).
443
+
444
+ #### Si vienes de CodeTown
445
+
446
+ Busybits se llamaba **CodeTown** hasta la 0.3.2. Después del `git pull`, ejecuta una vez:
447
+
448
+ ```bash
449
+ npm install
450
+ npm run mod:install # troca o marketplace e os plugins codetown pelos habblaud, em cada conta
451
+ npm run docker:up # tira o container codetown e copia os dados do volume antigo para o novo
452
+ ```
453
+
454
+ - **Mod:** hasta que ejecutes `mod:install`, el Claude Code de las cuentas se queja del marketplace `codetown` (las
455
+ carpetas `mod/codetown*` cambiaron de nombre). `docker:up` avisa, pero no hace el cambio por su cuenta.
456
+ - **Docker:** el volumen antiguo (`codetown_codetown-data`) queda intacto. Después de comprobar que los nombres de los
457
+ personajes se conservaron, bórralo con `docker volume rm codetown_codetown-data`, y la imagen antigua con
458
+ `docker image rm codetown:local`.
459
+ - **Carpeta local:** `~/.codetown` pasa a ser `~/.habblaud` automáticamente (en el servidor, en `docker:up` y en
460
+ `mod:install`).
461
+ - **Navegador:** las preferencias y las monedas pasan a las claves nuevas la primera vez que se abre la página.
462
+ - **Variables:** las `CODETOWN_*` ya no funcionan; renómbralas a `HABBLAUD_*` en el `.env` (p. ej., `HABBLAUD_BIND`). El
463
+ servidor y `docker:up` avisan cuando encuentran una antigua.
464
+ - **Repositorio:** ahora es `github.com/marmottajr/habblaud` (GitHub redirige la dirección antigua). Para ajustar el
465
+ clon: `git remote set-url origin https://github.com/marmottajr/habblaud.git`. La carpeta local puede seguir con el
466
+ nombre antiguo.
467
+ - Las copias de seguridad del `settings.json` hechas antes del cambio conservan el nombre
468
+ `settings.json.codetown-backup-<data>`.
469
+
470
+ ### Desinstalar
471
+
472
+ ```bash
473
+ busybits uninstall --dry-run # muestra lo que se quitaría
474
+ busybits uninstall # quita el servicio, la extensión de Pi, los hooks de Codex y el mod
475
+ busybits uninstall --purge # borra también los datos de Busybits
476
+ npm rm -g busybits # solo si lo instalaste globalmente
477
+ ```
478
+
479
+ **Desde un clon** (o Docker):
480
+
481
+ ```bash
482
+ npm run mod:uninstall # tira o mod, os plugins de permissões e de mensagens e o marketplace
483
+ npm run codex:uninstall # tira os hooks do Busybits do Codex (os outros ficam)
484
+ npm run docker:down # para o container
485
+ docker volume rm habblaud_habblaud-data # apaga os dados do container (nomes, salas, linha do tempo e estatísticas)
486
+ docker image rm habblaud:local # apaga a imagem
487
+ rm -rf ~/.habblaud # apaga os dados locais (uso capturado, nomes, salas, linha do tempo e estatísticas)
488
+ ```
489
+
490
+ Después solo tienes que borrar la carpeta del proyecto; ejecuta `mod:uninstall` **antes**, porque si no, el Claude
491
+ Code de las cuentas empieza a quejarse del marketplace que desapareció. Si usaste el método antiguo, ejecuta también
492
+ `npm run usage:uninstall` (restaura el statusline original) y `npm run hooks:uninstall` (quita el hook de permisos);
493
+ sin ellos, el statusline de las cuentas empieza a dar error (y el hook, a fallar en silencio). `mod:install`, que quita
494
+ el tap y el hook antiguos, y los instaladores y desinstaladores antiguos dejan copias
495
+ `settings.json.habblaud-backup-<data>` en la carpeta de cada cuenta (p. ej., `~/.claude/`); bórralas si ya no las
496
+ necesitas.
497
+
498
+ ## Cómo usar
499
+
500
+ ### Qué está haciendo cada personaje
501
+
502
+ | Estado | Lo que ves |
503
+ | --- | --- |
504
+ | **Trabajando** | En su escritorio, tecleando. El monitor y un globo muestran la actividad: 📖 leyendo, ✏️ editando, 💻 terminal, 🧪 pruebas, 🌐 buscando… |
505
+ | **Te necesita** | Corre a su escritorio y levanta la mano, con una alerta parpadeando: está esperando un permiso o una respuesta en la terminal. |
506
+ | **Esperando el shell** | Terminó su turno pero dejó un comando en ejecución (pruebas, build, deploy…), así que se queda en su escritorio con un reloj de arena girando sobre la cabeza y la terminal mostrando el progreso: come palomitas mirando, a los 3 min se cruza de brazos y da vueltas en la silla, a los 10 min junta telarañas y a los 25 min se queda dormido; cuando el comando termina, se levanta y lo celebra con confeti (o le cae una nube de lluvia, si falló). Pasados 40 s, si hay compañeros sin nada que hacer, puede salir a una ronda, con el reloj de arena en la cabeza. |
507
+ | **Ocioso** | Terminó su turno y pasea: café en la cocina, bebedero, baño, sofá del salón, celular en el puf, espejo. Con compañeros sin nada que hacer, se une a una ronda: TV, videojuegos, ping-pong, charla en la cocina, piedra, papel o tijera (consulta [Vida social](#vida-social)). Tras 10 min sin actividad, se queda dormido, pero un compañero puede despertarlo para una ronda. |
508
+ | **Subagente completado** | Va hasta el agente que lo llamó, le entrega el resultado y sale por el ascensor. |
509
+ | **Sesión cerrada** | Se va; si era el último de la sala, apaga la luz antes de salir. |
510
+
511
+ Cada personaje tiene un **nombre brasileño único** (Marina, Henrique, Luan…) que se mantiene mientras exista la
512
+ sesión, y un **chip de color con la letra de la cuenta** (C, D…).
513
+
514
+ ### Interfaz
515
+
516
+ - **Arriba:** contadores (salas, agentes, trabajando, subagentes, shells en ejecución, te necesitan) y una tarjeta de
517
+ **uso por cuenta**. El de shells solo aparece mientras algún comando está en ejecución; haz clic en él para ir hasta
518
+ quien espera. Debajo del logo están la conexión y la versión en uso, que se convierte en el sello **Nueva versión**
519
+ cuando sale una versión nueva (consulta [Actualizar](#actualizar)).
520
+ - **Barra lateral:** búsqueda, filtro por cuenta y la lista de salas con sus agentes y subagentes.
521
+ - **Panel de detalles:** haz clic en un personaje (en el edificio o en la lista) para ver actividad, tareas,
522
+ subagentes, línea de tiempo y estadísticas (herramientas, tokens, costo, líneas modificadas, modelo, branch).
523
+ - **Feed:** las últimas actividades de toda la oficina.
524
+ - **Configuración (⚙):** nombres, globos, cuánto pasean los ociosos, ciclo día/noche, sonidos, notificaciones del
525
+ navegador, límite de FPS (60/30/15 FPS) y pausar cuando la pestaña está oculta, modo demostración y **Acerca de** (versión en uso y versión nueva). **Ayuda (?):** leyenda completa y
526
+ atajos.
527
+ - **Panel de Rendimiento:** el icono de medidor en la barra superior muestra el uso de recursos en tiempo real por máquina (central y satélites: CPU, memoria RSS/heap, event loop p99, tiempo de actividad, contadores de trabajo y sparklines de 10 minutos) y en el navegador (FPS, tiempo de cuadro p50/p95 como indicador de GPU, tareas largas, heap JS, nodos del DOM y límite de FPS). El sondeo solo está activo mientras el panel permanece abierto y visible.
528
+ - **Mi día (📊):** adónde se fue el tiempo del día (consulta [Mi día](#mi-día)). **Timelapse** e **Historial** (los
529
+ relojes de la barra superior): consulta [Timelapse del día](#timelapse-del-día) y [Terminal](#terminal).
530
+
531
+ **Cámara:** arrastra para moverte, usa la rueda para hacer zoom y haz doble clic en un personaje para seguirlo.
532
+
533
+ **Atajos:** `/` buscar · `F` seguir al seleccionado · `T` terminal · `L` timelapse · `M` mi día · `P` próxima solicitud
534
+ (permiso o pregunta) · `O` o `0` vista general · `Esc` limpiar selección · `[` barra lateral · `]` feed · flechas/`WASD`
535
+ mover · `+` `-` zoom · `?` ayuda.
536
+
537
+ ### Temas de la oficina
538
+
539
+ En **Configuración → Apariencia → Tema de la oficina**, elige:
540
+
541
+ - **Automático** (por defecto): sigue el calendario, en la hora local. Halloween del 1 al 31 de octubre, Navidad del 1
542
+ de noviembre al 26 de diciembre y, el resto del año, el aspecto original.
543
+ - **Ninguno**: siempre el aspecto original.
544
+ - **Navidad**: guirnaldas, luces cálidas, árboles con regalos, alfombras navideñas, nieve en las ventanas y gorros en
545
+ los personajes.
546
+ - **Halloween**: calabazas, fantasmas decorativos, telarañas, murciélagos, luces moradas, alfombras temáticas y
547
+ accesorios de disfraz.
548
+
549
+ El cambio es inmediato y la elección queda guardada en este navegador. Los temas conservan los caminos,
550
+ las actividades y las animaciones de los agentes. El ciclo día/noche sigue siendo una opción independiente.
551
+
552
+ <table>
553
+ <tr>
554
+ <td width="50%"><img src="docs/screenshots/seasonal-christmas.png" alt="Oficina con el tema Navidad: árboles con regalos en las esquinas de las salas, guirnaldas y luces en las paredes, alfombras rojas y personajes con gorro" /></td>
555
+ <td width="50%"><img src="docs/screenshots/seasonal-halloween.png" alt="Oficina con el tema Halloween: calabazas y fantasmas en lugar de las plantas, telarañas y murciélagos en las paredes, alfombras moradas y personajes disfrazados" /></td>
556
+ </tr>
557
+ </table>
558
+
559
+ ### Idiomas
560
+
561
+ La interfaz está en **portugués, inglés, español y francés**. Sigue el idioma del navegador; en
562
+ **Configuración › Idioma** puedes fijar uno (la elección queda guardada en este navegador). Los textos que arma el
563
+ servidor (actividades, avisos, terminal, logs y los scripts de instalación) siguen `HABBLAUD_LANG` y, si no está
564
+ definida, el idioma del sistema, salvo el inglés: muchas máquinas y todos los contenedores vienen en inglés por
565
+ defecto, incluso para quien usa otro idioma. Para tener el servidor en inglés, define `HABBLAUD_LANG=en` (en Docker,
566
+ en el `.env`). Un texto sin traducción aparece en portugués.
567
+
568
+ ### Día, noche y sonidos
569
+
570
+ La oficina sigue la **hora local**: de madrugada y de noche el césped y la calle se ponen azulados y oscuros, los
571
+ faroles, las lámparas, las máquinas y los monitores encendidos proyectan halos de luz, las salas con gente quedan
572
+ iluminadas (la luz que se apaga cuando la sala se vacía sigue funcionando), los autos pasan con los faros encendidos y
573
+ aparecen luciérnagas en el jardín. Al amanecer (~5–7 h) y al atardecer (~17–19 h) todo toma un tono cálido, y durante
574
+ el día el sol entra por las ventanas y dibuja franjas de luz en el piso: cortas al mediodía, largas y anaranjadas al
575
+ final de la tarde. En **Configuración › Ciclo día/noche** puedes elegir automático, siempre de día o siempre de noche;
576
+ para probar un horario, usa `?hora=21:30` en la URL.
577
+
578
+ Los **sonidos** vienen desactivados. Al activarlos en **Configuración › Sonidos**, se sintetizan en el propio
579
+ navegador (sin archivos de audio) y suenan bajito: el teclado de quien trabaja en las salas a la vista, el "ding" del
580
+ ascensor cuando alguien llega o se va, la campana cuando alguien te necesita, el chasquido de tarea completada y el
581
+ ping-pong y el arcade de las rondas. Hay un volumen general y cada categoría se activa y desactiva por separado. Con la
582
+ pestaña oculta, solo suena la campana.
583
+
584
+ ### Terminal
585
+
586
+ Haz clic en un agente y usa **Abrir terminal** para ver la conversación de la sesión tal como la muestra Claude Code:
587
+ los prompts, las respuestas, cada herramienta llamada (con el comando o el diff) y el resultado, actualizados en vivo.
588
+ Funciona para agentes principales y subagentes; en el modo demostración, la conversación es ficticia.
589
+
590
+ En el pie, para agentes principales, puedes **escribir**: `Enter` envía y `Shift+Enter` hace un salto de línea. El
591
+ texto entra en la sesión como si lo hubieras escrito en su terminal (consulta [Enviar mensajes](#enviar-mensajes)); si
592
+ el agente está ocupado, entra cuando termine lo que está haciendo. Los subagentes y las sesiones del historial siguen
593
+ siendo de solo lectura.
594
+
595
+ - **Búsqueda:** con la terminal enfocada, `Ctrl+F` (`⌘F` en Mac) o la lupa del encabezado abre la búsqueda en la
596
+ conversación, sin distinguir mayúsculas ni acentos. El contador muestra la posición ("3/17"); `Enter` y `Shift+Enter`
597
+ van al siguiente y al anterior, y abren los bloques contraídos ("… +N líneas") donde esté el término. La búsqueda
598
+ sigue activa mientras llegan mensajes nuevos. `Esc` cierra la búsqueda; el siguiente cierra la terminal.
599
+ - **Filtro:** **Todo**, **Solo prompts** (tus prompts y las respuestas finales del agente, sin los pasos intermedios)
600
+ o **Sin herramientas**.
601
+ - **Copiar:** pasa el cursor (o el foco) sobre un prompt, una respuesta, un comando o un resultado para copiarlo.
602
+ - **Historial:** el reloj de la barra superior lista las sesiones de los últimos 7 días de todas las cuentas (hasta
603
+ 150), agrupadas por día, con búsqueda por título, proyecto o cuenta. Una sesión cerrada se abre en la terminal con el
604
+ proyecto, el título y la fecha en el encabezado y "Sesión cerrada a las …" en el pie; una sesión todavía abierta abre
605
+ la terminal en vivo del agente.
606
+
607
+ Como la terminal (y el historial) muestra la conversación completa, solo existe cuando Busybits es accesible
608
+ **únicamente desde la propia computadora** (lo predeterminado) y solo se abre por `http://localhost` o
609
+ `http://127.0.0.1`. Con el puerto abierto a la red (`HABBLAUD_BIND=0.0.0.0` o `HABBLAUD_HOST=0.0.0.0`), queda
610
+ desactivada. Detalles en [Privacidad y seguridad](#privacidad-y-seguridad).
611
+
612
+ ### Terminal interactiva (tomar el control, nueva sesión y cerrar)
613
+
614
+ Con `HABBLAUD_PTY=1` y ejecutando con `npm start` (fuera de Docker), la ventana de terminal de cada agente principal es
615
+ interactiva: el botón **Abrir terminal** del panel, el atajo junto a cada agente en la barra lateral o la tecla `T`
616
+ abren la misma ventana, con pestañas para los demás agentes del mismo proyecto.
617
+
618
+ - Sesión abierta aquí: es el Claude Code de verdad (escribir, responder; Esc interrumpe al agente, como en la
619
+ terminal).
620
+ - Sesión abierta en otra terminal: **Tomar el control aquí** (en la parte superior de la ventana) cierra la sesión allá
621
+ y continúa la **misma conversación** aquí (`claude --resume <sessão>`, en la misma carpeta y cuenta). El personaje
622
+ conserva su nombre. En Windows, la terminal de donde salió la sesión vuelve a la normalidad (Busybits desactiva los
623
+ modos de mouse/teclado que Claude había activado).
624
+ - **Cerrar** termina la sesión, esté aquí o en otra terminal (la conversación queda guardada).
625
+ - **Nueva sesión** (en el panel de la sala) abre un Claude Code nuevo en la carpeta del proyecto.
626
+
627
+ Tomar el control y cerrar piden un segundo clic; cerrar la ventana no termina la sesión. La ventana (y el panel del
628
+ agente) se puede arrastrar por la barra y redimensionar por la esquina; doble clic en la barra la devuelve a su lugar.
629
+ **Viene desactivada:** actívala con `HABBLAUD_PTY=1` (lee antes el aviso en [Privacidad y seguridad](#privacidad-y-seguridad)).
630
+ Usa `node-pty`, `@xterm/headless` (dependencias opcionales) y el `claude` del PATH (`HABBLAUD_CLAUDE_BIN` para
631
+ otro); solo acepta solicitudes de la propia computadora. Al iniciar, Busybits abre una terminal de prueba: si `node-pty`
632
+ o `claude` no funcionan, la función queda desactivada y el log dice el motivo. **Reiniciar Busybits cierra las sesiones
633
+ que abrió.**
634
+ La terminal en vivo sigue disponible en el historial de sesiones, para los subagentes y cuando la interactiva está
635
+ desactivada.
636
+
637
+ ### Timelapse del día
638
+
639
+ El botón **Timelapse** (reloj con la flecha hacia atrás, o la tecla `L`) reproduce el día a alta velocidad: salas que
640
+ se encienden y se apagan, agentes que llegan, trabajan, te esperan, van a las rondas, subagentes que entran y salen.
641
+ La barra de reproducción tiene el día, play/pausa, la velocidad (60×, 180× o 600×: un día de 10 h en 10, 3⅓ o 1 min),
642
+ la línea de tiempo arrastrable con el gráfico de quién estaba presente y trabajando, las marcas de los picos (haz clic
643
+ para saltar ahí) y **Ver en vivo**. Mientras tanto, la oficina toma un ligero tono sepia, con el sello **REPLAY 14:32**,
644
+ y el feed sigue mostrando lo que pasa ahora.
645
+
646
+ El servidor graba la línea de tiempo **a partir del momento en que está encendido** (no se puede reconstruir el
647
+ pasado): resúmenes de lo que muestra la oficina, sin conversaciones, en `~/.habblaud/timeline/` (en Docker, en el
648
+ volumen de datos), con un límite de tamaño por día y los últimos **7 días** guardados. Para no grabar:
649
+ `HABBLAUD_TIMELINE=0`. Detalles en [`server/README.md`](server/README.md#linha-do-tempo-timelapse).
650
+
651
+ Los personajes caminan más rápido en el replay, pero a velocidades altas quien pasa poco tiempo en la oficina casi no
652
+ llega a su escritorio; saltar a otro punto los muestra a todos ya en su lugar.
653
+ ### Responder desde la oficina
654
+
655
+ Con el plugin de permisos instalado (`npm run mod:install`, que lo instala junto con el mod; en Claude Code anterior
656
+ a 2.1.287, `npm run hooks:install`), cuando un agente pide permiso (ejecutar un comando, editar un archivo, abrir una
657
+ página), la solicitud aparece en la oficina: el personaje levanta la mano, aparece en pantalla un aviso con
658
+ **Responder** y, en los detalles del agente, la tarjeta **Pide permiso** muestra el comando (o el diff de la edición)
659
+ con los botones:
660
+
661
+ - **Aprobar** y, cuando Claude Code lo sugiere, **Aprobar y no volver a preguntar** (la misma regla que ofrecería la
662
+ terminal, por ejemplo `Bash(npm test:*)` en este proyecto);
663
+ - **Rechazar**, con un motivo opcional, que le llega al agente, y la opción de interrumpirlo;
664
+ - **Responder en la terminal**: Busybits deja la solicitud de lado.
665
+
666
+ El diálogo sigue apareciendo en la terminal al mismo tiempo, y vale lo que respondas primero: si respondes en la
667
+ terminal, la solicitud desaparece de la oficina sola. El contador **te necesitan** (y la tecla `P`) lleva a cada
668
+ solicitud.
669
+
670
+ **Las preguntas del agente** (`AskUserQuestion`) también: la tarjeta de preguntas muestra cada pregunta con las
671
+ opciones y sus descripciones, como las mostraría la terminal. Elige una opción (o varias, cuando la pregunta lo
672
+ permite) o escribe la tuya en **Otro**, y usa **Responder**; **Rechazar…** le dice al agente que no quieres responder,
673
+ y **Responder en la terminal** deja la pregunta allá. La respuesta le llega al agente como si la hubieras elegido en la
674
+ terminal.
675
+
676
+ - La solicitud pasa por un hook `PermissionRequest` de Claude Code (el del plugin o el del método antiguo), que solo
677
+ la desvía cuando hay **alguna página de Busybits abierta** en esta computadora; con Busybits detenido o sin ninguna
678
+ página abierta, sale de inmediato y la terminal sigue como siempre.
679
+ - Sin respuesta desde la oficina en 5 minutos (hasta 24 h con `HABBLAUD_PERMISSION_TIMEOUT=86400` en el `env` del
680
+ `settings.json`), la solicitud vuelve a valer solo en la terminal (las opciones del plugin están en
681
+ [`mod/README.md`](mod/README.md); en el método antiguo, `npm run hooks:install -- --timeout 120` cambia el tiempo y
682
+ `--port`, el puerto). En los **subagentes en segundo plano**, Claude Code solo muestra el diálogo en la terminal
683
+ después de que el hook termina: responde desde la oficina o usa **Responder en la terminal**. Con una espera de más
684
+ de 5 minutos, si pasan 5 minutos sin ninguna página abierta que pueda responder (y no hay ningún
685
+ [celular con inicio de sesión](#celular-con-inicio-de-sesión-y-https-aprobar-solicitudes) configurado para
686
+ responder), la solicitud vuelve a la terminal.
687
+ - Funciona con el mismo bloqueo que la terminal: solo con Busybits accesible únicamente desde la propia
688
+ computadora y abierto por `http://localhost`. Compruébalo con `npm run mod:status` (o `npm run hooks:status`, en el
689
+ método antiguo).
690
+ También funciona desde el [celular con inicio de sesión](#celular-con-inicio-de-sesión-y-https-aprobar-solicitudes) (allí, es lo predeterminado).
691
+ - En el modo demostración, los agentes ficticios también piden permiso y hacen preguntas (de mentira), para que lo
692
+ pruebes.
693
+
694
+ ### Enviar mensajes
695
+
696
+ Con el plugin de mensajes instalado (`npm run mod:install`, que lo instala junto con el mod; requiere Claude Code
697
+ 2.1.287 o más reciente), los detalles de cada agente principal incluyen la sección **Enviar mensaje**, y el pie de la
698
+ [terminal](#terminal) se convierte en un cuadro de texto. Escribe y presiona `Enter` (`Shift+Enter` hace un salto de
699
+ línea): el texto entra en la sesión **como si lo hubieras escrito en su terminal**. Puedes responder cuando el agente
700
+ termina su turno y espera la siguiente solicitud, darle una instrucción nueva o corregir el rumbo, sin buscar la
701
+ ventana correcta.
702
+
703
+ - El cuadro muestra el estado: **en cola** (la sesión busca los mensajes cada 2 segundos), **entregado** o **no se
704
+ entregó**, con el motivo. Con el agente ocupado, el mensaje espera y entra cuando termine su turno, como un prompt
705
+ escrito con el agente trabajando.
706
+ - El plugin se ejecuta dentro de cada sesión y solo habla con Busybits en `127.0.0.1`. Sin él (o en una sesión abierta
707
+ antes de la instalación: usa `/reload-plugins`), aparece la sugerencia de instalación en lugar del cuadro. Los
708
+ subagentes no reciben mensajes.
709
+ - Funciona con el mismo bloqueo que la terminal (solo con acceso local) y se puede desactivar con
710
+ `HABBLAUD_MENSAGENS=0`. Lee el aviso en [Privacidad y seguridad](#privacidad-y-seguridad).
711
+ Desde el [celular con inicio de sesión](#celular-con-inicio-de-sesión-y-https-aprobar-solicitudes), solo con `messages` en `HABBLAUD_REMOTE_ALLOW`.
712
+ - En el modo demostración, los agentes ficticios también reciben mensajes (de mentira).
713
+
714
+ ### Editar el personaje
715
+
716
+ Cada sesión llega con un nombre y una apariencia sorteados. Para fijar el personaje de un proyecto, abre los detalles
717
+ del agente principal y haz clic en el lápiz junto al nombre (**Editar personaje**). En el editor:
718
+
719
+ - **Nombre:** hasta 24 caracteres. No puede repetir el de alguien que está en la oficina ni el elegido para otro
720
+ proyecto.
721
+ - **Sortear:** trae otra apariencia.
722
+ - **Piezas:** piel, cabello, barba, ojos, parte de arriba, parte de abajo, zapatos y accesorio, con la vista previa al
723
+ lado.
724
+ - **Guardar:** vale para el proyecto (la sala). La próxima sesión que se abra en él llega con ese personaje. Con dos
725
+ sesiones al mismo tiempo en la misma sala, la segunda recibe un personaje sorteado.
726
+ - **Volver al sorteo:** deshace la elección.
727
+
728
+ La elección queda en `~/.habblaud/names.json` y se borra después de 60 días sin uso del proyecto. El editor tiene el
729
+ mismo bloqueo que la terminal: el lápiz solo aparece con la terminal activada (sin `HABBLAUD_TERMINAL=0`) y el acceso
730
+ local, es decir, con Busybits accesible únicamente desde la propia computadora y abierto por `http://localhost`.
731
+
732
+ ### Codex
733
+
734
+ Las sesiones de Codex (CLI o app) aparecen como las de Claude Code: personaje, sala del proyecto, actividad, tareas,
735
+ subagentes, terminal e historial, uso de 5 horas y semanal y **Mi día** (solo tokens: Codex no informa el costo). El
736
+ chip de la cuenta de Codex es hueco y lleva el sello **CODEX**.
737
+
738
+ - **Sin instalar nada**, Busybits lee los archivos que el propio Codex guarda (las conversaciones en
739
+ `~/.codex/sessions` y los bloqueos de las sesiones abiertas en `~/.codex/thread-writer-locks`). Pero Codex guarda cada
740
+ paso **después** de que termina y nunca guarda "esperándote": sin los hooks, la oficina muestra Codex con retraso y no
741
+ avisa cuando te necesita.
742
+ - **Con los hooks** (`npm run codex:install` y aprobarlos en `/hooks`), Codex le avisa a Busybits en cada paso: la
743
+ sesión aparece al instante, la actividad es la actual y una solicitud de aprobación hace que el personaje levante la
744
+ mano.
745
+ - **Aprobar desde la oficina:** con alguna página de Busybits abierta, la solicitud de aprobación de Codex espera tu
746
+ respuesta en la tarjeta **Pide permiso** hasta **25 segundos** (`npm run codex:install -- --espera <s>`, de 5 a 120):
747
+ **Aprobar** o **Rechazar** (con el motivo). A diferencia de Claude Code, Codex solo muestra la aprobación en la
748
+ terminal **después** de que la oficina responde o se acaba el plazo; mientras tanto, la terminal muestra "Esperando
749
+ respuesta en Busybits…". No hay "permitir siempre" ni "interrumpir", y Codex no deja responder sus preguntas desde
750
+ fuera.
751
+ - **Enviar mensajes:** el cuadro **Enviar mensaje** también funciona con Codex, a través de `codex queue`: el mensaje
752
+ entra en la cola de la sesión y Codex lo toma cuando termina lo que está haciendo (hasta unos 10 segundos después). En
753
+ modo Node, el propio Busybits ejecuta el comando; **en Docker**, deja `npm run codex:bridge` en ejecución en el Mac
754
+ (el contenedor no ve tu Codex).
755
+ - **Uso de 5 horas y semanal:** viene de los propios archivos de Codex y solo se renueva mientras alguna sesión está en
756
+ ejecución; la tarjeta muestra la antigüedad de los números y "sin cuota" cuando el workspace se quedó sin créditos.
757
+ - **Cuándo entra la sesión:** con el primer mensaje (que es cuando Codex guarda la carpeta del proyecto); una CLI
758
+ abierta y todavía sin conversación no aparece.
759
+ - **Cuándo sale la sesión de la oficina:** la CLI de Codex ejecuta las sesiones en un servidor en segundo plano, que
760
+ las mantiene cargadas hasta un minuto después de quedar inactivas y sin que nadie las mire; por eso el personaje
761
+ puede tardar un poco en irse después de que cierras la terminal.
762
+ - Las conversaciones en la nube de ChatGPT (sin archivo en la computadora) no aparecen. `HABBLAUD_CODEX=0` desactiva
763
+ Codex.
764
+
765
+ ### GitHub en la oficina
766
+
767
+ Lo que los agentes hacen en GitHub anima la sala del proyecto, sin token y sin acceder a internet: Busybits lee en
768
+ los transcripts las llamadas (`gh pr create`, `gh pr merge`, `git push`, `gh run watch`, `gh pr checks`, `gh run view`,
769
+ `gh release create` y las herramientas del MCP de GitHub) y sus resultados.
770
+
771
+ | Evento | Qué pasa |
772
+ | --- | --- |
773
+ | 🎉 **PR abierto o fusionado, release publicada** | Cae confeti en la sala, todos celebran dando saltitos y una pancarta dice el motivo ("¡PR #12 fusionado!") durante ~12 s. |
774
+ | 🚨 **CI en rojo** | Luces giratorias parpadeando en las esquinas de la sala, suelo rojizo y un globo "!" sobre quien vio el fallo, hasta que haya un CI en verde en la sala (que se vuelve fiesta) o durante 10 min. |
775
+ | 🚀 **Push** | Solo el aviso y el feed. |
776
+
777
+ <table>
778
+ <tr>
779
+ <td width="50%"><img src="docs/screenshots/github-party.png" alt="Sala app-mobile de fiesta: confeti cayendo, la pancarta dorada '¡PR #12 fusionado!' y Jéssica de pie con los brazos en alto y una estrella sobre la cabeza" /></td>
780
+ <td width="50%"><img src="docs/screenshots/github-alarm.png" alt="Sala data-pipeline en alarma: suelo rojizo, pancarta roja 'CI falló (feat/checkout)', luces giratorias en las esquinas de arriba y un globo '!' rojo junto a Ícaro" /></td>
781
+ </tr>
782
+ </table>
783
+
784
+ Cada evento también genera un aviso ("🎉 Danilo abrió el PR #12 en habblaud", "🚨 CI falló en habblaud (feat/x)") y
785
+ entra en el feed. Solo lo que pasa en vivo anima la sala: lo que ya estaba en los transcripts cuando se abrió Busybits
786
+ va solo al historial. Con "reducir movimiento" activado en el sistema, nada parpadea ni gira. En el modo demostración,
787
+ aparecen de vez en cuando PRs, merges y CIs ficticios.
788
+ ### Mi día
789
+
790
+ El botón **Mi día** (o la tecla `M`) muestra adónde se fue el día: cuánto tiempo pasaron los agentes trabajando y,
791
+ destacado, cuánto tiempo pasaron **esperándote** (permiso, pregunta o elección), con la espera más larga, quién
792
+ esperó, dónde y cuándo. Al lado, sesiones, subagentes, solicitudes, tokens y costo (cuando Claude Code registra el
793
+ costo en el transcript), y gráficos por hora, por proyecto (del que más te esperó al que menos) y por cuenta, además
794
+ del ranking de las esperas más largas. Elige el día en el selector (Busybits guarda los últimos 30); abierto en el día
795
+ de hoy, el panel se actualiza cada 30 s. Cada gráfico tiene una versión en tabla, y la leyenda activa y desactiva cada
796
+ estado.
797
+
798
+ El tiempo es **tiempo de agente**: dos agentes trabajando durante una hora cuentan dos horas. Busybits solo cuenta lo
799
+ que pasa mientras está en ejecución, y el día sigue la zona horaria de tu navegador. Con el modo demostración
800
+ activado, el panel muestra números ficticios (con el sello "demostración") y permite alternar a los datos reales; los
801
+ agentes de la demo nunca entran en las estadísticas de verdad.
802
+
803
+ ### Modo demostración
804
+
805
+ ¿Quieres ver la oficina llena sin tener sesiones abiertas?
806
+
807
+ - Agrega **`?mock=1`** a la URL (p. ej., http://localhost:4747/?mock=1) para simular todo en el navegador, sin tus
808
+ sesiones reales. Parámetros: `&speed=3` acelera el tiempo y `&sessions=6` cambia el número de sesiones simuladas.
809
+ - O actívalo desde la interfaz, con **Ver demostración** (cuando la oficina está vacía) o **Configuración › Modo
810
+ demostración**, que pone agentes ficticios junto a los reales. Con `npm run demo` (o `HABBLAUD_DEMO=1` en el
811
+ `.env` de Docker), este modo ya empieza activado.
812
+
813
+ ## Cuentas y uso (5 horas y semanal)
814
+
815
+ > Las cuentas de **Codex** entran solas (cada carpeta `~/.codex*` o `CODEX_HOME` es una cuenta; la letra sale de un
816
+ > `alias x='CODEX_HOME=… codex'`, si existe) y su uso viene de los archivos de Codex; consulta [Codex](#codex). El resto
817
+ > de esta sección trata de Claude Code.
818
+
819
+ Si usas más de una cuenta de Claude Code (por ejemplo, un atajo `c` con `~/.claude` y uno `d` con
820
+ `CLAUDE_CONFIG_DIR=~/.claude-conta2`), Busybits las muestra todas juntas: cada agente lleva el chip de su cuenta y la
821
+ parte superior muestra, para cada cuenta, el **porcentaje usado** de la sesión de 5 horas y de la semana y **cuándo se
822
+ reinicia cada límite**.
823
+
824
+ **Cómo se reconocen las cuentas.** Cada carpeta de configuración de Claude Code es una cuenta: `~/.claude` y cualquier
825
+ `~/.claude*` con `projects/` o `sessions/` (además de `CLAUDE_CONFIG_DIR`). Para asignarle una letra a cada una,
826
+ Busybits lee en los archivos del shell (`~/.zshrc`, `~/.bashrc`…) **solamente** las líneas `alias x='... claude ...'`:
827
+
828
+ ```bash
829
+ alias c='claude'
830
+ alias d='CLAUDE_CONFIG_DIR=~/.claude-conta2 claude'
831
+ ```
832
+
833
+ se convierte en **Cuenta C** y **Cuenta D**. Solo valen atajos de hasta 3 letras; las cuentas sin atajo reciben A, B…
834
+
835
+ **De dónde vienen los números.** El método recomendado es el mod de Busybits (`npm run mod:install`, Claude Code
836
+ 2.1.287+): dentro de cada sesión, recibe del propio Claude Code los límites del plan y guarda solo los porcentajes de 5
837
+ horas y de la semana (y cuándo se reinician) en `~/.habblaud/usage/<conta>.json`. Los números llegan después de la
838
+ siguiente respuesta de cada cuenta. Compruébalo con `npm run mod:status`. En versiones anteriores de Claude Code, el
839
+ tap de statusline (`npm run usage:install`) hace lo mismo mediante el comando de statusline, en el mismo archivo.
840
+
841
+ <details>
842
+ <summary><b>Detalles del tap y de la caché de /usage</b></summary>
843
+
844
+ - `usage:install` (método antiguo) modifica, en `<conta>/settings.json`, **solo** el campo `statusLine.command`: el
845
+ comando original (p. ej., `npx -y ccstatusline`) pasa a ejecutarse a través de `node "<pasta do Busybits>/scripts/statusline-tap.mjs" --
846
+ <comando original>` (en Windows, el comando original se ejecuta en Git Bash, como lo ejecutaría Claude Code). Antes,
847
+ una copia del archivo va a `settings.json.habblaud-backup-<data>`. Si la cuenta no tenía statusline, se crea uno que
848
+ solo captura el uso. `npm run usage:install -- --dry-run` muestra lo que cambiaría sin guardar nada.
849
+ - El tap le pasa el mismo JSON a tu statusline (la salida y el código de salida siguen siendo los suyos) y guarda
850
+ **solamente** `{accountId, configDir, fetchedAt, five_hour, seven_day}`: nada de prompts, costos ni rutas de
851
+ proyecto. Cualquier fallo en la captura se ignora: el statusline nunca se rompe por culpa de Busybits.
852
+
853
+ | Fuente | Cómo funciona |
854
+ | --- | --- |
855
+ | **Mod de Busybits** (recomendado) | En vivo, como se describe arriba. Reemplaza al tap: `mod:install` quita el tap de la cuenta. |
856
+ | Tap de statusline (Claude Code anterior a 2.1.287) | En vivo, mediante el comando de statusline, en el mismo archivo. |
857
+ | Caché de `/usage` (siempre activa) | Claude Code guarda el último resultado del comando `/usage`. En modo Node, Busybits lo vuelve a leer cada 60 s; en Docker, vale el valor leído en el último `npm run docker:up`. Solo cambia cuando alguien ejecuta `/usage`. |
858
+
859
+ Las fuentes son archivos locales: ninguna lee contraseñas ni tokens, ni hace llamadas de red. Siempre vale la fuente
860
+ con los números más recientes. Los números con más de 30 minutos aparecen como **desactualizados**; una ventana que ya
861
+ se reinició desde la recolección aparece como **—** hasta que lleguen números nuevos.
862
+
863
+ </details>
864
+
865
+ ## Configuración
866
+
867
+ Todo funciona sin configurar nada. Si necesitas ajustar algo, usa variables de entorno (en modo Node, cada
868
+ `HABBLAUD_X` también acepta el alias `BUSYBITS_X`; si están las dos, vale `HABBLAUD_X`):
869
+
870
+ | Variable | Por defecto | Para qué |
871
+ | --- | --- | --- |
872
+ | `HABBLAUD_PORT` | `4747` | Puerto HTTP (en Docker, el puerto publicado en el host). |
873
+ | `HABBLAUD_HOST` | `127.0.0.1` | Interfaz del servidor en modo Node. Fuera de `127.0.0.1`/`localhost`, la terminal (y responder y enviar mensajes desde la oficina) queda desactivada. |
874
+ | `HABBLAUD_BIND` | `127.0.0.1` | Solo Docker (en el `.env`): dónde se publica el puerto. `0.0.0.0` abre la red local (y desactiva la terminal y lo que actúa sobre las sesiones). |
875
+ | `HABBLAUD_CLAUDE_DIRS` | detección automática | Carpetas de las cuentas, separadas por comas (p. ej., `/caminho/conta1,/caminho/conta2`). |
876
+ | `HABBLAUD_DATA_DIR` | `~/.habblaud` | Dónde guarda Busybits sus propios datos (nombres de los personajes y de las salas, línea de tiempo del timelapse y estadísticas de Mi día). |
877
+ | `HABBLAUD_TIMELINE` | activada | `0` desactiva la grabación de la línea de tiempo (los días ya grabados siguen en el timelapse). En Docker siempre está activada. |
878
+ | `HABBLAUD_USAGE_DIR` | `~/.habblaud/usage` | Dónde guarda el uso el mod (o el tap de statusline). |
879
+ | `HABBLAUD_DEMO` | desactivado | `1` activa el modo demostración al iniciar. |
880
+ | `HABBLAUD_ALLOWED_HOSTS` | — | Nombres extra aceptados en la dirección (p. ej., `meu-mac.local`), además de `localhost` y las IP. |
881
+ | `HABBLAUD_TERMINAL` | activada (solo con acceso local) | `0` desactiva la terminal, responder y enviar mensajes desde la oficina y el editor de personajes. Con el puerto expuesto ya quedan desactivados, sin opción de activarlos. |
882
+ | `HABBLAUD_PTY` | desactivada | `1` activa la terminal interactiva (abrir, tomar el control y cerrar sesiones de Claude Code desde la oficina; solo con acceso local y fuera de Docker) y **Nuevo agente** (también en Docker, a través de `npm run codex:bridge`). Lee el aviso en [Privacidad y seguridad](#privacidad-y-seguridad). |
883
+ | `HABBLAUD_CLAUDE_BIN` | `claude` del PATH | El ejecutable de Claude Code que ejecutan la terminal interactiva y Nuevo agente. |
884
+ | `HABBLAUD_REMOTE_ALLOW` | `permissions` | Lo que puede hacer el [celular con inicio de sesión](#celular-con-inicio-de-sesión-y-https-aprobar-solicitudes): `permissions`, `messages`, `terminal`, `spawn` (separados por comas) o `none`. Las demás `HABBLAUD_REMOTE_*` las escribe `npm run remote:setup`. |
885
+ | `HABBLAUD_MENSAGENS` | activados (con la terminal) | `0` desactiva solo los mensajes desde la oficina (el cuadro en la terminal y en los detalles del agente). |
886
+ | `HABBLAUD_CODEX` | activado | `0` desactiva Codex en la oficina. |
887
+ | `HABBLAUD_CODEX_DIRS` | detección automática | Carpetas de Codex, separadas por comas (en lugar de `~/.codex*` y `CODEX_HOME`). |
888
+ | `HABBLAUD_CODEX_BIN` | `codex` del PATH (en Windows, `codex.exe`) | El binario de Codex que entrega los mensajes (`codex queue`), en modo Node o en `npm run codex:bridge`. |
889
+ | `HABBLAUD_UPDATE_CHECK` | empaquetada: activada; clon/Docker: desactivada | `1` activa la comprobación de versión nueva (una consulta al registro de npm cada 6 h), `0` la desactiva. |
890
+ | `HABBLAUD_LANG` | idioma del sistema (salvo inglés); si no, `pt-BR` | Idioma de los textos que arma el servidor (actividades, avisos, logs): `pt-BR`, `en`, `es` o `fr`. La interfaz sigue al navegador o la elección en Configuración › Idioma. Consulta [Idiomas](#idiomas). |
891
+ | `HABBLAUD_ACCOUNTS` | — | JSON para personalizar el nombre, la letra o el color, emparejado por el nombre de la carpeta de la cuenta. P. ej.: `[{"id":".claude-conta2","name":"Trabalho","short":"T","color":"#5cc97b"}]`. |
892
+
893
+ **En Docker**, valen `HABBLAUD_PORT`, `HABBLAUD_BIND`, `HABBLAUD_ALLOWED_HOSTS`, `HABBLAUD_DEMO`, `HABBLAUD_TERMINAL`,
894
+ `HABBLAUD_MENSAGENS`, `HABBLAUD_CODEX`, `HABBLAUD_UPDATE_CHECK`, `HABBLAUD_LANG`, `HABBLAUD_PTY`, las `HABBLAUD_WORLD*` y las
895
+ `HABBLAUD_REMOTE_*` (en el `.env` o en el entorno) y `HABBLAUD_CLAUDE_DIRS`, `HABBLAUD_CODEX_DIRS`, `HABBLAUD_USAGE_DIR` y
896
+ `HABBLAUD_ACCOUNTS` (leídas por `docker:up` en el host); las demás quedan fijas dentro del contenedor. Opciones: `npm run docker:up -- --no-build` (inicia sin reconstruir),
897
+ `npm run docker:down` (detiene) y `npm run docker:logs` (sigue los logs).
898
+
899
+ ## Habblaud World
900
+
901
+ Habblaud World es una ciudad en línea en pixel art donde cada oficina de Busybits se convierte en un edificio, encendido
902
+ en vivo mientras los agentes trabajan, y cada persona pasea con un personaje. **Viene desactivado por defecto en
903
+ Busybits**: `HABBLAUD_WORLD=1` lo activa, apuntando a `server.habblaud.com`; aun así, **nada sale de la computadora
904
+ hasta que crees la cuenta** y entres. El acceso se libera por lista de espera.
905
+
906
+ **Cómo configurarlo.** Actívalo con `HABBLAUD_WORLD=1` (en el `.env` o en el entorno); las demás variables de abajo
907
+ son opcionales: sin ellas, Busybits apunta al servidor oficial. La sección aparece en la ventana **Habblaud World** (el botón de ciudad en la barra superior) y solo funciona desde la propia computadora (nunca por el puerto
908
+ del celular); la cuenta queda solo aquí, en `~/.habblaud/world.json` (permiso 600; en Docker, en el volumen `/data`).
909
+
910
+ | Variable | Por defecto | Para qué |
911
+ | --- | --- | --- |
912
+ | `HABBLAUD_WORLD_URL` | `https://server.habblaud.com` | Dirección del servidor del mundo, solo `https://` o `wss://` (sin ruta). |
913
+ | `HABBLAUD_WORLD` | desactivado | `1` activa el World (rutas e interfaz). Sin definir o en `0`, no hay nada del World y nada sale de la computadora. |
914
+ | `HABBLAUD_WORLD_DEV` | desactivado | `1` acepta un servidor del mundo local sin TLS: `http://127.0.0.1:<puerto>` (`npm run dev` ya lo acepta) o, desde dentro de Docker, `http://host.docker.internal:<puerto>`. |
915
+
916
+ **Privacidad.** Nada de tu trabajo sale de la computadora. Del edificio salen solo el tema, un piso por sala abierta
917
+ (con un código aleatorio que cambia cada día) y, de cada agente, si es principal o subagente, la herramienta, el
918
+ estado, la apariencia, un nombre sorteado y la franja de tareas terminadas en el día. Rutas, nombres de proyectos,
919
+ títulos, comandos, mensajes, código, costo, modelo, rama y tu cuenta de Claude nunca salen. La lista completa, campo a
920
+ campo (en portugués): [docs/world/privacidade.md](docs/world/privacidade.md). **Ver lo que se envió**, en la tarjeta Tu
921
+ edificio, muestra el JSON exacto del último envío, con el tamaño en bytes y la respuesta del mundo.
922
+
923
+ **Cuenta y lista de espera.** Registro con correo, **nombre de jugador** (3 a 20 caracteres, único en el mundo: queda
924
+ reservado para ti mientras esperas en la lista y pasa a ser el nombre del personaje) y contraseña (12 caracteres o más;
925
+ las contraseñas filtradas se rechazan), código de 6 dígitos por correo y la aceptación de los Términos de Uso y la
926
+ Política de Privacidad. Toda cuenta entra en una lista de espera y el acceso se libera por lotes: el Busybits abierto lo
927
+ comprueba solo cada 30 minutos. Hasta 3 computadoras por cuenta (**Dispositivos**, con revocar).
928
+
929
+ **Personaje.** El nombre de jugador elegido en el registro (se puede cambiar después, una vez cada 30 días), el mismo
930
+ editor de apariencia de los agentes, 2 o 3 rasgos de personalidad y una frase de presentación de la lista (en el mundo
931
+ no hay texto libre aparte del nombre). Se puede crear ya en la lista de espera.
932
+
933
+ **Edificio.** Con la cuenta aprobada y el personaje creado, el edificio sube solo (por WebSocket) y acompaña la oficina
934
+ en vivo. La tarjeta **Tu edificio** muestra la conexión, los pisos, los agentes, el último envío y, cuando el mundo
935
+ rechaza un envío o detiene el edificio (versión antigua, otra computadora, cuenta suspendida o baneada), el motivo; una
936
+ cuenta suspendida o baneada recibe **Apelar por correo**. Un edificio marcado como "no verificado" (números fuera de lo
937
+ plausible, en revisión) queda fuera de clasificaciones y destacados y muestra **Impugnar por correo**. Cuando el mundo
938
+ está en mantenimiento, la tarjeta lo dice y Busybits vuelve a intentarlo solo.
939
+
940
+ **Visibilidad.** En vivo (pisos, contadores y el estado de cada personaje) o **modo discreto** (solo encendido o apagado
941
+ y el número de pisos); cerrado a visitas; ocultar el país; los **tokens** del edificio solo en franjas (hasta 100 mil, 1
942
+ millón…), nunca el número ni el costo, y se pueden desactivar; clasificación y compactaciones solo si las activas; tocar
943
+ a la puerta (**Avisarme cuando toquen a la puerta**) también solo si lo activas.
944
+
945
+ **Ciudad.** El botón **Mundo**, en la barra superior, cambia la oficina por la ciudad: se camina con flechas/WASD o
946
+ haciendo clic, la tarjeta de cada edificio muestra pisos, agentes y estado, y el minimapa queda en la esquina; en pausa o
947
+ fuera del mundo, tu edificio queda apagado, pero puedes pasear por la ciudad. En el modo demostración
948
+ (`?mock=1&world=approved&scene=city`, solo edificios y personas ficticios): [la ciudad](docs/screenshots/world-cidade.png)
949
+ y [la tarjeta de un edificio](docs/screenshots/world-cartao.png).
950
+
951
+ **Visitas.** Cerca de la puerta de un edificio, **Entrar (E)** te lleva adentro: la oficina del dueño en vivo, con salas
952
+ de nombres ficticios y los agentes en su estado de ahora, solo para mirar (sin terminal, mensajes ni permisos, y nada
953
+ del trabajo); un edificio cerrado a visitas solo se ve por fuera. En el tuyo ves "N visitantes ahora" (solo el número,
954
+ nunca quién). En el modo demostración: [la visita](docs/screenshots/world-visita.png) y
955
+ [el panel de la visita](docs/screenshots/world-visita-painel.png).
956
+
957
+ **Social.** En la ciudad, sin ningún texto libre: **L** da me gusta al edificio junto a la puerta, **G** abre la rueda
958
+ de saludos (frases listas, traducidas para quien las lee) y **K** toca a la puerta de quien lo acepta; la tarjeta de
959
+ cada persona tiene Saludar, Bloquear y Denunciar, y el minimapa lleva a un edificio por su código ("Ir a HB-XXXX") o a
960
+ cualquier edificio encendido. Dentro de un edificio, **Me gusta** y **Dejar un sello** en la recepción (uno por edificio
961
+ por día). En la plaza, el termómetro de la meta semanal de la ciudad y, cuando se alcanza, fuegos artificiales. En la
962
+ oficina, el chip "❤️ N hoy" y la tarjeta "Mientras no estabas" con las visitas, los me gusta y los sellos dejados en la
963
+ recepción (nunca quién); a quien bloqueaste lo ves en **Bloqueados**, con **Desbloquear**. En el modo demostración:
964
+ [la rueda de saludos](docs/screenshots/world-social.png) y [la plaza con los fuegos](docs/screenshots/world-praca.png).
965
+
966
+ **Pausar, salir, eliminar.** **Pausar** apaga el edificio en el acto y guarda el lote (con 30 días en pausa, desaparece
967
+ del mapa; 30 días después, se retira). **Salir del mundo** retira el edificio y libera el lote; la cuenta y el personaje
968
+ siguen, y volver crea un edificio nuevo. **Eliminar cuenta** (en **Cuenta y datos**, con el código que llega por
969
+ correo) saca el edificio y el perfil del mundo en el acto, borra la cuenta, los likes, los bloqueos, las denuncias
970
+ hechas y los dispositivos de la base de datos en 7 días (y de las copias de seguridad en hasta 30) y borra el
971
+ `world.json` de esta computadora. Sin noticias de Busybits durante 7 días, el edificio desaparece del mapa y, 30 días
972
+ después, se retira; un correo avisa 3 días antes (se puede desactivar en **Cuenta y datos**).
973
+
974
+ **Exportar.** **Descargar mis datos** (en **Cuenta y datos**) guarda `habblaud-world-dados.json` con lo que el mundo
975
+ guarda de tu cuenta: correo, fechas, personaje, visibilidad, dispositivos, edificio, likes dados, bloqueos y denuncias
976
+ hechas. Una vez al día.
977
+
978
+ **Datos verdaderos.** El World solo funciona si los edificios son de verdad: cambiar Busybits para enviar pisos,
979
+ agentes, estados, tokens o personajes inventados o inflados rompe los Términos de Uso y banea la cuenta (el servidor
980
+ comprueba la plausibilidad de cada paquete). Cambiar Busybits para cualquier otra cosa sigue siendo libre (MIT). Cómo
981
+ habla Busybits con el World (en portugués): [shared/world/README.md](shared/world/README.md).
982
+
983
+ **Probar con un servidor del mundo local.** Para quien desarrolla el World, con el servidor del mundo corriendo en la
984
+ propia computadora (por ejemplo, en Docker, publicado en el puerto 4848):
985
+
986
+ - Fuera de Docker: `HABBLAUD_WORLD_URL=http://127.0.0.1:4848 npm run dev`.
987
+ - Con Busybits en Docker: en el `.env` de esta carpeta, `HABBLAUD_WORLD_URL=http://host.docker.internal:4848` y
988
+ `HABBLAUD_WORLD_DEV=1`; después, `npm run docker:up`, que termina con la línea del World
989
+ (`Habblaud World: activado: http://host.docker.internal:4848`, o por qué quedó desactivado). El `docker-compose.yml`
990
+ ya apunta `host.docker.internal` al host (`extra_hosts` con `host-gateway`; en Docker Desktop el nombre ya existe). En
991
+ Linux, el servidor del mundo tiene que escuchar en una interfaz que el contenedor alcance (`0.0.0.0` o la IP del
992
+ puente de Docker): un puerto publicado solo en el `127.0.0.1` del host no responde por `host-gateway`.
993
+ - Sin TLS, solo con `HABBLAUD_WORLD_DEV=1` (o `--dev`) y solo para `127.0.0.1` y `host.docker.internal`; fuera de eso,
994
+ solo `https://` o `wss://`. El servidor del mundo tiene que aceptar el nombre usado en la URL como host del juego (si
995
+ no, responde `421`).
996
+
997
+ Cómo se ve la sección, en el modo demostración (`?mock=1&world=logged_out`, `waiting` o `approved`; en portugués):
998
+ [sin cuenta](docs/screenshots/world-sem-conta.png), [lista de espera](docs/screenshots/world-lista-de-espera.png),
999
+ [personaje](docs/screenshots/world-personagem.png), [Tu edificio](docs/screenshots/world-predio.png) y
1000
+ [lo que se envió](docs/screenshots/world-enviado.png).
1001
+
1002
+ ## Cómo funciona
1003
+
1004
+ ```
1005
+ ~/.claude*/sessions/<pid>.json ─────────────────┐
1006
+ ~/.claude*/projects/<projeto>/<sessão>.jsonl ───┼──▶ servidor Node ──▶ modelo do escritório ──▶ SSE ──▶ navegador
1007
+ .../<sessão>/subagents/**/agent-*.jsonl ────────┘ (polling de 1 s) (canvas + interface)
1008
+ ```
1009
+
1010
+ - **Quién está en la oficina:** mientras una sesión está abierta, Claude Code mantiene `sessions/<pid>.json` con el
1011
+ proyecto y el estado (ocupado, ocioso, esperándote o esperando un shell en segundo plano). Eso es lo que decide
1012
+ quién aparece y qué hace cada uno.
1013
+ - **Shells en ejecución:** en los transcripts, cada `Bash` en segundo plano (o comando largo en primer plano) se
1014
+ convierte en un "shell" con etiqueta y cronómetro, hasta que llega la notificación de que terminó, falló o fue
1015
+ interrumpido.
1016
+ - **Vida social:** las rondas, las personalidades y las monedas son una simulación del navegador (`client/src/world/social/`),
1017
+ sin ningún efecto en los agentes de verdad. La personalidad sale de la semilla de cada agente (es la misma en
1018
+ cualquier navegador); los monederos quedan en el `localStorage` del navegador.
1019
+ - **Qué está haciendo cada uno:** el servidor sigue el final de los transcripts (`.jsonl`) de las sesiones abiertas y
1020
+ traduce cada llamada de herramienta a una actividad en el idioma del servidor, con ícono. De ahí también salen las tareas, el título, el modelo y las estadísticas.
1021
+ - **Subagentes:** los transcripts en `<sessão>/subagents/` (incluidos los de los workflows) se convierten en personajes
1022
+ vinculados al agente que los llamó.
1023
+ - **GitHub:** los PRs, pushes, CI y releases salen de las mismas líneas del transcript (el comando y su salida, o el
1024
+ `gitOperation` que el propio Claude Code guarda); no se consulta nada en GitHub.
1025
+ - **El dibujo:** el navegador recibe el estado por SSE y lo dibuja todo en un canvas: personajes, muebles, pisos y
1026
+ paredes son pixel art **generado por código**; en cambio, el logotipo, las ilustraciones y los cuadros de las paredes
1027
+ se generaron con IA.
1028
+
1029
+ <details>
1030
+ <summary><b>Estructura del código y API</b></summary>
1031
+
1032
+ ```
1033
+ shared/ protocolo (types.ts), atividades em PT-BR, nomes, simulador de demonstração
1034
+ server/ servidor HTTP + SSE: contas e uso, leitura das sessões e transcripts, modelo do escritório
1035
+ client/ Vite: src/art (pixel art procedural), src/world (o escritório no canvas), src/ui (interface)
1036
+ scripts/ build do servidor, docker-up, instaladores (mod, tap de statusline e hook de permissão) e screenshots
1037
+ mod/ o mod do Busybits e os plugins de permissões e de mensagens (plugins do Claude Code; marketplace em .claude-plugin/)
1038
+ ```
1039
+
1040
+ | Ruta | Descripción |
1041
+ | --- | --- |
1042
+ | `GET /api/stream` | SSE con los eventos `snapshot`, `feed` y `notice` (formato en `shared/types.ts`). |
1043
+ | `GET /api/snapshot` | Estado actual de la oficina. |
1044
+ | `GET /api/agents/:id` | Detalles de un agente, con hasta 200 actividades. |
1045
+ | `GET /api/agents/:id/terminal` | SSE de la terminal (eventos `init` y `append`); solo con acceso local. |
1046
+ | `PUT /api/agents/:id/character` | Editar el personaje: `{name, seed, parts}` guarda el nombre y la apariencia del agente principal como el personaje del proyecto (la sala); solo con acceso local. |
1047
+ | `DELETE /api/agents/:id/character` | "Volver al sorteo": borra el personaje del proyecto y el agente vuelve al nombre sorteado; solo con acceso local. |
1048
+ | `GET /api/sessions/recent` | Historial: sesiones de los últimos 7 días de todas las cuentas (hasta 150); solo con acceso local. |
1049
+ | `GET /api/sessions/:conta/:sessionId/terminal` | SSE de la conversación de una sesión del historial (mismo protocolo que la terminal); solo con acceso local. |
1050
+ | `GET /api/stats?day=AAAA-MM-DD` | Estadísticas de Mi día (tiempo por estado, proyectos, cuentas, horas, esperas, tokens y costo). |
1051
+ | `GET /api/stats/days` | Días con estadísticas (los últimos 30). |
1052
+ | `GET /api/timeline/days` | Días grabados para el timelapse, con el tamaño y la hora del primer y del último registro. |
1053
+ | `GET /api/timeline/:dia` | Línea de tiempo de un día (`AAAA-MM-DD`), en JSONL (con gzip). |
1054
+ | `GET /api/health` | Salud: versión, demostración, Docker, terminal, responder y enviar mensajes desde la oficina, fuentes y estado del uso de cada cuenta. |
1055
+ | `POST /api/demo` | `{"enabled": true \| false}` activa o desactiva los agentes simulados. |
1056
+ | `POST /api/rooms/rename` | `{"id": sala, "name": nome}` cambia el nombre de la sala (vacío vuelve al nombre de la carpeta); el nombre queda en `rooms.json`, en la carpeta de datos. Solo con acceso local. |
1057
+ | `GET /api/mod/summary` | Para el mod de Claude Code: versión, cuántos agentes hay, cuántos trabajan y quién te necesita (sin la demo y, con `?account=&session=`, sin la propia sesión). |
1058
+ | `/api/permissions…` | Responder desde la oficina: el hook de permisos registra la solicitud (permiso o pregunta) y espera; la página busca el detalle y decide o responde. Solo con acceso local. |
1059
+ | `/api/messages…` y `/api/mod/inbox…` | Enviar mensajes: la página deja el mensaje en la cola y sigue la entrega; el plugin `busybits-messages` lo recoge, lo entrega a la sesión y lo confirma. Solo con acceso local. |
1060
+ | `POST /api/codex/events` | Eventos de los hooks de Codex (sesión abierta, herramienta, aprobación, fin del turno). Solo con acceso local. |
1061
+ | `/api/codex/bridge/poll` y `/ack` | `npm run codex:bridge` recoge los mensajes para Codex y confirma la entrega. Solo con acceso local. |
1062
+
1063
+ Más detalles del servidor en [`server/README.md`](server/README.md).
1064
+
1065
+ </details>
1066
+
1067
+ <details>
1068
+ <summary><b>Qué monta Docker y por qué</b></summary>
1069
+
1070
+ | Host | Contenedor | Para qué |
1071
+ | --- | --- | --- |
1072
+ | `<conta>/sessions/` | `/claude/<conta>/sessions` (solo lectura) | Sesiones abiertas y sus estados. |
1073
+ | `<conta>/projects/` | `/claude/<conta>/projects` (solo lectura) | Transcripts de las sesiones y de los subagentes. |
1074
+ | `~/.habblaud/usage/` | `/usage` (solo lectura) | Uso capturado por el mod (o por el tap de statusline). |
1075
+ | volumen `habblaud-data` | `/data` | Datos del propio Busybits (nombres de los personajes, línea de tiempo del timelapse y estadísticas de Mi día). |
1076
+ | `~/.habblaud/remote-tls/server/` | `/remote-tls` (solo lectura) | Solo después de `npm run remote:setup`: el certificado y la clave del servidor del [celular con inicio de sesión](#celular-con-inicio-de-sesión-y-https-aprobar-solicitudes) (nunca la clave de la CA). |
1077
+
1078
+ La carpeta de la cuenta **nunca** se monta entera (ahí están las credenciales y la configuración). El contenedor se
1079
+ ejecuta como usuario sin privilegios, con el sistema de archivos de solo lectura, sin capabilities extra y con
1080
+ `no-new-privileges`. Los metadatos de las cuentas (letra, correo, organización) los lee `docker:up` en el host y se
1081
+ los pasa al contenedor.
1082
+
1083
+ </details>
1084
+
1085
+ ## Privacidad y seguridad
1086
+
1087
+ - **Solo lectura:** Busybits nunca escribe en las carpetas de Claude Code. Las excepciones son los instaladores, que
1088
+ ejecutas tú: `npm run mod:install` / `mod:uninstall` usa el propio `claude plugin` (que registra el marketplace y los
1089
+ plugins en el `settings.json` y en `<conta>/plugins/`) y, en la instalación, quita el tap y el hook antiguos con copia
1090
+ de seguridad; en el método antiguo, `npm run usage:install` / `usage:uninstall` cambia solo el `statusLine.command`
1091
+ del `settings.json` y `npm run hooks:install` / `hooks:uninstall`, solo la lista `hooks.PermissionRequest`, siempre
1092
+ con una copia de seguridad antes.
1093
+ - **El mod:** se ejecuta dentro de cada sesión de Claude Code, con tus permisos (como todo mod), y hace solo lo que está
1094
+ listado en [`mod/README.md`](mod/README.md); `claude plugin validate mod/habblaud` muestra los eventos y las llamadas,
1095
+ sin ejecutar nada. Guarda solo los porcentajes de uso de 5 horas y de la semana (y cuándo se reinician) en
1096
+ `~/.habblaud/usage/<conta>.json`; para la línea de "te necesita" y el `/busybits`, solo habla con Busybits en
1097
+ `127.0.0.1`. No lee la conversación, no llama al modelo y no envía nada fuera de la computadora. Se lee desde esta
1098
+ carpeta: lo que haya en ella (incluso después de un `git pull`) es lo que se ejecuta. El plugin de mensajes
1099
+ (`busybits-messages`) está separado justamente porque actúa: escribe en la sesión lo que enviaste desde la oficina.
1100
+ - **Solo local, por defecto:** el servidor solo acepta conexiones de la propia computadora; abrirlo a la red local es
1101
+ opcional. No hay telemetría. La única llamada externa es la comprobación de versión nueva: activada por defecto
1102
+ en instalaciones empaquetadas (desactivada en clon y Docker; `HABBLAUD_UPDATE_CHECK=1` o `0` lo cambia), cada 6 horas,
1103
+ una consulta anónima, sin token, al registro de npm (`registry.npmjs.org/busybits`). No envía nada sobre tus sesiones;
1104
+ npm ve solo tu IP. Con `HABBLAUD_UPDATE_CHECK=0` (o en un clon sin `=1`), no hay consulta.
1105
+ [Habblaud World](#habblaud-world) (desactivado por defecto en Busybits; `HABBLAUD_WORLD=1` lo activa) solo envía algo
1106
+ al servidor del mundo después de que crees la cuenta y entres, y solo lo que está en
1107
+ [lo que sale](docs/world/privacidade.md) (en portugués).
1108
+ El [celular con inicio de sesión](#celular-con-inicio-de-sesión-y-https-aprobar-solicitudes) también, y solo existe después de `npm run remote:setup`.
1109
+ - **Sin credenciales:** Busybits no lee contraseñas ni tokens de acceso. Del `.claude.json` de cada cuenta aprovecha
1110
+ solo el correo, la organización y la caché de `/usage`; el uso en vivo viene del mod (o del tap de statusline).
1111
+ - **Secretos enmascarados:** los tokens y contraseñas con formato conocido (`Bearer`, `-u usuário:senha`, `TOKEN=`,
1112
+ claves `sk-…`, `ghp_…`, `AKIA…`, JWTs, contraseñas en URLs) se convierten en `***` antes de llegar al navegador.
1113
+ - **Protegido contra sitios maliciosos:** el servidor rechaza direcciones que no sean `localhost`/IP (DNS rebinding) y
1114
+ `POST` que vengan de otros orígenes (CSRF), y no deja que la página se incruste en otros sitios.
1115
+ - **Terminal solo local:** la conversación completa de las sesiones (y el historial de las sesiones cerradas, con los
1116
+ títulos) solo sale del servidor con Busybits accesible únicamente desde la propia computadora (`HABBLAUD_HOST` local
1117
+ en Node; `HABBLAUD_BIND` local en Docker); no hay forma de
1118
+ activarla con el puerto expuesto, y cada solicitud tiene que llegar por `localhost`/`127.0.0.1`: las IP de la red y
1119
+ los nombres de `HABBLAUD_ALLOWED_HOSTS` (proxies, túneles) se rechazan. Los secretos se enmascaran y los textos
1120
+ largos se truncan antes de llegar al navegador; en el modo demostración, la conversación es ficticia.
1121
+ `HABBLAUD_TERMINAL=0` la desactiva por completo.
1122
+ La única excepción es el [celular con inicio de sesión](#celular-con-inicio-de-sesión-y-https-aprobar-solicitudes), y solo con `terminal` en `HABBLAUD_REMOTE_ALLOW`.
1123
+ - **Línea de tiempo del timelapse:** solo los resúmenes que ya aparecen en pantalla (actividad en una línea, estado,
1124
+ títulos, uso de las cuentas; sin correos, comandos completos ni conversaciones), guardados en
1125
+ `~/.habblaud/timeline/` y borrados después de 7 días. `HABBLAUD_TIMELINE=0` desactiva la grabación.
1126
+ - **Responder desde la oficina, solo local:** aprobar o rechazar actúa sobre las sesiones, así que sigue el mismo
1127
+ bloqueo que la terminal (bind local, `Host` local, nada de proxies ni túneles) y solo existe con el hook de permisos
1128
+ (el del plugin `busybits-permissions` o el del método antiguo) instalado por ti. Las respuestas exigen JSON y origen
1129
+ local (un sitio abierto en el navegador no puede enviarlas), el hook solo habla con `127.0.0.1` y, ante la duda
1130
+ (Busybits caído, error, tiempo agotado), sale sin decidir: vale la terminal. El comando completo o el diff solo salen
1131
+ del servidor hacia quien abrió la página desde la propia computadora. "Permitir siempre" solo aplica una regla que el
1132
+ propio Claude Code sugirió para esa solicitud. Atención: cualquier programa o persona que pueda abrir
1133
+ `http://localhost:4747` en esta máquina también puede responder; en computadoras compartidas con otros usuarios, no
1134
+ instales el hook (`npm run mod:install -- --sem-permissoes`).
1135
+ Excepción: el [celular con inicio de sesión](#celular-con-inicio-de-sesión-y-https-aprobar-solicitudes) también responde (es lo predeterminado) y ve el mismo comando o diff.
1136
+ - **Enviar mensajes, solo local, y con una advertencia:** el mensaje entra en la sesión como si lo hubieras escrito
1137
+ tú, así que vale lo que el agente puede hacer con una solicitud tuya. Sigue el mismo bloqueo (bind local, `Host`
1138
+ local, JSON y origen local, así que un sitio abierto en el navegador no puede enviarlo), pero **cualquier programa de
1139
+ esta máquina** que hable con `http://localhost:4747`, incluido un agente que ejecute un comando, puede dejarle un
1140
+ mensaje a otra sesión que tenga el plugin. Si eso no te sirve (computadora compartida, agentes ejecutándose sin
1141
+ supervisión), no instales el plugin (`npm run mod:install -- --sem-mensagens`) o desactívalo con
1142
+ `HABBLAUD_MENSAGENS=0`. El texto de los mensajes no se guarda: desaparece del servidor en cuanto se entrega.
1143
+ Desde el [celular con inicio de sesión](#celular-con-inicio-de-sesión-y-https-aprobar-solicitudes), solo con `messages` en `HABBLAUD_REMOTE_ALLOW`.
1144
+ - **Terminal interactiva, opcional (opt-in), y con una advertencia:** con `HABBLAUD_PTY=1`, la oficina abre Claude
1145
+ Code en cualquier carpeta, escribe en él (incluido `!comando`, que se ejecuta en el shell) y cierra o toma el control
1146
+ de sesiones abiertas en otras terminales. Sigue el mismo bloqueo que la terminal (bind local, `Host` local, nada de
1147
+ proxies ni túneles) y cada solicitud tiene que venir de la propia computadora, con origen local (un sitio abierto en
1148
+ el navegador no puede enviarla). Aun así, **cualquier programa de esta máquina** que hable con
1149
+ `http://localhost:4747`, incluido un agente que ejecute un comando, obtiene ese poder. Antes de terminar un proceso
1150
+ externo, Busybits comprueba en el registro de sesiones y en el sistema que ese PID sigue siendo ese Claude Code
1151
+ (mismo inicio y ejecutable). En computadoras compartidas o con agentes ejecutándose sin supervisión, déjala
1152
+ desactivada.
1153
+ - **Celular con inicio de sesión, opcional (opt-in):** solo existe después de `npm run remote:setup`. Un segundo
1154
+ puerto con HTTPS (una CA local que solo firma nombres `.local`, `localhost`, tu dirección propia e IP privadas),
1155
+ usuario y contraseña (solo se guarda el hash scrypt); la sesión es una cookie `HttpOnly`, `SameSite=Strict` y
1156
+ `Secure` firmada con HMAC. En ese puerto, lo permitido sale de `HABBLAUD_REMOTE_ALLOW` (por defecto, solo responder
1157
+ solicitudes de permiso), nunca del encabezado Host; las rutas de los hooks, de los plugins y del auxiliar del host,
1158
+ la terminal interactiva, el editor de personajes y cambiar el nombre de las salas nunca funcionan por él. Quien
1159
+ tenga la contraseña obtiene lo que permitiste: elige una fuerte y permite solo lo que necesites. La clave de la CA
1160
+ queda en `~/.habblaud/remote-tls/ca` y nunca entra en el contenedor.
1161
+ - **Nuevo agente, opcional (opt-in):** con `HABBLAUD_PTY=1`, la oficina inicia sesiones de Claude Code con la
1162
+ solicitud que escribiste, en la carpeta que elijas; vale la misma advertencia que para la terminal interactiva. Los
1163
+ adjuntos se guardan en `~/.habblaud/attachments/` (carpeta 700, archivos 600). En Docker, quien inicia las sesiones
1164
+ es el auxiliar del host (`npm run codex:bridge`), que además solo lee los archivos de las entregas de carpetas de
1165
+ proyecto conocidas (las que Claude Code tiene en `<conta>/projects`), de la carpeta temporal y de los adjuntos.
1166
+ - **Editor de personajes, solo local:** guardar o volver al sorteo cambia la oficina y escribe en `names.json`, así
1167
+ que sigue el mismo bloqueo que la terminal (bind local, `Host` local, nada de proxies ni túneles): sin él, el lápiz
1168
+ no aparece y el servidor responde `403`. Los cambios exigen JSON y origen local. `HABBLAUD_TERMINAL=0` también lo
1169
+ desactiva.
1170
+ - **Estadísticas de Mi día:** solo números agregados (tiempo por estado, conteos, tokens, costo) con los nombres de
1171
+ proyecto, cuenta y agente, guardados en `HABBLAUD_DATA_DIR/stats/` durante 30 días; nada de la conversación.
1172
+ - **Codex:** Busybits lee solo las conversaciones (`sessions/`, `archived_sessions/`) y los bloqueos de las sesiones
1173
+ abiertas (`thread-writer-locks/`); en Docker, solo se montan esas tres carpetas, en modo de solo lectura. Nunca lee
1174
+ el `auth.json`, el `config.toml`, el entorno del shell (`shell_snapshots/`), el historial de prompts, los logs ni las
1175
+ bases de datos de Codex, y no muestra los ids de la cuenta de ChatGPT. `npm run codex:install` solo agrega grupos al
1176
+ `hooks.json` (con copia de seguridad; los de otras apps se quedan en su lugar) y guarda `~/.habblaud/codex-hook.json`;
1177
+ la aprobación de los hooks siempre es tuya, en `/hooks`. Los hooks solo hablan con `127.0.0.1`. Los mensajes a Codex
1178
+ tienen la misma advertencia que los de Claude Code: cualquier programa de esta máquina que hable con Busybits puede
1179
+ dejar un mensaje en la cola de una sesión.
1180
+ - **Lo que aparece en pantalla:** resúmenes de las actividades (herramienta, archivo, comando o consulta), títulos de
1181
+ las sesiones, tareas y estadísticas (y, en la terminal, la conversación). No expongas el puerto en redes en las que
1182
+ no confíes.
1183
+
1184
+ ## Desarrollo
1185
+
1186
+ | Comando | Qué hace |
1187
+ | --- | --- |
1188
+ | `npm run dev` | Servidor + Vite en http://localhost:4747, con recarga automática. |
1189
+ | `npm run dev:client` | Solo Vite, en http://localhost:5173 (ábrelo con `?mock=1`; `/api` se redirige al puerto 4747). |
1190
+ | `npm run demo` | `npm run dev` con el modo demostración activado. |
1191
+ | `npm run build` / `npm start` | Compila y ejecuta la versión de producción. |
1192
+ | `npm test` | Pruebas (Vitest). |
1193
+ | `npm run typecheck` | Verificación de tipos del cliente, el servidor y los scripts. |
1194
+ | `claude plugin test mod/habblaud` | Pruebas del mod (sin sesión, cuenta ni red); lo mismo para `mod/habblaud-mensagens`. |
1195
+ | `claude plugin validate .` | Valida el marketplace (`.claude-plugin/marketplace.json`); con `mod/habblaud`, `mod/habblaud-permissoes` o `mod/habblaud-mensagens`, valida el plugin y lista los eventos y las llamadas del mod. |
1196
+ | `claude --plugin-dir mod/habblaud` | Abre una sesión con el mod de esta carpeta, sin instalarlo (edita y ejecuta `/reload-plugins`). |
1197
+ | `npm run mod:status` | Muestra, por cuenta, el marketplace, los plugins y las versiones instaladas. |
1198
+ | `npm run demo:timeline` | Genera una línea de tiempo ficticia (simulador del modo demostración) para el timelapse. |
1199
+ | `npm run release` | Publica la versión del `package.json` en GitHub (tag y release con las notas del `CHANGELOG.md`). |
1200
+
1201
+ Para tomar capturas de pantalla sin abrir tu navegador, `scripts/shot.mjs` usa un Chromium headless aislado
1202
+ (Playwright). La primera vez, descarga el navegador (una sola vez): `npx playwright-core install chromium-headless-shell`.
1203
+
1204
+ ```bash
1205
+ node scripts/shot.mjs 'http://localhost:4747/?mock=1&speed=3' /tmp/habblaud.png --size 1400x900 --wait 4000
1206
+ ```
1207
+
1208
+ En la consola del navegador, `habblaud.world.debug` tiene herramientas para probar escenas (p. ej.,
1209
+ `habblaud.world.debug.setHour(21)` para ver la noche). Para fijar la hora desde que se abre, usa `?hora=21:30` en la
1210
+ URL.
1211
+
1212
+ **Timelapse solo con datos ficticios** (p. ej., para grabar un GIF): `npm run demo:timeline` ejecuta el simulador del
1213
+ modo demostración sin conexión y graba un día entero (por defecto, ayer de 9 a 19 h, con la mañana llena, el almuerzo
1214
+ más vacío y un pico por la tarde) en `<tmp>/habblaud-demo/timeline/`. Después, inicia un Busybits que solo lea esa
1215
+ carpeta y no muestre tus sesiones, y abre el Timelapse:
1216
+
1217
+ ```bash
1218
+ npm run demo:timeline -- --data-dir /tmp/habblaud-demo # opções: --date, --start 8:30, --hours, --sessions, --seed
1219
+ mkdir -p /tmp/habblaud-demo/vazio
1220
+ HABBLAUD_DATA_DIR=/tmp/habblaud-demo HABBLAUD_TIMELINE=0 HABBLAUD_CLAUDE_DIRS=/tmp/habblaud-demo/vazio \
1221
+ HABBLAUD_PORT=4848 npm start # depois de npm run build; abra http://localhost:4848
1222
+ ```
1223
+
1224
+ `HABBLAUD_TIMELINE=0` evita grabar en esa carpeta; con la grabación activada, se borran los días con más de 7 días.
1225
+
1226
+ **Publicar una versión:** cada versión tiene su sección en el [`CHANGELOG.md`](CHANGELOG.md), con lo que entró.
1227
+ Durante el trabajo, anota los cambios en "Não lançado" (la sección de lo que aún no se publicó). Para publicar:
1228
+
1229
+ 1. Sube el número con `npm version minor --no-git-tag-version` (o `patch`, en una versión solo de correcciones).
1230
+ 2. Cambia "Não lançado" por la versión y la fecha (`## [0.3.0] - AAAA-MM-DD`), deja un "Não lançado" vacío arriba y
1231
+ actualiza los enlaces del final. `npm test` falla si la versión del `package.json` no tiene sección.
1232
+ 3. Haz el merge en `main` y ejecuta `npm run release` (requiere [`gh`](https://cli.github.com/) autenticado;
1233
+ `-- --dry-run` solo muestra las notas). El script crea el tag `v0.3.0` y la release con el texto de la sección. A
1234
+ partir de ahí, quienes usan Busybits ven el sello **Nueva versión**.
1235
+
1236
+ ## Solución de problemas
1237
+
1238
+ <details>
1239
+ <summary><b>La oficina está vacía</b></summary>
1240
+
1241
+ Solo aparecen las sesiones **abiertas** de Claude Code. Comprueba si hay alguna en ejecución y si la cuenta se detectó
1242
+ en `http://localhost:4747/api/health`. Si las carpetas de las cuentas están en otro lugar, usa
1243
+ `HABBLAUD_CLAUDE_DIRS=/caminho/conta1,/caminho/conta2`.
1244
+
1245
+ </details>
1246
+
1247
+ <details>
1248
+ <summary><b>El uso aparece como "sin datos" o "desactualizado"</b></summary>
1249
+
1250
+ Ejecuta `npm run mod:install` (o, en Claude Code anterior a 2.1.287, `npm run usage:install`) y compruébalo con
1251
+ `npm run mod:status` (o `npm run usage:status`). Los números llegan después de la siguiente respuesta en una sesión
1252
+ abierta de esa cuenta; en una sesión abierta antes de la instalación, ejecuta `/reload-plugins` o vuelve a abrir la
1253
+ sesión. Un **—** en lugar del porcentaje significa que la ventana se reinició desde la última recolección.
1254
+
1255
+ </details>
1256
+
1257
+ <details>
1258
+ <summary><b>El mod no se carga en una sesión</b></summary>
1259
+
1260
+ Ejecuta `npm run mod:status`: muestra la versión de Claude Code (el mod requiere la 2.1.287 o más reciente) y, por
1261
+ cuenta, si el marketplace apunta a esta carpeta y si los plugins están instalados y activados. En una sesión abierta
1262
+ antes de la instalación, ejecuta `/reload-plugins`; `/plugin` muestra, debajo de las pestañas, los mods cargados (p. ej.,
1263
+ `1 mod active · habblaud`). Los mods no se ejecutan con `"disableAllHooks": true` en el `settings.json` de la cuenta ni
1264
+ con `claude --safe-mode`.
1265
+
1266
+ </details>
1267
+
1268
+ <details>
1269
+ <summary><b>"El puerto 4747 ya está en uso"</b></summary>
1270
+
1271
+ Ya hay otro Busybits (Node o Docker) en ejecución. Detenlo (`npm run docker:down`, o Ctrl+C en la terminal de
1272
+ `npm start`) o usa otro puerto: `HABBLAUD_PORT=4848 npm run docker:up` (Docker) o `HABBLAUD_PORT=4848 npm start`
1273
+ (Node).
1274
+
1275
+ </details>
1276
+
1277
+ <details>
1278
+ <summary><b>No abre en el celular</b></summary>
1279
+
1280
+ Comprueba que creaste el `.env` con `HABBLAUD_BIND=0.0.0.0` y que recreaste el contenedor
1281
+ (`npm run docker:up -- --no-build`), que el celular está en la misma red Wi-Fi y que el firewall de la computadora
1282
+ permite conexiones en el puerto 4747. Por IP funciona directamente; para abrirlo por un nombre (p. ej.,
1283
+ `meu-mac.local`), agrega `HABBLAUD_ALLOWED_HOSTS=meu-mac.local` (en Docker, en el mismo `.env`).
1284
+
1285
+ </details>
1286
+
1287
+ <details>
1288
+ <summary><b>La terminal no abre</b></summary>
1289
+
1290
+ La terminal solo existe con Busybits accesible únicamente desde la propia computadora. Comprueba que el `.env` no
1291
+ tenga `HABBLAUD_BIND=0.0.0.0` (o, en modo Node, que no usaste `HABBLAUD_HOST=0.0.0.0`) ni `HABBLAUD_TERMINAL=0`, y
1292
+ ábrelo por `http://localhost:4747` (por la IP de la red o por un nombre de `HABBLAUD_ALLOWED_HOSTS` se rechaza). En
1293
+ Docker, un contenedor creado antes de esta función tiene que recrearse: `npm run docker:up`. El log de inicio
1294
+ (`npm run docker:logs`) dice si la terminal está activada y, si no lo está, por qué.
1295
+
1296
+ </details>
1297
+
1298
+ <details>
1299
+ <summary><b>La solicitud de permiso (o la pregunta) no aparece en la oficina</b></summary>
1300
+
1301
+ Ejecuta `npm run mod:status`: dice, por cuenta, si el plugin `busybits-permissions` está instalado y activado (y si
1302
+ quedó también el hook antiguo, lo que haría que respondieran dos) y si Busybits está respondiendo solicitudes. En el
1303
+ método antiguo, `npm run hooks:status` dice si el hook está instalado y apunta a esta carpeta. La solicitud solo se
1304
+ desvía con alguna página de Busybits abierta por `http://localhost` (o `127.0.0.1`) y con la terminal activada (mismo
1305
+ bloqueo). Las sesiones abiertas antes de la instalación cargan el plugin con `/reload-plugins` (o al volver a
1306
+ abrirlas). En el método antiguo, si Busybits usa otro puerto, reinstala con `npm run hooks:install -- --port <porta>`.
1307
+ Para las preguntas del agente, el plugin tiene que ser el de la 0.6.0 o más reciente: ejecuta `npm run mod:install`
1308
+ después de actualizar.
1309
+
1310
+ </details>
1311
+
1312
+ <details>
1313
+ <summary><b>Codex no aparece en la oficina (o aparece con retraso)</b></summary>
1314
+
1315
+ El log de inicio (`npm run docker:logs`) dice cuántas cuentas de Codex encontró Busybits; si no encontró ninguna,
1316
+ indica la carpeta con `HABBLAUD_CODEX_DIRS` (y vuelve a ejecutar `npm run docker:up`: en Docker, solo se montan las
1317
+ carpetas que existían al ejecutar `docker:up`). Sin los hooks, Codex aparece por sus archivos, que solo se guardan
1318
+ después de cada paso: ejecuta `npm run codex:install`, **aprueba los hooks en `/hooks` en Codex** y compruébalo con
1319
+ `npm run codex:status`. Codex ejecuta los hooks con el shell de inicio de sesión, que puede tener un Node antiguo;
1320
+ `codex:install` elige un Node 22+ y dice cuál (o usa `--node <caminho>`). Una sesión de la CLI recién abierta solo
1321
+ aparece con el **primer mensaje**: antes de eso, Codex no dice en qué carpeta está (solo crea el bloqueo de la
1322
+ sesión), y sin la carpeta no hay sala.
1323
+
1324
+ </details>
1325
+
1326
+ <details>
1327
+ <summary><b>El cuadro de mensaje no aparece (o se queda en cola)</b></summary>
1328
+
1329
+ El cuadro solo aparece para los agentes principales cuya sesión tiene el plugin `busybits-messages` conectado:
1330
+ ejecuta `npm run mod:status` (dice, por cuenta, si el plugin está instalado y si Busybits tiene los mensajes
1331
+ activados) y, en las sesiones abiertas antes de la instalación, `/reload-plugins`. Sin el plugin, los detalles del
1332
+ agente muestran la sugerencia de instalación. Los mensajes siguen el bloqueo de la terminal y `HABBLAUD_MENSAGENS=0`
1333
+ los desactiva; el log de inicio (`npm run docker:logs`) dice si están activados y, si no lo están, por qué. Un mensaje
1334
+ que se queda **en cola** y falla con "la sesión no recogió el mensaje" significa que la sesión dejó de consultar a
1335
+ Busybits (se cerró, o el plugin se desactivó).
1336
+
1337
+ </details>
1338
+
1339
+ <details>
1340
+ <summary><b>En Docker, una sesión cerrada sigue en la oficina</b></summary>
1341
+
1342
+ Pasa si Claude Code se cerró a la fuerza sin borrar su propio registro en `sessions/` (en Docker no se puede
1343
+ comprobar si el proceso todavía existe). Si lo ejecutas con Node (`npm start`), Busybits revisa los procesos y esto no
1344
+ pasa.
1345
+
1346
+ </details>
1347
+
1348
+ <details>
1349
+ <summary><b>En Docker, una cuenta fuera de /Users no aparece</b></summary>
1350
+
1351
+ Docker Desktop solo comparte algunas carpetas del Mac con los contenedores (por defecto `/Users`, `/Volumes`, `/private`
1352
+ y `/tmp`). Agrega la carpeta en *Settings › Resources › File sharing*.
1353
+
1354
+ </details>
1355
+
1356
+ <details>
1357
+ <summary><b>Quiero empezar de cero</b></summary>
1358
+
1359
+ `npm run docker:down`, después `docker volume rm habblaud_habblaud-data` (borra los nombres guardados) y
1360
+ `npm run docker:up`.
1361
+
1362
+ </details>
1363
+
1364
+ ## Aviso
1365
+
1366
+ Busybits es un proyecto independiente, **no afiliado, patrocinado ni respaldado por Anthropic**. "Claude" y
1367
+ "Claude Code" son marcas de Anthropic, usadas aquí solo para describir con qué funciona el proyecto.
1368
+
1369
+ Para mostrar los agentes, Busybits lee únicamente archivos locales que el propio Claude Code guarda en tu máquina
1370
+ (registros de las sesiones abiertas, transcripts y configuración de las cuentas). Ese formato no está documentado y puede cambiar entre versiones de Claude Code:
1371
+ después de una actualización, Busybits puede dejar de funcionar, total o parcialmente, hasta que se ajuste.
1372
+
1373
+ ## Licencia
1374
+
1375
+ [MIT](LICENSE). Las imágenes en `client/public/assets` (logotipo, ilustraciones, cuadros y pósters) se generaron con
1376
+ IA para este proyecto y se convirtieron en pixel art con los scripts de `scripts/assets/`.
1377
+
1378
+ ## Vida social
1379
+
1380
+ Cuando dos o más agentes no tienen nada que hacer (ociosos, o esperando un shell desde hace más de 40 segundos),
1381
+ dejan de pasear solos y se juntan. Nadie se pone de acuerdo: cada personaje tiene una **personalidad**, **amigos** y
1382
+ **rivales**, y eso decide qué prefiere hacer, con quién y qué dice. Quien está esperando un shell solo deja su
1383
+ escritorio para una ronda (si está solo, sigue con las palomitas) y se lleva el reloj de arena; cuando el comando
1384
+ termina (o cuando le envías una solicitud nueva a alguien), avisa al grupo ("¡Uy, me llaman! 🏃") y vuelve corriendo
1385
+ a su escritorio.
1386
+
1387
+ <p align="center">
1388
+ <img src="docs/screenshots/social-lounge.gif" width="816" alt="Salón de Busybits con tres rondas al mismo tiempo: tres compañeros en el sofá viendo fútbol en la TV (la pantalla parpadea GOL), un partido de ping-pong con público animando y un duelo en las máquinas arcade con provocaciones en los globos" />
1389
+ </p>
1390
+
1391
+ ### Las rondas
1392
+
1393
+ | | Ronda | Qué pasa |
1394
+ | --- | --- | --- |
1395
+ | 📺 | **TV en el salón** | Fútbol, telenovela o dibujos animados, con palomitas en el sofá. En el fútbol, el público celebra junto con el "GOL" que parpadea en la pantalla (o lamenta el gol del rival); en la telenovela, corazoncitos y "¡No lo puedo creer! 😱". Quien es de siestas acaba dormido en el sofá. |
1396
+ | 🎮 | **Videojuegos** | Dos en el sofá con el control, la TV en pantalla dividida (carreras o pelea), al mejor de 3, provocaciones ("¿¡Qué es este lag!?") y público animando. |
1397
+ | 👾 | **Arcade** | Duelo en las dos máquinas del salón, una sola partida. |
1398
+ | 🏓 | **Ping-pong** | Hasta 5 puntos, con la pelotita yendo y viniendo, el marcador en los globos ("3 × 2 🏓") y público animando detrás de la mesa. |
1399
+ | ☕ | **Charla en la cocina** | Cada uno toma un café (o agua) y se sienta a la mesa: chismes con el nombre de los compañeros ("¿Viste el commit de Rafaela? 👀"), chistes (el grupo se ríe a carcajadas), trabajo ("¿Deploy un viernes? 😈") y temas del día y de la hora ("¡Por fin es viernes! 🎉"). |
1400
+ | 💬 | **Conversación** | Dos compañeros de pie en un rincón de la recepción, la cocina o el salón. |
1401
+ | ✊ | **Piedra, papel o tijera con apuesta** | "Jo… ken… ¡po!", los gestos aparecen sobre la cabeza, quien gana celebra y las monedas vuelan de uno a otro; quien pierde se enoja y, si es competitivo, pide la revancha. Si empatan, repiten. Quien pasa por ahí puede detenerse a mirar. |
1402
+ | 💄 | **Espejo del baño** | Labial o peine, con la cara reflejada en el espejo y un brillo al final. Vale solo o en pareja ("¿Me prestas el peine?"). |
1403
+
1404
+ <table>
1405
+ <tr>
1406
+ <td width="50%"><img src="docs/screenshots/social-rps.png" alt="Piedra, papel o tijera en la recepción: Lia celebra con una moneda sobre la cabeza y el globo '¡Gané!', las monedas vuelan de Bruna (enojada, con el ícono de piedra) hacia ella, '+20' y '−20' flotando, e Iara mira detrás" /></td>
1407
+ <td width="50%"><img src="docs/screenshots/social-kitchen.png" alt="Charla en la cocina: cuatro compañeros sentados a la mesa larga con café, con los globos '¡Va a salir bien!' y 'Jajaja'" /></td>
1408
+ </tr>
1409
+ <tr>
1410
+ <td><b>Piedra, papel o tijera por monedas.</b> La apuesta sale de la personalidad (quien es de apuestas apuesta fuerte, quien es tacaño apuesta poco) y nunca supera el saldo de quien tiene menos.</td>
1411
+ <td><b>Charla en la cocina.</b> Quien más habla es quien es más sociable; las reacciones dependen del tema (carcajadas con el chiste, 👀 con el chisme).</td>
1412
+ </tr>
1413
+ <tr>
1414
+ <td><img src="docs/screenshots/social-mirror.png" alt="Dos compañeras frente a los lavabos del baño arreglándose, con las caras reflejadas en los espejos y el globo '¡Estás arrasando!'" /></td>
1415
+ <td><img src="docs/screenshots/social-drawer.png" alt="Sección Vida social en los detalles del agente: 'Viendo una telenovela en la tele con Bruna e Iara', 115 monedas, 1 victoria y 0 derrotas, los rasgos Vanidad y Ahorro, la muletilla, amistades, rivalidades con el marcador y los movimientos" /></td>
1416
+ </tr>
1417
+ <tr>
1418
+ <td><b>En el espejo.</b> Quien es de vanidad pasa por el baño siempre que puede, y aparece reflejado.</td>
1419
+ <td><b>En los detalles del agente.</b> Qué está haciendo, el monedero, el marcador, la personalidad, las amistades y rivalidades (con el historial) y los movimientos.</td>
1420
+ </tr>
1421
+ </table>
1422
+
1423
+ ### Personalidades
1424
+
1425
+ Cada agente tiene 2 o 3 rasgos, sorteados a partir de su semilla (siempre es la misma persona, en cualquier navegador):
1426
+
1427
+ 🏆 Competitividad · 🎲 Apuestas · 🎮 Videojuegos · 📺 Series y TV · 🗣️ Chismes · 💄 Vanidad · ☕ Cafeína · 😂 Chistes · 🏓 Deporte ·
1428
+ 🙈 Timidez · 💰 Ahorro · 😴 Siestas · 🧘 Calma · 📚 Lectura
1429
+
1430
+ Los rasgos cambian lo que elige cada uno (quien es de series enciende la TV, quien es de deporte invita al ping-pong),
1431
+ a quién llama (los amigos se buscan; los rivales se desafían en los juegos), qué dice e incluso quién juega mejor. Cada
1432
+ uno tiene también una muletilla ("¡Hecho!", "¡A programar!"). Pasa el cursor sobre un rasgo en los detalles del agente
1433
+ para ver qué hace.
1434
+
1435
+ ### Monedas
1436
+
1437
+ Monedas ficticias (🪙), solo para darles gracia a las apuestas:
1438
+
1439
+ | | |
1440
+ | --- | --- |
1441
+ | **Llegó a la oficina** | 🪙100 (subagentes, 🪙30) |
1442
+ | **Tarea completada** (elemento de la lista de tareas) | +🪙10 |
1443
+ | **Solicitud atendida** (fin de turno) | +🪙5 |
1444
+ | **El subagente entregó el resultado** | +🪙15 |
1445
+ | **Apuestas** (piedra, papel o tijera; partidas entre rivales o con quien es de apuestas) | lo que pierde uno va para quien gana |
1446
+
1447
+ Cada ganancia aparece como "+🪙10" sobre la cabeza; las partidas y apuestas entran en el feed de actividad. El saldo,
1448
+ el marcador y los movimientos quedan guardados en el navegador (cada navegador tiene su propia economía: las apuestas
1449
+ se sortean ahí) y se olvidan tres días después de que el agente se va.
1450
+
1451
+ > Todo esto es teatro de Busybits: nada cambia en los agentes de Claude Code, que siguen trabajando con normalidad.
1452
+
1453
+ ---
1454
+
1455
+ <p align="center">
1456
+ Hecho con ☕ y muchos agentes de <a href="https://code.claude.com">Claude Code</a>.
1457
+ </p>