busybits 2.0.0 → 2.1.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 (34) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/CHANGELOG.md +21 -0
  3. package/README.es.md +27 -27
  4. package/README.fr.md +26 -26
  5. package/README.md +63 -34
  6. package/README.pt-BR.md +28 -28
  7. package/dist/build.json +2 -2
  8. package/dist/cli/busybits.js +302 -35
  9. package/dist/client/bundle/app-BXRp9yel.js +24 -0
  10. package/dist/client/bundle/{app-CoDOLwxe.css → app-Y2N0l58V.css} +1 -1
  11. package/dist/client/bundle/city-SSVRvwxu.js +1 -0
  12. package/dist/client/bundle/{daystats-DGzYOP8l.js → daystats-B5wgtYEK.js} +1 -1
  13. package/dist/client/bundle/{dom-D2vx0KTo.js → dom-DTwIMOMe.js} +1 -1
  14. package/dist/client/bundle/{en-DBfNt5uV.js → en-C1UkXkY6.js} +25 -5
  15. package/dist/client/bundle/{es-pnWdszTE.js → es-DrTXrvU-.js} +25 -5
  16. package/dist/client/bundle/{format-C7qb6Cn-.js → format-COWnO8aN.js} +1 -1
  17. package/dist/client/bundle/{fr-CY8q9pj4.js → fr-DSvgQnax.js} +25 -5
  18. package/dist/client/bundle/{main-DktU0GfB.js → main-CjRdSA5N.js} +2 -2
  19. package/dist/client/bundle/{ptypane-NIZ2Y8QM.js → ptypane-BU6MDOyh.js} +1 -1
  20. package/dist/client/bundle/{room-name-CFJfHE5L.js → room-name-DefEKN7q.js} +1 -1
  21. package/dist/client/bundle/{simulator-BnBPS_Ws.js → simulator-BhSq5TwZ.js} +1 -1
  22. package/dist/client/bundle/world-model-D6tSJZPE.js +1 -0
  23. package/dist/client/bundle/{world-stream-BRkL9Eme.js → world-stream-pGb-glkT.js} +1 -1
  24. package/dist/client/index.html +1 -1
  25. package/dist/server/index.js +1030 -450
  26. package/mod/README.md +144 -144
  27. package/mod/habblaud/.claude-plugin/plugin.json +1 -1
  28. package/mod/habblaud-mensagens/.claude-plugin/plugin.json +1 -1
  29. package/mod/habblaud-permissoes/.claude-plugin/plugin.json +1 -1
  30. package/mod/habblaud-pi/package.json +1 -1
  31. package/package.json +7 -2
  32. package/dist/client/bundle/app-AwZeKIeu.js +0 -24
  33. package/dist/client/bundle/city-YoIG0FsX.js +0 -1
  34. package/dist/client/bundle/world-model-BIYmgAWC.js +0 -1
package/mod/README.md CHANGED
@@ -1,43 +1,43 @@
1
- # Plugins do Claude Code do Busybits
2
-
3
- O repositório é também um marketplace de plugins do Claude Code: `.claude-plugin/marketplace.json` (na raiz)
4
- lista o marketplace `habblaud` com três plugins, um em cada pasta daqui: o mod `busybits` (só observa; mora na pasta `mod/habblaud`),
5
- `busybits-permissions` (responder permissões pelo escritório) e `busybits-messages` (mandar mensagens pelo
6
- escritório). O `npm run mod:install` instala os três; `--sem-permissoes` e `--sem-mensagens` deixam o seu de fora.
7
- As versões acompanham o `package.json` (o teste `server/test/mod.test.ts` falha se divergirem).
8
-
9
- Testado com o **Claude Code 2.1.293** (o `busybits-messages`, por enquanto só pelo `claude plugin test` do
10
- 2.1.295). Mods (hooks em TypeScript carregados pelo próprio Claude Code) existem a partir da 2.1.287; a API ainda é
11
- "early access" e pode mudar entre versões. Em versões anteriores, use os instaladores de sempre
12
- (`npm run usage:install` e `npm run hooks:install`); mandar mensagens pelo escritório só existe com o mod. A
13
- instalação está no README principal.
14
-
15
- ## `busybits` — o mod
16
-
17
- `habblaud/hooks/register.ts`, um módulo só, sem build. Liga cada sessão ao escritório sem ler a conversa:
18
-
19
- - **Uso do plano (5h e semanal):** no início da sessão e a cada `session.measure` (depois de cada turno e quando
20
- um limite anda um ponto) lê `$.session.usage().rateLimits` e grava `~/.habblaud/usage/<conta>.json` (ou em
21
- `HABBLAUD_USAGE_DIR`) no mesmo formato do tap de statusline, mais `"source": "mod"`. Substitui o
22
- `npm run usage:install`: o seu statusline fica intocado. A conta é a pasta de `CLAUDE_CONFIG_DIR` (o primeiro
23
- item) ou `~/.claude` (`~` é o `HOME`; no Windows sem ele, o `USERPROFILE`). Valores iguais gravados há menos de
24
- 10 s não são regravados; falha ao gravar = silêncio.
25
- - **"Precisa de você" embaixo do prompt:** a cada 5 s pergunta ao Busybits local
26
- (`GET http://127.0.0.1:<HABBLAUD_PORT ou 4747>/api/mod/summary`) quem está esperando, já sem esta sessão e os
27
- subagentes dela, e mostra `🏢 Valentina precisa de você em loja-virtual` ou
28
- `🏢 2 precisam de você: Valentina (loja-virtual), Elias (app-mobile)` (até 3 nomes, depois "e mais N").
29
- Ninguém esperando ou Busybits fora do ar: a linha some; fora do ar, as perguntas passam a ser a cada 30 s até
30
- ele voltar. Só em sessões que desenham (no `claude -p` não pergunta nada).
31
- - **`/busybits`:** resumo do escritório inteiro, respondido pelo próprio mod (não chama o modelo, não gasta uso):
1
+ # Busybits plugins for Claude Code
2
+
3
+ The repository is also a Claude Code plugin marketplace: `.claude-plugin/marketplace.json` (at the root)
4
+ lists the `busybits` marketplace with three plugins, each in a folder here: the `busybits` mod (observe-only; it lives in the `mod/habblaud` folder),
5
+ `busybits-permissions` (answer permission requests from the office; `mod/habblaud-permissoes`) and `busybits-messages` (send messages from the
6
+ office; `mod/habblaud-mensagens`). `npm run mod:install` installs all three; `--sem-permissoes` and `--sem-mensagens` leave theirs out.
7
+ Versions follow `package.json` (the test `server/test/mod.test.ts` fails if they diverge).
8
+
9
+ Tested with **Claude Code 2.1.293** (`busybits-messages`, for now only through `claude plugin test` on
10
+ 2.1.295). Mods (TypeScript hooks loaded by Claude Code itself) exist from 2.1.287 on; the API is still
11
+ "early access" and may change between versions. On older versions, use the usual installers
12
+ (`npm run usage:install` and `npm run hooks:install`); sending messages from the office only exists with the mod.
13
+ Installation is covered in the main README.
14
+
15
+ ## `busybits` — the mod
16
+
17
+ `habblaud/hooks/register.ts`, a single module, no build. It connects each session to the office without reading the conversation:
18
+
19
+ - **Plan usage (5h and weekly):** at session start and on every `session.measure` (after each turn and when
20
+ a limit moves by a point) it reads `$.session.usage().rateLimits` and writes `~/.habblaud/usage/<account>.json` (or to
21
+ `HABBLAUD_USAGE_DIR`) in the same format as the statusline tap, plus `"source": "mod"`. It replaces
22
+ `npm run usage:install`: your statusline is left untouched. The account is the `CLAUDE_CONFIG_DIR` folder (the first
23
+ item) or `~/.claude` (`~` is `HOME`; on Windows without it, `USERPROFILE`). Identical values written less than
24
+ 10 s ago are not rewritten; a write failure is silent.
25
+ - **"Needs you" under the prompt:** every 5 s it asks the local Busybits
26
+ (`GET http://127.0.0.1:<HABBLAUD_PORT or 4747>/api/mod/summary`) who is waiting, already excluding this session and its
27
+ subagents, and shows `🏢 Valentina needs you in loja-virtual` or
28
+ `🏢 2 need you: Valentina (loja-virtual), Elias (app-mobile)` (up to 3 names, then "and N more").
29
+ Nobody waiting or Busybits down: the line disappears; while it is down, the polling drops to every 30 s until
30
+ it is back. Only in sessions that draw a UI (`claude -p` asks nothing).
31
+ - **`/busybits`:** a summary of the whole office, answered by the mod itself (it does not call the model and spends no usage):
32
32
 
33
33
  ```
34
- Busybits 0.3.0 em http://localhost:4747
35
- 7 agentes · 3 trabalhando · 2 precisam de você
36
- ✋ Valentina (loja-virtual): aprovar uma permissão · dá para responder pelo escritório
37
- ✋ Elias (app-mobile): responder no terminal
34
+ Busybits 2.0.1 at http://localhost:4747
35
+ 7 agents · 3 working · 2 need you
36
+ ✋ Valentina (loja-virtual): approve a permission · you can answer from the office
37
+ ✋ Elias (app-mobile): answer in the terminal
38
38
  ```
39
39
 
40
- Fora do ar: `O Busybits não respondeu em http://localhost:4747. Para subir: npm run docker:up na pasta do Busybits.`
40
+ When Busybits is down: `Busybits did not answer at http://localhost:4747. To start it: npm run docker:up in the Busybits folder.`
41
41
 
42
42
  ### Language
43
43
 
@@ -54,10 +54,10 @@ The plugin id is now `busybits@busybits`, in a marketplace named `busybits` (it
54
54
  removes every `*@habblaud` plugin and the `habblaud` marketplace in each account before adding `busybits`, and
55
55
  `npm run mod:uninstall` removes both generations. A packaged install (`busybits setup`) does the same switch, pointing the marketplace at `~/.busybits/marketplace`; until then `npm run mod:status` and `docker:up` report the old name.
56
56
 
57
- ### O que ele acessa
57
+ ### What it accesses
58
58
 
59
- Saída de `claude plugin validate --strict mod/habblaud` (a análise estática que o Claude Code faz antes de
60
- carregar o módulo; nada fora desta lista é chamado):
59
+ Output of `claude plugin validate --strict mod/habblaud` (the static analysis Claude Code runs before
60
+ loading the module; nothing outside this list is called):
61
61
 
62
62
  ```
63
63
  ❯ ./register.ts hooks: session.start, session.measure, command.run{command=busybits}
@@ -67,68 +67,68 @@ carregar o módulo; nada fora desta lista é chamado):
67
67
  ❯ ./register.ts env reads: CLAUDE_CONFIG_DIR, HABBLAUD_LANG, HABBLAUD_PORT, HABBLAUD_USAGE_DIR, HOME, LANG, LANGUAGE, LC_ALL, LC_MESSAGES, USERPROFILE
68
68
  ```
69
69
 
70
- Em palavras: só observa (nenhum hook decide nada: não aprova ferramentas, não muda prompts, não lê mensagens),
71
- grava um único arquivo (o de uso), fala só com `127.0.0.1` e lê dez variáveis de ambiente. `$.clock.after` é o
72
- prazo de 2 s de cada pergunta ao Busybits (`$.http.fetch` não aceita AbortSignal).
70
+ In plain words: it only observes (no hook decides anything: it does not approve tools, change prompts or read messages),
71
+ writes a single file (the usage one), talks only to `127.0.0.1` and reads ten environment variables. `$.clock.after` is the
72
+ 2 s deadline of each question to Busybits (`$.http.fetch` does not accept an AbortSignal).
73
73
 
74
- ## `busybits-permissions` — responder permissões pelo escritório
74
+ ## `busybits-permissions` — answer permissions from the office
75
75
 
76
- Um hook `PermissionRequest` comum (sem mod), em `habblaud-permissoes/hooks/hooks.json`:
76
+ A regular `PermissionRequest` hook (no mod), in `habblaud-permissoes/hooks/hooks.json`:
77
77
 
78
78
  ```json
79
79
  { "matcher": "*", "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/permission-hook.mjs\"", "timeout": 86430, "statusMessage": "Aguardando resposta no Busybits" }] }
80
80
  ```
81
81
 
82
- O script `hooks/permission-hook.mjs` é o mesmo que o `npm run hooks:install` instala (fonte única; Node puro, só
83
- `node:*`, porque o Claude Code copia apenas a pasta do plugin para o cache). Ele manda o pedido ao Busybits local
84
- e espera a resposta por até 5 min; o diálogo continua no terminal e vale o que você responder primeiro. Sem o
85
- Busybits no ar ou sem nenhuma página aberta, sai na hora. Porta: `HABBLAUD_PORT` (padrão 4747); espera:
86
- `HABBLAUD_PERMISSION_TIMEOUT` (padrão 300 s, até 86400 s = 24 h; o tempo limite do hook no plugin é 86430 s). Para aprovar
87
- pelo celular longe do computador, ponha `"env": { "HABBLAUD_PERMISSION_TIMEOUT": "86400" }` no `settings.json` da
88
- conta: vale para as sessões abertas depois. Subagentes em segundo plano só mostram o diálogo quando o hook termina,
89
- por isso o padrão continua 5 min. Precisa de `node` 22+ no `PATH` da sessão.
90
-
91
- `claude plugin validate --strict mod/habblaud-permissoes`: `✔ Validation passed` (o validador também confere o
92
- esquema do `hooks.json`).
93
-
94
- ## `busybits-messages` — mensagens pelo escritório
95
-
96
- `habblaud-mensagens/hooks/register.ts`, um módulo só, sem build. Leva para a sessão o que você digita no escritório
97
- (no painel do agente ou no terminal da tecla T), como se você tivesse digitado no terminal:
98
-
99
- - **Busca:** a cada 2 s, só em sessões que desenham (no `claude -p` não pergunta nada),
100
- `POST http://127.0.0.1:<HABBLAUD_PORT ou 4747>/api/mod/inbox` com `{session, account}`. A pergunta também marca a
101
- sessão como presente: é ela que mostra, na página, a caixa de mensagem do agente (sem o plugin, a página dá a dica
102
- de instalar). Fora do ar, ou respondendo outra coisa (403 com as mensagens desligadas, 404 numa versão sem a
103
- rota), passa a perguntar a cada 30 s até ele voltar.
104
- - **Entrega:** cada mensagem, na ordem, vai por `$.prompt.submit({ text, asUser: true })`. O modelo lê o texto como
105
- seu, sem o "The busybits-messages plugin sent a message" (o registro da sessão ainda diz que veio do plugin), e o
106
- texto vai exatamente como foi digitado. Com a sessão no meio de um turno, o Claude Code guarda o prompt e o roda
107
- num turno só dele quando o atual terminar (um prompt de plugin nunca entra no meio do turno, como um digitado
108
- pode entrar). Um hook que recuse a mensagem (`{drop}`) ou uma exceção viram falha, com o motivo, na página.
109
- - **Comandos de barra:** a mensagem que começa por `/nome argumentos`, com `nome` na lista de `$.command.list()`,
110
- roda por `$.command.run({ command, args })` em vez de `$.prompt.submit` (o Claude Code recusa em `$.prompt.submit`
111
- todo texto que comece por `/`), e o desfecho (ok ou o erro) segue na confirmação. Com a lista fora do ar, quem
112
- decide é o `$.command.run`, que rejeita nome desconhecido. Texto que começa por `/` e não é comando da sessão
113
- (`/etc/hosts`, erro de digitação) falha com o motivo, sem ir à sessão. A mesma lista vai ao Busybits em
114
- `POST /api/mod/commands` com `{session, account, commands: [{name, description, source, plugin?}]}`, só quando muda
115
- e de minuto em minuto (o Busybits pode ter reiniciado): é ela que alimenta o autocompletar da caixa. Comandos que
116
- abrem um menu interativo (`/model` sem argumento, `/config`) não têm o que mostrar no escritório: dê argumentos ou
117
- use o terminal. O texto que o comando imprime não volta para a página.
118
- - **Confirmação:** um `POST /api/mod/inbox/ack` com o resultado de cada uma (`{session, results: [{id, ok, error?}]}`).
119
- A espera por mensagem (ou comando) é de no máximo 2 s: passou disso, a sessão está ocupada, a mensagem está na fila dela e
120
- conta como entregue (as seguintes vão em seguida, na ordem). Assim uma rodada nunca passa de uns poucos segundos e
121
- a presença (10 s) e a confirmação (30 s) do servidor não vencem com a sessão ocupada; o preço é que uma recusa
122
- depois desses 2 s não chega à página.
123
-
124
- Fica separado do mod `habblaud` de propósito: aquele só observa; este age, digitando na sessão em seu nome. Para
125
- ficar sem ele: `npm run mod:install -- --sem-mensagens` (um já instalado continua; para tirar:
126
- `claude plugin uninstall busybits-messages@busybits`). O `npm run docker:up` atualiza o plugin de quem já o tem,
127
- mas não o instala sozinho: numa conta com o mod e sem ele, só dá a dica de rodar o `npm run mod:install`.
128
-
129
- ### O que ele acessa
130
-
131
- Saída de `claude plugin validate --strict mod/habblaud-mensagens`:
82
+ The `hooks/permission-hook.mjs` script is the same one `npm run hooks:install` installs (single source; plain Node, only
83
+ `node:*`, because Claude Code copies only the plugin folder into its cache). It sends the request to the local Busybits
84
+ and waits for the answer for up to 5 min; the dialog stays in the terminal and whatever you answer first wins. Without
85
+ Busybits running, or without any open page, it exits immediately. Port: `HABBLAUD_PORT` (default 4747); wait:
86
+ `HABBLAUD_PERMISSION_TIMEOUT` (default 300 s, up to 86400 s = 24 h; the hook timeout in the plugin is 86430 s). To approve
87
+ from your phone while away from the computer, put `"env": { "HABBLAUD_PERMISSION_TIMEOUT": "86400" }` in the account's
88
+ `settings.json`: it applies to sessions opened afterwards. Background subagents only show the dialog once the hook finishes,
89
+ which is why the default stays at 5 min. Requires `node` 22+ on the session's `PATH`.
90
+
91
+ `claude plugin validate --strict mod/habblaud-permissoes`: `✔ Validation passed` (the validator also checks the
92
+ `hooks.json` schema).
93
+
94
+ ## `busybits-messages` — messages from the office
95
+
96
+ `habblaud-mensagens/hooks/register.ts`, a single module, no build. It brings into the session what you type in the office
97
+ (in the agent panel or in the terminal opened with the T key), as if you had typed it in the terminal:
98
+
99
+ - **Polling:** every 2 s, only in sessions that draw a UI (`claude -p` asks nothing),
100
+ `POST http://127.0.0.1:<HABBLAUD_PORT or 4747>/api/mod/inbox` with `{session, account}`. The request also marks the
101
+ session as present: that is what shows the agent's message box on the page (without the plugin, the page shows a hint
102
+ to install it). When Busybits is down, or answers something else (403 with messages turned off, 404 on a version without the
103
+ route), it polls every 30 s until it is back.
104
+ - **Delivery:** each message, in order, goes through `$.prompt.submit({ text, asUser: true })`. The model reads the text as
105
+ yours, without the "The busybits-messages plugin sent a message" prefix (the session log still says it came from the plugin), and the
106
+ text goes exactly as typed. If the session is in the middle of a turn, Claude Code holds the prompt and runs it
107
+ in a turn of its own when the current one ends (a plugin prompt never enters mid-turn, the way a typed one
108
+ can). A hook that refuses the message (`{drop}`) or an exception becomes a failure, with the reason, on the page.
109
+ - **Slash commands:** a message that starts with `/name arguments`, with `name` in the `$.command.list()` list,
110
+ runs through `$.command.run({ command, args })` instead of `$.prompt.submit` (Claude Code refuses any text that starts with `/`
111
+ in `$.prompt.submit`), and the outcome (ok or the error) follows in the acknowledgement. With the list unavailable, the decision is
112
+ left to `$.command.run`, which rejects unknown names. Text that starts with `/` and is not a session command
113
+ (`/etc/hosts`, a typo) fails with the reason, without reaching the session. The same list goes to Busybits in
114
+ `POST /api/mod/commands` with `{session, account, commands: [{name, description, source, plugin?}]}`, only when it changes
115
+ and once a minute (Busybits may have restarted): it feeds the box's autocomplete. Commands that
116
+ open an interactive menu (`/model` without an argument, `/config`) have nothing to show in the office: pass arguments or
117
+ use the terminal. The text the command prints does not come back to the page.
118
+ - **Acknowledgement:** a `POST /api/mod/inbox/ack` with the result of each one (`{session, results: [{id, ok, error?}]}`).
119
+ Waiting for a message (or command) takes at most 2 s: past that, the session is busy, the message is in its queue and
120
+ counts as delivered (the following ones go right after, in order). This way a round never takes more than a few seconds and
121
+ the server's presence (10 s) and confirmation (30 s) windows do not expire while the session is busy; the price is that a refusal
122
+ after those 2 s does not reach the page.
123
+
124
+ It is kept separate from the `busybits` mod on purpose: that one only observes; this one acts, typing into the session on your behalf. To
125
+ go without it: `npm run mod:install -- --sem-mensagens` (one already installed stays; to remove it:
126
+ `claude plugin uninstall busybits-messages@busybits`). `npm run docker:up` updates the plugin for accounts that already have it,
127
+ but does not install it by itself: on an account with the mod and without it, it only hints to run `npm run mod:install`.
128
+
129
+ ### What it accesses
130
+
131
+ Output of `claude plugin validate --strict mod/habblaud-mensagens`:
132
132
 
133
133
  ```
134
134
  ❯ ./register.ts hooks: session.start
@@ -137,57 +137,57 @@ Saída de `claude plugin validate --strict mod/habblaud-mensagens`:
137
137
  ❯ ./register.ts env reads: CLAUDE_CODE_ENTRYPOINT, CLAUDE_CONFIG_DIR, HABBLAUD_PORT, HOME, USERPROFILE
138
138
  ```
139
139
 
140
- Em palavras: um hook só (`session.start`, que liga o relógio das rodadas); as únicas ações na sessão são o
141
- `$.prompt.submit` das mensagens e o `$.command.run` dos comandos de barra que você manda (`$.command.list` só lê os
142
- nomes e as descrições dos comandos para publicá-los); não lê a conversa, não grava arquivo nenhum, fala só com `127.0.0.1` e lê quatro
143
- variáveis de ambiente (a conta sai do `CLAUDE_CONFIG_DIR`, como no mod). `$.clock.after` é o prazo de 2 s de cada
144
- pedido ao Busybits, de cada `$.prompt.submit`, `$.command.run` e `$.command.list`.
145
-
146
- Porta: `HABBLAUD_PORT` (padrão 4747). Precisa do Claude Code 2.1.287+ e de um Busybits com as mensagens ligadas: a
147
- mesma trava do terminal e das permissões (porta presa ao `127.0.0.1` e cabeçalho Host local) e `HABBLAUD_MENSAGENS`
148
- não desligado (`0`, `false`, `off` ou `no` desligam). Qualquer processo desta máquina que fale com o Busybits
149
- consegue mandar uma mensagem às sessões com o plugin: por isso a trava local.
150
-
151
- ## `habblaud-pi` — Gentle Shell e Pi
152
-
153
- Não é um plugin do Claude Code: é uma extensão do Pi (`habblaud-pi/extension.ts`, TypeScript carregado pelo próprio Pi, sem
154
- build; a lógica testável está em `core.ts`, sem dependência do Pi). Instalação: `npm run pi:install` (ou `npm run setup`),
155
- que põe a pasta `mod/habblaud-pi` em `packages` do `settings.json` de `~/.gentle-shell/agent` e de `~/.pi/agent`
156
- (o que o `pi install <pasta>` faz; com backup, idempotente, sem tocar em `auth.json` nem em `mcp*.json`);
157
- `npm run pi:status` e `npm run pi:uninstall` completam. Sessões abertas precisam ser reabertas (ou `/reload` no Pi).
158
-
159
- - **Mensagens:** o mesmo protocolo do `busybits-messages` (`/api/mod/inbox`, `/ack` e `/commands`), só em sessões com tela
160
- (`ctx.mode === "tui"`; subagentes, `-p` e RPC não buscam nada). Entrega com `pi.sendUserMessage`: a sessão ociosa recebe
161
- na hora e, no meio de um turno, a mensagem entra como `followUp`. `/comando` da lista de `pi.getCommands()` (extensões,
162
- prompt templates e skills) roda com `expandPromptTemplates`; o resto de `/...` falha com o motivo (os comandos embutidos
163
- do Pi só rodam no terminal).
164
- - **Precisa de você:** o Pi emite `ui_prompt_start` / `ui_prompt_end` (tipo e título) quando uma extensão abre uma caixa
165
- bloqueante. O guard do gentle-pi pergunta com `ctx.ui.confirm("Allow guarded git push?", <prévia do comando>)`
166
- (`extensions/gentle-ai.ts`, `confirmCommand`) e emite também `pi-permission-system:permission-request` (sem o
167
- comando). Com o agente trabalhando, a extensão avisa o Busybits (`POST /api/permissions` com `answerable: false`, o
168
- comando vindo da chamada de ferramenta em aberto) e libera o aviso quando a caixa fecha.
169
- **Responder pelo escritório não é possível com segurança:** os eventos só observam, o `confirm` é resolvido pela
170
- interface do terminal e o Pi não expõe como responder a caixa de outra extensão; a única saída seria substituir o
171
- `ctx.ui.confirm` por dentro, o que muda a semântica do guard (a decisão sairia de outro lugar que não a caixa do
172
- terminal). Por isso o escritório mostra que o agente espera, com o comando, e a resposta continua no terminal.
173
- - **O que acessa:** `127.0.0.1:<HABBLAUD_PORT ou 4747>` (nenhum outro destino), as variáveis `HABBLAUD_PORT`, `HABBLAUD_PI`
174
- (`0`, `false`, `off` ou `no` desligam) e `GENTLE_PI_AGENTS_CHILD`; não lê a conversa, não grava arquivo, não bloqueia nem
175
- decide nenhuma chamada de ferramenta (o handler de `tool_call` só observa).
176
- - Testes: `server/sources/gentle-shell/pi-extension.test.ts` (núcleo e extensão contra o Busybits de verdade, com um Pi
177
- falso), `pi-install.test.ts` e `setup.test.ts` (HOME falso).
178
-
179
- ## Desenvolver
140
+ In plain words: a single hook (`session.start`, which starts the round clock); the only actions on the session are
141
+ `$.prompt.submit` for messages and `$.command.run` for the slash commands you send (`$.command.list` only reads the
142
+ command names and descriptions to publish them); it does not read the conversation, does not write any file, talks only to `127.0.0.1` and reads four
143
+ environment variables (the account comes from `CLAUDE_CONFIG_DIR`, as in the mod). `$.clock.after` is the 2 s deadline of each
144
+ request to Busybits, and of each `$.prompt.submit`, `$.command.run` and `$.command.list`.
145
+
146
+ Port: `HABBLAUD_PORT` (default 4747). Requires Claude Code 2.1.287+ and a Busybits with messages turned on: the
147
+ same lock as the terminal and permissions (port bound to `127.0.0.1` and a local Host header) and `HABBLAUD_MENSAGENS`
148
+ not turned off (`0`, `false`, `off` or `no` turn it off). Any process on this machine that talks to Busybits
149
+ can send a message to the sessions that have the plugin: that is why the lock is local.
150
+
151
+ ## `habblaud-pi` — Gentle Shell and Pi
152
+
153
+ Not a Claude Code plugin: it is a Pi extension (`habblaud-pi/extension.ts`, TypeScript loaded by Pi itself, no
154
+ build; the testable logic is in `core.ts`, with no Pi dependency). Installation: `npm run pi:install` (or `npm run setup`),
155
+ which adds the `mod/habblaud-pi` folder to `packages` in the `settings.json` of `~/.gentle-shell/agent` and of `~/.pi/agent`
156
+ (what `pi install <folder>` does; with a backup, idempotent, without touching `auth.json` or `mcp*.json`);
157
+ `npm run pi:status` and `npm run pi:uninstall` complete the set. Open sessions must be reopened (or run `/reload` in Pi).
158
+
159
+ - **Messages:** the same protocol as `busybits-messages` (`/api/mod/inbox`, `/ack` and `/commands`), only in sessions with a UI
160
+ (`ctx.mode === "tui"`; subagents, `-p` and RPC fetch nothing). Delivery uses `pi.sendUserMessage`: an idle session receives
161
+ it right away and, in the middle of a turn, the message enters as a `followUp`. A `/command` from the `pi.getCommands()` list (extensions,
162
+ prompt templates and skills) runs with `expandPromptTemplates`; any other `/...` fails with the reason (Pi's built-in commands
163
+ only run in the terminal).
164
+ - **Needs you:** Pi emits `ui_prompt_start` / `ui_prompt_end` (type and title) when an extension opens a blocking
165
+ box. The gentle-pi guard asks with `ctx.ui.confirm("Allow guarded git push?", <command preview>)`
166
+ (`extensions/gentle-ai.ts`, `confirmCommand`) and also emits `pi-permission-system:permission-request` (without the
167
+ command). While the agent is working, the extension tells Busybits (`POST /api/permissions` with `answerable: false`, the
168
+ command taken from the open tool call) and releases the notice when the box closes.
169
+ **Answering from the office is not possible safely:** the events only observe, `confirm` is resolved by the
170
+ terminal UI and Pi does not expose a way to answer another extension's box; the only way out would be to replace
171
+ `ctx.ui.confirm` from the inside, which changes the guard's semantics (the decision would come from somewhere other than the
172
+ terminal box). That is why the office shows that the agent is waiting, with the command, and the answer stays in the terminal.
173
+ - **What it accesses:** `127.0.0.1:<HABBLAUD_PORT or 4747>` (no other destination), the variables `HABBLAUD_PORT`, `HABBLAUD_PI`
174
+ (`0`, `false`, `off` or `no` turn it off) and `GENTLE_PI_AGENTS_CHILD`; it does not read the conversation, does not write files, and does not block or
175
+ decide any tool call (the `tool_call` handler only observes).
176
+ - Tests: `server/sources/gentle-shell/pi-extension.test.ts` (core and extension against a real Busybits, with a fake
177
+ Pi), `pi-install.test.ts` and `setup.test.ts` (fake HOME).
178
+
179
+ ## Development
180
180
 
181
181
  ```bash
182
- claude --plugin-dir mod/habblaud # carrega o mod numa sessão, sem instalar (recarrega ao salvar)
183
- claude -p "/busybits" --plugin-dir mod/habblaud # testa o comando sem sessão interativa (não chama o modelo)
184
- cd mod/habblaud && claude plugin test # testes do mod (tests/*.test.ts), sem sessão, login nem rede
185
- cd mod/habblaud-mensagens && claude plugin test # idem para o plugin de mensagens
186
- claude plugin validate --strict mod/habblaud # análise estática + manifesto (idem para as outras pastas e .)
187
- npx tsc -p mod/habblaud # tipos (depois de carregar o mod uma vez com --plugin-dir)
182
+ claude --plugin-dir mod/habblaud # loads the mod in a session, without installing (reloads on save)
183
+ claude -p "/busybits" --plugin-dir mod/habblaud # tests the command without an interactive session (does not call the model)
184
+ cd mod/habblaud && claude plugin test # mod tests (tests/*.test.ts), no session, login or network
185
+ cd mod/habblaud-mensagens && claude plugin test # same for the messages plugin
186
+ claude plugin validate --strict mod/habblaud # static analysis + manifest (same for the other folders and .)
187
+ npx tsc -p mod/habblaud # types (after loading the mod once with --plugin-dir)
188
188
  ```
189
189
 
190
- Ao carregar um mod, o Claude Code grava os tipos da versão instalada em `<pasta>/.claude-plugin/types/` e um
191
- `<pasta>/tsconfig.json` que os estende; os dois são gerados e ficam fora do git (`mod/.gitignore`). Os testes dos
192
- mods importam `claude-code/testing` e só rodam pelo `claude plugin test`: o `npm test` (vitest) e o
193
- `npm run typecheck` não olham esta pasta.
190
+ When loading a mod, Claude Code writes the types of the installed version to `<folder>/.claude-plugin/types/` and a
191
+ `<folder>/tsconfig.json` that extends them; both are generated and kept out of git (`mod/.gitignore`). The mod tests
192
+ import `claude-code/testing` and only run through `claude plugin test`: `npm test` (vitest) and
193
+ `npm run typecheck` do not look at this folder.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "busybits",
3
3
  "displayName": "Busybits",
4
- "version": "2.0.0",
4
+ "version": "2.1.0",
5
5
  "description": "Connects the session to Busybits: records plan usage (5h and weekly) for the office, shows a line under the prompt when another session needs you, and adds the /busybits command.",
6
6
  "author": { "name": "Márcio Junior", "url": "https://github.com/marmottajr" },
7
7
  "homepage": "https://github.com/marmottajr/habblaud#readme",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "busybits-messages",
3
3
  "displayName": "Busybits: messages from the office",
4
- "version": "2.0.0",
4
+ "version": "2.1.0",
5
5
  "description": "Delivers to the Claude Code session the messages you type in Busybits (agent panel or terminal), as if you had typed them in the terminal.",
6
6
  "author": { "name": "Márcio Junior", "url": "https://github.com/marmottajr" },
7
7
  "homepage": "https://github.com/marmottajr/habblaud#readme",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "busybits-permissions",
3
3
  "displayName": "Busybits: permissions from the office",
4
- "version": "2.0.0",
4
+ "version": "2.1.0",
5
5
  "description": "PermissionRequest hook that lets you approve or deny Claude Code permission requests and answer AskUserQuestion prompts from Busybits; the dialog stays in the terminal and whichever answer comes first wins.",
6
6
  "author": { "name": "Márcio Junior", "url": "https://github.com/marmottajr" },
7
7
  "homepage": "https://github.com/marmottajr/habblaud#readme",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "habblaud-pi",
3
- "version": "2.0.0",
3
+ "version": "2.1.0",
4
4
  "private": true,
5
5
  "description": "Extensão do Pi / Gentle Shell para o Habblaud: recebe as mensagens do escritório e mostra quando o agente precisa de você.",
6
6
  "license": "MIT",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "busybits",
3
- "version": "2.0.0",
3
+ "version": "2.1.0",
4
4
  "description": "Animated pixel-art office that shows what your Claude Code, Codex and Pi agents are doing, live.",
5
5
  "license": "MIT",
6
6
  "bin": {
@@ -57,6 +57,7 @@
57
57
  "mod:install": "tsx scripts/mod-install.ts install",
58
58
  "mod:uninstall": "tsx scripts/mod-install.ts uninstall",
59
59
  "mod:status": "tsx scripts/mod-install.ts status",
60
+ "post": "tsx scripts/post.ts",
60
61
  "satellite:pair": "tsx scripts/satellite-pair.ts",
61
62
  "codex:install": "tsx scripts/codex-install.ts install",
62
63
  "codex:uninstall": "tsx scripts/codex-install.ts uninstall",
@@ -73,9 +74,12 @@
73
74
  "version": "node scripts/sync-version.mjs && git add .claude-plugin/marketplace.json mod/*/.claude-plugin/plugin.json mod/habblaud-pi/package.json",
74
75
  "version:check": "node scripts/sync-version.mjs --check",
75
76
  "pack:check": "node scripts/check-pack.mjs",
76
- "release": "tsx scripts/release.ts"
77
+ "release": "tsx scripts/release.ts",
78
+ "prepare": "husky || true"
77
79
  },
78
80
  "devDependencies": {
81
+ "@commitlint/cli": "21.2.4",
82
+ "@commitlint/config-conventional": "21.2.4",
79
83
  "@fontsource/pixelify-sans": "^5.3.0",
80
84
  "@storybook/addon-docs": "^10.6.7",
81
85
  "@storybook/html-vite": "^10.6.7",
@@ -83,6 +87,7 @@
83
87
  "@xterm/addon-fit": "^0.11.0",
84
88
  "@xterm/xterm": "^6.0.0",
85
89
  "esbuild": "^0.28.2",
90
+ "husky": "9.1.7",
86
91
  "playwright-core": "^1.64.0",
87
92
  "storybook": "^10.6.7",
88
93
  "tsx": "^4.23.15",