@gwro/codeaside 0.0.0-stage → 0.1.1

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.
@@ -0,0 +1,60 @@
1
+ # Privacy policy
2
+
3
+ Last updated: 19 November 2026
4
+
5
+ CodeAside is made of two parts: the codeaside hub, which you install and run on
6
+ your own PC, and the CodeAside app for Even Realities G2 glasses. This policy covers both, for this fork. Upstream's GlanceCode has
7
+ [its own](https://github.com/sousyllc/glancecode/blob/main/docs/privacy.md).
8
+
9
+ ## What the app handles
10
+
11
+ - **Session content.** The app shows your Claude Code sessions: prompts, replies,
12
+ tool calls and status. It fetches them from the hub on your PC and keeps them in
13
+ memory only while the app is open.
14
+ - **Voice.** When you hold to talk, audio from the glasses microphone is sent to
15
+ the hub on your PC, which turns it into text with a speech model running
16
+ locally. Audio isn't stored and isn't sent to any other service.
17
+ - **Pairing details.** The hub address and pairing token are saved in the Even
18
+ Realities app's storage for this app, so you don't have to pair again.
19
+
20
+ ## What the hub reads on your PC
21
+
22
+ - **Transcripts.** Claude Code's own session files, to show a session's history
23
+ and follow it live.
24
+ - **Hooks.** Claude Code tells the hub when a session starts, works, asks for
25
+ something or stops.
26
+ - **The terminal screen** of sessions started with `codeaside claude`: to read
27
+ the options of an approval or a question before pressing a key, and to find the
28
+ next prompt Claude Code suggests in its input box. Set `showSuggestions` to
29
+ `false` to stop the hub looking for suggestions.
30
+
31
+ The hub keeps what it needs to list your sessions again after a restart in
32
+ `%APPDATA%\codeaside\sessions.json`: their ids, folders and transcript paths, not
33
+ their content. Its log, `%LOCALAPPDATA%\codeaside\logs\hub.log`, records the
34
+ prompts sent from the glasses and what your voice was transcribed as.
35
+
36
+ ## Where data goes
37
+
38
+ The app connects only to the hub address you paired with, over your own Tailscale
39
+ network. CodeAside has no servers, accounts, analytics or tracking, and the
40
+ developers never receive your data.
41
+
42
+ The hub works with Claude Code on your PC. What Claude Code sends to Anthropic is
43
+ covered by your agreement with Anthropic, not by this policy.
44
+
45
+ If you turn on the optional phone notifications (`ntfyTopic`), the hub sends the
46
+ project name and up to 180 characters of text to the ntfy server you configure:
47
+ the start of Claude's last reply when a session finishes, or what it is asking to
48
+ do when it needs you. Anyone who knows the topic name can read them.
49
+
50
+ ## Removing your data
51
+
52
+ Choose "Forget this hub" in the app and uninstall the app. On the PC, remove the
53
+ hub with `codeaside service uninstall` and `codeaside uninstall`, and
54
+ `npm uninstall -g @gwro/codeaside` if you installed the command globally.
55
+ Configuration lives in `%APPDATA%\codeaside`, and the speech model, whisper.cpp and
56
+ the logs in `%LOCALAPPDATA%\codeaside`; delete both folders to remove everything.
57
+
58
+ ## Contact
59
+
60
+ Open an issue at https://github.com/gwro/CodeAside/issues.
@@ -0,0 +1,532 @@
1
+ # CodeAside: design of the Windows port
2
+
3
+ This fork makes GlanceCode run natively on Windows: no WSL, no tmux, no Git Bash
4
+ needed at runtime. The glasses app is untouched. The first version follows Claude
5
+ Code only; Codex and Gemini CLI are out of scope, but the seams upstream uses for
6
+ them are kept so they can come back later.
7
+
8
+ Status: all four milestones implemented, and the port has run on G2 glasses. Each
9
+ "What milestone N found" section at the end records what differed from this design.
10
+ The last section, "After the port", covers what changed once it was in use; in
11
+ particular, the glasses app is no longer untouched.
12
+
13
+ ## What stays the same
14
+
15
+ Everything the glasses see. The hub's HTTP API, the SSE event stream, the session
16
+ and item shapes, pairing (`https://<name>.ts.net:7443#<token>`) and the Even Hub
17
+ app are identical, so the store build of the glasses app pairs with a Windows hub
18
+ as it is. The parts of the hub that read Claude Code's transcripts
19
+ (`hub/transcript.mjs`), keep the session registry (`hub/sessions.mjs`) and serve
20
+ the API (`hub/server.mjs`) port with small edits, because they only read files and
21
+ listen on 127.0.0.1.
22
+
23
+ ## What has to change
24
+
25
+ Upstream leans on five Unix things. Each has a Windows replacement:
26
+
27
+ | Upstream (macOS/Linux) | Role | Windows |
28
+ |---|---|---|
29
+ | tmux server, `send-keys`, `capture-pane` | hold the Claude Code terminal, type into it, read its screen | a **session host**: a small Node process that runs Claude Code in a ConPTY pseudo-console, keeps a headless terminal screen for it, and exposes both over a named pipe |
30
+ | `bin/glancecode-hook` (bash + curl) | post hook events to the hub, tagged with `$TMUX_PANE` | a Node script run by Claude Code through PowerShell, tagged with the host session id from the environment |
31
+ | launchd / systemd user unit | run the hub at login, restart it | a Task Scheduler logon task with restart on failure, launched hidden |
32
+ | `tailscale serve` | HTTPS on the machine's `*.ts.net` name | the same command; Tailscale for Windows ships `tailscale.exe` |
33
+ | `brew install whisper-cpp` | local speech to text | `whisper-server.exe` from whisper.cpp's Windows release zip, downloaded by `setup-voice` next to the model |
34
+
35
+ Plus the usual portability: `~/.config` and `~/.local/share` become `%APPDATA%`
36
+ and `%LOCALAPPDATA%`, `/bin/sh -c command -v` becomes `where.exe`, `chmod 600` is
37
+ a no-op, and nothing assumes `/` as the path separator.
38
+
39
+ ## Architecture
40
+
41
+ ```
42
+ claude.exe (in ConPTY) ◀── keys ─── session host ◀── named pipe ──┬── codeaside claude / attach (your terminal)
43
+ │ screen bytes ─────────────▶ (headless xterm buffer) └── hub (127.0.0.1:7717)
44
+ │ ▲ ▲
45
+ └── hooks ── powershell ── node codeaside-hook.mjs ── POST 127.0.0.1:7718 │
46
+ transcript %USERPROFILE%\.claude\projects\<dir>\<id>.jsonl ── hub tails ┘
47
+ │
48
+ whisper-server.exe (127.0.0.1:7719) ◀── hub ◀── tailscale serve (HTTPS) ◀── Even app ◀── G2
49
+ ```
50
+
51
+ Three processes on the computer, all running as the signed-in user:
52
+
53
+ - **host**: the tmux replacement. Owns the Claude Code processes. Starts on
54
+ demand, exits when its last session ends. Deliberately tiny and rarely changed,
55
+ so hub upgrades and restarts never kill a running Claude session.
56
+ - **hub**: unchanged in role. Registry, transcript tailing, API, hook intake,
57
+ voice, notifications. Talks to the host over the pipe the way it talked to tmux
58
+ through `execFile("tmux", ...)`.
59
+ - **CLI** (`codeaside`): setup, doctor, service, serve, pair, and the terminal
60
+ client that attaches to a host session.
61
+
62
+ ## The session host
63
+
64
+ ### Why a host, and not something else
65
+
66
+ Options considered:
67
+
68
+ 1. **Drive Claude Code through its terminal, as upstream does.** Needs something
69
+ that owns the terminal and can type into it and read it back. On Windows that
70
+ is ConPTY, which is what Windows Terminal and VS Code use to run console
71
+ programs. This keeps the upstream model: one Claude process, visible in your
72
+ terminal, the glasses typing into the same session, dialogs confirmed on
73
+ screen before a key is pressed.
74
+ 2. **Drive Claude Code through an API instead of its UI.** Claude Code documents
75
+ no local protocol for sending prompts or answering permissions into a running
76
+ interactive session. Remote Control is outbound-only, `--input-format
77
+ stream-json` is for print mode, and cross-session messaging can hand an idle
78
+ session a prompt but "can't answer a pending permission prompt". Codex
79
+ upstream works this way because Codex has an app server its terminal UI also
80
+ uses; Claude Code has no public equivalent.
81
+ 3. **Send keystrokes to a Windows Terminal window** (SendInput, UI Automation).
82
+ Needs the window focused and visible, breaks when you alt-tab. No.
83
+
84
+ Option 1, with the host as a separate process (like the tmux server) rather than
85
+ inside the hub, so that `codeaside service restart` or an upgrade leaves sessions
86
+ running, and `codeaside claude` works even when the hub is down.
87
+
88
+ ### Process model
89
+
90
+ - Binary: `node host/host.mjs`, started detached and windowless by whoever needs
91
+ it first (the CLI for `codeaside claude`, the hub for a launch from the
92
+ glasses). One per user, guarded by the named pipe: if the pipe answers, join it.
93
+ - Listens on `\\.\pipe\codeaside-host-<username>`. Named pipes are local only,
94
+ and the default ACL limits them to the same user, which matches tmux's socket
95
+ permissions.
96
+ - Each session: a ConPTY from `@lydell/node-pty` running Claude Code, a headless
97
+ `@xterm/headless` terminal that every byte of output is written to (this is the
98
+ `capture-pane` buffer), and zero or more attached terminal clients that get the
99
+ same bytes live.
100
+ - The host exits when it has had no sessions and no clients for a few seconds,
101
+ like a tmux server with no sessions.
102
+
103
+ ### Protocol
104
+
105
+ Newline-delimited JSON over the pipe, one control connection per client, plus a
106
+ raw connection for an attach stream.
107
+
108
+ | Request | Reply | tmux equivalent |
109
+ |---|---|---|
110
+ | `new {name, cwd, cmd, args, env, cols, rows}` | `{id, name, pid}` | `new-session -d` |
111
+ | `list` | `[{id, name, cwd, pid, attached, alive, title}]` | `list-sessions` |
112
+ | `alive {id}` | `{alive}` | `display-message #{pane_id}` |
113
+ | `screen {id, lines}` | `{text}`: last N logical lines, wrapped rows joined | `capture-pane -p -J -S -N` |
114
+ | `write {id, data}` | ok | `send-keys -l` |
115
+ | `key {id, key}` | ok; same whitelist as upstream (`Enter`, `Escape`, `Up`, `Down`, `Tab`, `BTab`, `1`…`9`), sent as VT sequences | `send-keys Enter` |
116
+ | `resize {id, cols, rows}` | ok | client resize |
117
+ | `kill {id}` | ok | `kill-session` |
118
+ | `attach {id}` on a raw connection | the current screen (serialized with `@xterm/addon-serialize`), then live output; input bytes flow back | `attach-session` |
119
+
120
+ Session identity for the hub: the pipe name plus the host's session id, standing
121
+ in for tmux's socket path plus pane id (`paneKey` in `hub/tmux.mjs`). The host
122
+ sets `CODEASIDE_HOST=<pipe name>` and `CODEASIDE_PANE=<id>` in the ConPTY's
123
+ environment so the hook can report which session it belongs to, the way `$TMUX`
124
+ and `$TMUX_PANE` do upstream. Claude Code's hooks inherit the parent environment
125
+ (documented), so these reach the hook.
126
+
127
+ ### Copy mode, scrolling, and the things tmux did for free
128
+
129
+ - No copy mode. Scrolling in Windows Terminal scrolls the terminal's own buffer,
130
+ not the ConPTY, so typed keys always reach Claude Code. `leaveCopyMode` goes.
131
+ - Resize: the ConPTY takes the size of the most recently attached client, and
132
+ 200×50 for a session nobody is attached to (upstream's launch size). Claude Code
133
+ reflows on resize, so a detached session that later gets attached redraws.
134
+ - Scrollback: the headless terminal keeps 5000 lines, so `screen` can look back
135
+ as far as upstream's `capture-pane -S -60` ever needs.
136
+ - The terminal title Claude Code sets is forwarded to attached clients, so the
137
+ Windows Terminal tab shows the session title as it does upstream.
138
+
139
+ ### Starting Claude Code
140
+
141
+ Claude Code on Windows is the native `claude.exe`, whether it came from the
142
+ installer (`%USERPROFILE%\.local\bin\claude.exe`), WinGet, or npm (the npm package
143
+ installs the same binary and exposes it through a `claude.cmd` shim). The host
144
+ resolves the command with `where.exe`, prefers a `.exe`, and runs a `.cmd` through
145
+ `cmd.exe /d /c` so ConPTY gets a real executable. There is no login-shell wrapper:
146
+ a process started from a logon task or the hub already has the user's registry
147
+ environment, which is where PATH lives on Windows. `CODEASIDE_HOOK_PORT` is
148
+ passed as upstream does.
149
+
150
+ ### The attach client
151
+
152
+ `codeaside claude [args]` and `codeaside attach [name]` run a thin client in the
153
+ current console: stdin in raw mode → pipe → ConPTY; ConPTY output → stdout; window
154
+ resize → `resize`. Closing the window drops the pipe and only detaches. A detach
155
+ key (Ctrl+]) is offered too. On attach the client receives the serialized screen
156
+ first, so a session that has been running headless appears exactly as it is.
157
+
158
+ Windows Terminal, the legacy console and VS Code's terminal all work, because each
159
+ is just a VT host for the client. Nothing requires Windows Terminal, and Claude
160
+ Code documents no terminal requirement beyond a shell.
161
+
162
+ ## Hooks
163
+
164
+ How Claude Code runs `type: "command"` hooks on Windows, per its docs: the command
165
+ string goes to Git Bash when Git for Windows is installed, otherwise to PowerShell;
166
+ the `shell` field can force `"powershell"`. Git for Windows is recommended but not
167
+ required. Hooks inherit the parent process environment. `async: true` is supported
168
+ and has no Windows restriction. The hook's stdin JSON carries `session_id`,
169
+ `transcript_path`, `cwd`, `permission_mode` and `hook_event_name`.
170
+
171
+ Design:
172
+
173
+ - The hook entry is written with `"shell": "powershell"` so it behaves the same
174
+ with or without Git Bash, and the command is
175
+ `& "<node.exe>" "<...>\bin\codeaside-hook.mjs"`, both paths absolute and taken
176
+ from `process.execPath` and the package location at install time. `async: true`
177
+ as upstream, and a short `timeout`.
178
+ - `codeaside-hook.mjs` reads stdin, posts it to `http://127.0.0.1:7718/hook`
179
+ with headers `X-Host` and `X-Pane` (from `CODEASIDE_HOST`/`CODEASIDE_PANE`) and
180
+ `X-Shell-Pid` (PowerShell's `$PID`, passed as an argument), swallows every
181
+ error, and exits 0. Node starts in about 50 ms; PowerShell adds a few hundred.
182
+ Both are hidden by `async`.
183
+ - **Process id of Claude.** Upstream's hook reports `$PPID`, which under
184
+ `sh -c` is Claude itself. Under PowerShell → Node it is PowerShell. The hub
185
+ doesn't need it for host sessions, because the host knows the ConPTY process
186
+ and answers `alive`. For sessions started outside the host (view-only), the hub
187
+ looks the parent up once, when a session first reports in, with
188
+ `Get-CimInstance Win32_Process -Filter "ProcessId=<X-Shell-Pid>"` while that
189
+ PowerShell is still alive, and retries on the next hook if it has already gone.
190
+ One query per session, not per event. If that proves flaky, fall back to a
191
+ transcript-mtime idle timeout for view-only sessions.
192
+ - `install` edits `%USERPROFILE%\.claude\settings.json` with the same
193
+ merge/backup logic as upstream; `isOurHook` recognises the entry by the script's
194
+ basename, so old paths are replaced on reinstall.
195
+ - The transcript path "is written asynchronously and may lag" (docs). Upstream
196
+ already treats `Stop`'s `last_assistant_message` as the end-of-turn text and
197
+ tails the file with a poll, so nothing new is needed; worth remembering when
198
+ testing `confirmDelivered`.
199
+
200
+ ## CLI on Windows
201
+
202
+ Same commands, same output. Differences:
203
+
204
+ | Command | Windows behaviour |
205
+ |---|---|
206
+ | `codeaside claude [args]` | starts the host if needed, creates a session, attaches. Inside a host session (`CODEASIDE_PANE` set) it just runs Claude Code, like upstream inside tmux. |
207
+ | `codeaside attach [name]`, `ls` | ask the host instead of `tmux list-sessions` |
208
+ | `codeaside service install\|uninstall\|restart\|status` | Task Scheduler, see below |
209
+ | `codeaside serve on\|off\|status` | `tailscale.exe serve --bg --https=7443 http://127.0.0.1:7717`, found on PATH or at `C:\Program Files\Tailscale\tailscale.exe` |
210
+ | `codeaside setup-voice` | downloads `whisper-bin-x64.zip` (or the arm64 build) from whisper.cpp's release and the model with Node's `fetch`, not `curl` |
211
+ | `codeaside doctor` | checks Node ≥ 20, Claude Code on PATH, Tailscale running with HTTPS certs, the host pipe, the hub, the hook in `settings.json`, the speech model and `whisper-server.exe` |
212
+ | `codeaside pair` | unchanged; the code is printed, and a QR is drawn in the terminal only if a pure-JS encoder is bundled later (`qrencode` isn't common on Windows) |
213
+
214
+ `commandExists` uses `where.exe`; `findRealClaude` filters this package's own npm
215
+ shim out of the `where.exe claude` results the same way upstream filters itself
216
+ out of `which -a claude`. The `bin/codeaside` entry gets a `.cmd` shim from npm
217
+ automatically, so `codeaside` works from PowerShell and cmd.
218
+
219
+ ## Background service: Task Scheduler
220
+
221
+ `codeaside service install` writes a task XML and registers it with
222
+ `schtasks /Create /XML`, because the XML form is the only one that can ask for
223
+ restart on failure:
224
+
225
+ - Trigger: at logon of the current user. Principal: the current user, least
226
+ privilege, "run only when user is logged on", so the hub shares the desktop
227
+ session with your terminals and no password is stored.
228
+ - Action: `wscript.exe "%LOCALAPPDATA%\codeaside\hub-launcher.vbs"`, a three-line
229
+ script that starts `node.exe <codeaside> hub` hidden. A console program started
230
+ directly by a logon task gets a visible console window; this is the standard
231
+ way around it.
232
+ - Settings: `RestartOnFailure` every minute, unlimited; `ExecutionTimeLimit` off;
233
+ `MultipleInstancesPolicy` IgnoreNew; allowed on battery.
234
+ - Logs: the hub writes its own log to `%LOCALAPPDATA%\codeaside\logs\hub.log`,
235
+ rotated at 5 MB, since there is no `StandardOutPath`.
236
+
237
+ `service install` also runs the task once so the hub is up immediately. `status`
238
+ reads `schtasks /Query /TN "CodeAside Hub" /V /FO LIST`. The hub keeps sessions across
239
+ its own restarts by asking the host for its session list at startup and matching
240
+ ids against `sessions.json`, so a hub restart never shows an empty glasses list.
241
+
242
+ Keeping the machine awake (`preventSleep`) uses
243
+ `SetThreadExecutionState(ES_CONTINUOUS | ES_SYSTEM_REQUIRED)` from a small
244
+ PowerShell child the hub keeps alive, only while on AC power. Later milestone.
245
+
246
+ ## HTTPS and the phone
247
+
248
+ Unchanged: Tailscale on the PC and the phone, HTTPS certificates on for the
249
+ tailnet, `tailscale serve` proxying `https://<pc>.<tailnet>.ts.net:7443` to
250
+ `http://127.0.0.1:7717`. A port proxy needs no elevation on Windows (only file
251
+ serving does). `tailscale status --json` and `tailscale serve status --json` have
252
+ the same shape as on macOS, so `tailscaleStatus()` and `serveActive()` in
253
+ `bin/codeaside` port as they are.
254
+
255
+ The hub still binds 127.0.0.1 only. Loopback listeners don't trigger Windows
256
+ Firewall prompts.
257
+
258
+ ## Voice
259
+
260
+ whisper.cpp publishes Windows binaries on its build-tagged releases (for example
261
+ `b5454`: `whisper-bin-x64.zip`, `whisper-bin-win-cpu-arm64.zip` and CUDA variants),
262
+ and the zip contains `whisper-server.exe`, the same HTTP server upstream talks
263
+ to. The version-tagged releases (`v1.9.x`) carry no binaries, so the code pins a
264
+ build tag. `setup-voice` downloads the zip for the machine's architecture into
265
+ `%LOCALAPPDATA%\codeaside\whisper\` and the `ggml-large-v3-turbo-q5_0.bin` model
266
+ into `%LOCALAPPDATA%\codeaside\models\`, both with resumable `fetch` to a `.part`
267
+ file, and unzips with PowerShell's `Expand-Archive` (no dependency). `hub/stt.mjs`
268
+ only changes the binary path (configurable as `whisperBin`) and spawns it with
269
+ `windowsHide: true`.
270
+
271
+ ## Paths and config
272
+
273
+ | Upstream | Windows |
274
+ |---|---|
275
+ | `~/.config/glancecode/` (config.json, sessions.json, tmux.conf) | `%APPDATA%\codeaside\` (config.json, sessions.json) |
276
+ | `~/.local/share/glancecode/models/` | `%LOCALAPPDATA%\codeaside\models\`, plus `whisper\` and `logs\` |
277
+ | `~/.claude/settings.json`, `~/.claude/projects/` | `%USERPROFILE%\.claude\settings.json`, `%USERPROFILE%\.claude\projects\`. Same layout. The project folder is the cwd with every non-alphanumeric character replaced by `-` (documented), so `D:\Repos\foo` is `D--Repos-foo`; `cwd` inside entries keeps backslashes. `CLAUDE_CONFIG_DIR` is honoured when set. |
278
+ | `chmod 600 config.json` | skipped; the profile folders are already user-only |
279
+ | `CODEASIDE_CONFIG_DIR`, `CODEASIDE_DATA_DIR` | same overrides, used by tests and CI |
280
+
281
+ Config keys dropped: `tmuxSocket`, `codex*`, `gemini*`, `defaultAgent`. Added:
282
+ `whisperBin`, `hostPipe` (default derived from the username). Everything else
283
+ keeps its name and default.
284
+
285
+ Code that splits paths on `/` (`sessionNameFor` in `hub/tmux.mjs`) switches to
286
+ `path.basename`, which handles both separators on Windows.
287
+
288
+ ## Code plan
289
+
290
+ The fork keeps upstream's file layout so merges from upstream stay tractable.
291
+
292
+ | File | Change |
293
+ |---|---|
294
+ | `host/host.mjs` (new) | the session host: pipe server, ConPTY sessions, headless screens, attach streams |
295
+ | `host/client.mjs` (new) | pipe client used by the hub and the CLI; the terminal relay for attach |
296
+ | `hub/tmux.mjs` → `hub/pane.mjs` | same exported functions (`capture`, `readDialog`, `sendPrompt`, `sendKey`, `chooseOption`, `switchModel`, `answerWithText`, `launchClaude`, `acceptTrustIfShown`, `waitForInput`, `paneAlive`, `paneKey`, …) over the host client. `readDialog`, `promptSnippet`, `screenHasSnippet` and `switchModel`'s logic are copied unchanged; they only look at text. |
297
+ | `hub/sessions.mjs` | imports from `pane.mjs`; hook env fields become `host`/`pane`/`shellPid`; Gemini branches removed; `pidAlive` works as is (`process.kill(pid, 0)` is supported on Windows) |
298
+ | `hub/server.mjs` | Codex and Gemini removed; `caffeinate` behind a platform check; a file logger; everything else as is |
299
+ | `hub/config.mjs` | Windows directories, dropped and added keys, no `chmod` |
300
+ | `hub/stt.mjs` | binary path, `windowsHide` |
301
+ | `bin/codeaside` | `where.exe`, Task Scheduler service, host-based `claude`/`attach`/`ls`, `fetch` download, Codex/Gemini commands removed |
302
+ | `bin/codeaside-hook.mjs` (new, replaces the bash script) | see Hooks |
303
+ | `package.json` | `"os": ["win32"]`; `host/` in `files`; dependencies `@lydell/node-pty`, `@xterm/headless`, `@xterm/addon-serialize` |
304
+ | `test/` | `transcript.test.mjs` kept; `codex`/`gemini` tests dropped; new tests for the host protocol and `pane.mjs` against a fake host; CI matrix on `windows-latest` |
305
+ | `app/` | unchanged, except the "not in tmux" help text in `app/src/app.ts`, which already reads the agent from the hub and can say "start it with `codeaside claude`" |
306
+ | docs | README rewritten for Windows; this file |
307
+
308
+ ### On dependencies
309
+
310
+ Upstream's hub has no runtime dependencies and CONTRIBUTING asks to keep it so.
311
+ This fork needs two, and both live in the host, not the hub:
312
+
313
+ - `@lydell/node-pty`: ConPTY bindings with prebuilt binaries for win32-x64 and
314
+ win32-arm64 as optional dependencies, so `npm install -g` needs no compiler.
315
+ There is no way to create a pseudo-console from plain Node.
316
+ - `@xterm/headless` (+ `@xterm/addon-serialize`): a VT parser with a screen
317
+ buffer, needed to answer "what does the screen say" without a terminal window.
318
+ Writing a VT parser good enough for Claude Code's Ink UI by hand isn't worth it.
319
+
320
+ The hub itself stays dependency-free; it only speaks JSON over a pipe.
321
+
322
+ ## Keeping up with upstream
323
+
324
+ Remotes: `upstream` → `sousyllc/glancecode`, `origin` → the fork. The fork is a
325
+ divergent port, not a feature branch, so upstream changes come over by cherry-pick
326
+ or small merges rather than rebases. Upstream commits to `hub/transcript.mjs`,
327
+ `hub/sessions.mjs`, `hub/server.mjs` and `app/` apply almost directly; changes to
328
+ `hub/tmux.mjs` and `bin/glancecode` get translated by hand. Wire-level names the
329
+ app depends on (`tmuxName`, `controllable`, `origin`) stay as they are so the same
330
+ store app serves both hubs.
331
+
332
+ If the port proves solid, the clean end state is to offer upstream a `hub/pane.mjs`
333
+ abstraction with a tmux backend and a host backend, and keep Windows support in
334
+ one tree. That's a later conversation with upstream.
335
+
336
+ ## Milestones
337
+
338
+ 1. **Host and local control.** `host/`, `pane.mjs`, `codeaside claude`/`attach`/
339
+ `ls`; the hub follows hook-registered sessions and can type into them.
340
+ Verified by: start a session at the desk, send a prompt with `curl` to the hub
341
+ API, see it typed; approve a permission; interrupt.
342
+ 2. **Install story.** Node hook script, `install`/`uninstall`, Task Scheduler
343
+ service, `serve`, `pair`, `doctor`, Windows config paths. Pair real glasses.
344
+ 3. **Voice.** `setup-voice` downloading whisper.cpp's Windows build and the
345
+ model; hold to talk end to end.
346
+ 4. **Polish.** Keep-awake, hub re-adopting host sessions after a restart, QR code
347
+ in the terminal, an ARM64 check on a Snapdragon machine, CI on
348
+ `windows-latest`. Possibly: deliver prompts to view-only sessions through
349
+ Claude Code's cross-session messaging pipe (documented; prompts only, never
350
+ approvals).
351
+
352
+ ## Risks and open questions
353
+
354
+ - **ConPTY output shape.** ConPTY re-renders rather than passing the app's exact
355
+ bytes through, so the headless screen shows what a terminal would show, which
356
+ is what `readDialog` wants. Cursor-position and partial-redraw quirks may need
357
+ the same tolerance tmux's `-J` join gave upstream; `readDialog` already trims
358
+ and joins.
359
+ - **Hook shell.** Forcing `"shell": "powershell"` relies on that field; it is in
360
+ the hooks docs and already in use in this machine's settings. If it ever went
361
+ away, the fallback is a command that works in both bash and PowerShell, which
362
+ is awkward because of `&`.
363
+ - **Claude's PID for view-only sessions.** One CIM query per new session, racing
364
+ the PowerShell exit. Mitigation above.
365
+ - **`claude.cmd` argument quoting** through `cmd.exe /c` for prompts with quotes
366
+ or carets. The host passes an argv array to node-pty, which builds the command
367
+ line, and prefers the native `claude.exe`, which avoids `cmd.exe` entirely.
368
+ - **Defender / SmartScreen** on a downloaded `whisper-server.exe`: it is unsigned.
369
+ Running it from `%LOCALAPPDATA%` normally just works; `doctor` should notice if
370
+ the process exits at once and point at the Defender history.
371
+ - **Named pipe collisions** between two users on the same PC are avoided by the
372
+ username in the pipe name; a fast-user-switched second desktop gets its own
373
+ host.
374
+ - **Node ABI.** `@lydell/node-pty` prebuilds must cover the Node version in use
375
+ (this machine runs Node 24); confirm at implementation and set `engines`
376
+ accordingly.
377
+
378
+ ## What milestone 1 found
379
+
380
+ Things the implementation learned that the design above didn't predict:
381
+
382
+ - **Arrow keys don't reach Claude Code's menus through ConPTY.** A raw-mode Node
383
+ program inside the same ConPTY receives `ESC [ B` fine, in legacy, application
384
+ and win32-input-mode encodings, but Claude Code's select menus (trust dialog,
385
+ model picker) don't move. The vi keys `j`/`k` do. The host exposes them as
386
+ `MenuDown`/`MenuUp`, and the trust handler checks that "Yes, I trust" has the
387
+ focus before pressing Enter. Only menus use them; in the prompt box they'd type.
388
+ - **A lone Escape is delayed.** conhost holds a bare ESC on the input pipe waiting
389
+ for a sequence, about a second. Sent as a win32-input-mode key record
390
+ (`ESC [ 27;1;27;1;0;1 _` down, then up) it is delivered at once, so `Escape` in
391
+ the key table is that record. Interrupt from the API works with it.
392
+ - **node-pty leaves handles open after a natural exit.** Only the output pipe is
393
+ closed when the child exits on its own; the input pipe and the conout worker
394
+ stay. The host calls the pty's `kill()` after exit to release them, or the host
395
+ process never ends.
396
+ - **Nested-session markers.** A hub started from inside a Claude Code session
397
+ passes `CLAUDECODE`, `CLAUDE_CODE_CHILD_SESSION`, `CLAUDE_CODE_SESSION_ID` and
398
+ friends to the host, and Claude Code then treats the new session as a child:
399
+ transcript saving off, so the hub saw no items. The host strips them.
400
+ - **The Claude pid of a view-only session** must be looked up while the hook's
401
+ PowerShell is still alive, which is only until the hub answers the POST. The
402
+ hub does the one CIM query before replying to a new view-only session's first
403
+ hook. Verified: a session started outside the host is listed view-only and is
404
+ marked ended within one sweep after its process dies.
405
+ - **A killed hub tree takes the host with it.** The host is spawned detached, so
406
+ closing a console window leaves it alone, but anything that kills the hub's
407
+ process tree (`taskkill /T`, and possibly Task Scheduler's end-task) kills the
408
+ host and orphans its Claude processes. Milestone 2 should start the host through
409
+ an intermediate (`wscript`, `Start-Process`) so it isn't the hub's child, and
410
+ the host should notice its ConPTY children on startup.
411
+ - **Host idleness** counts only sessions, not control connections: the hub keeps
412
+ one open for as long as it runs, and a host with nothing to hold should make way
413
+ for a newer one.
414
+ - The hook entry is `& "<node.exe>" "<...>\codeaside-hook.mjs" $PID` with
415
+ `"shell": "powershell"`, `async: true`, `timeout: 10`. For testing without
416
+ touching `%USERPROFILE%\.claude\settings.json`, the same entry in a scratch
417
+ project's `.claude\settings.json` works.
418
+
419
+ ## What milestone 2 found
420
+
421
+ - **Task Scheduler and process trees.** The task's action is `wscript.exe` running
422
+ a script that starts the hub hidden and waits for it, so Task Scheduler sees the
423
+ hub's exit code and restarts it on failure. `schtasks /End` plus stopping the hub
424
+ process does not reach the host when the host was started through its own
425
+ non-waiting `wscript` launcher: after `service stop` the host and its Claude
426
+ session were still there, and the restarted hub listed the session as
427
+ controllable again from `sessions.json`. The job-object worry in the design
428
+ didn't materialise.
429
+ - The task runs with the interactive token and least privilege, no stored
430
+ password; `Get-ScheduledTask` through PowerShell gives a locale-independent
431
+ status.
432
+ - Tailscale on this machine installs to `C:\Program Files\Tailscale` without
433
+ adding itself to PATH, so the CLI looks there. HTTPS certificates are a tailnet
434
+ setting the user has to flip once in the admin console; `serve` says so.
435
+
436
+ ## What milestone 3 found
437
+
438
+ - whisper.cpp's build-tagged release `b5454` ships `whisper-bin-x64.zip` and an
439
+ arm64 CPU zip with `whisper-server.exe` under `Release/`, plus every `ggml-cpu-*`
440
+ DLL for the CPU features it was built for; the server picks the right one at
441
+ run time. `setup-voice` keeps the server and the DLLs and drops the other tools.
442
+ Downloads resume from a `.part` file; GitHub and Hugging Face both honour Range.
443
+ - First transcription on this PC: the hub starts the server and the model loads in
444
+ under a second of extra latency; a 5-second sentence from Windows text-to-speech
445
+ came back word for word. CPU transcription runs at roughly real time on 6
446
+ threads, so the live preview while holding lags behind speech. `whisperThreads`
447
+ sizes the thread count to the machine; a CUDA build of whisper.cpp (set
448
+ `whisperBin`) is the real fix on an NVIDIA PC, and could become
449
+ `setup-voice --cuda` once the CUDA runtime DLL question is settled.
450
+ - Windows Defender let the unsigned `whisper-server.exe` run from
451
+ `%LOCALAPPDATA%` without a prompt.
452
+ - **CUDA.** The `whisper-bin-win-cuda-12.4.0-x64.zip` asset (685 MB) bundles
453
+ cudart, cublas and nvrtc, so it runs with just the NVIDIA driver. On this PC's
454
+ RTX 5090 the first inference ever took 33 s (kernel compilation for the card,
455
+ which the driver then caches: the next server start warmed up in 2 s), the
456
+ rest 70 ms, against 4.6 s on 8 CPU threads. The hub runs a one-second silent
457
+ inference when the server comes up, so whatever that cost is lands at hub start.
458
+ `setup-voice` picks CUDA when `nvidia-smi.exe` is in System32; `--cpu` and
459
+ `--cuda` override, and switching builds stops the running server first (its
460
+ files are locked while it runs).
461
+
462
+ ## What milestone 4 found
463
+
464
+ - **Keep-awake** is a PowerShell helper calling `SetThreadExecutionState`
465
+ (`ES_CONTINUOUS | ES_SYSTEM_REQUIRED`) every 30 s while on AC power, exiting
466
+ when the hub's pid is gone. It holds the system, not the display.
467
+ - **Dialog reads race Claude Code's redraws.** A capture taken mid-redraw can miss
468
+ one line of a numbered list; the old parser compacted the list, so index 0 became
469
+ option 2 and a tap on "Yes" pressed "Yes, and switch to accept edits". Reads now
470
+ reject lists with gaps and wait for two consecutive matching reads. This affects
471
+ upstream too, since `capture-pane` has the same race; worth sending back.
472
+ - **Dialogs the hub never heard about.** Restart the hub while Claude waits for
473
+ approval and the restored session comes back idle, because waiting isn't
474
+ persisted. The sweep now reads each live pane and, after two matching reads,
475
+ reports a permission or question dialog it finds, with the question line as the
476
+ detail. The same path covers a lost hook.
477
+ - New session and Resume from the glasses both work through the simulator: the
478
+ project picker lists recent projects from the transcripts on disk, Resume lists
479
+ past sessions with their titles, and the resumed session shows its history.
480
+ - `pair` draws the QR code with `qrcode-terminal` (pure JS, no dependencies),
481
+ since `qrencode` isn't a Windows staple.
482
+
483
+ ## After the port
484
+
485
+ Using the port on G2 glasses changed two things this design took as fixed.
486
+
487
+ **The glasses app is no longer upstream's, unchanged.** `app/` is the fork's own
488
+ copy, versioned with the fork from 0.1.0. Upstream's build in Even Hub still pairs
489
+ with this hub: what the hub adds to the API is extra fields (`prefs` in
490
+ `/api/state`, `full` on a tool item, `suggestion` on a session) that upstream's app
491
+ ignores. The fork's copy is sideloaded from the hub with `pair --dev` or installed
492
+ as a private or beta build; the README has both.
493
+
494
+ What the copy adds, each behind a setting in the hub's config:
495
+
496
+ - **A long reply starts at its first line** (`replyFromStart`). The view used to
497
+ be a number of lines up from the bottom, so it drifted as lines arrived. It is
498
+ now anchored to a transcript item and an offset in it (`app/src/scroll.ts`),
499
+ which also keeps a scrolled view still. Only a reply that arrives while the
500
+ session is open is held; a session opens on its latest lines.
501
+ - **The screen dims while a session works** (`workingBrightness`). The SDK has no
502
+ display brightness, but a text container takes a `textColor` from 0 to 4. A
503
+ change of level has to be sent to both containers even when their text is the
504
+ same, and a rebuilt page has to repeat it, or it falls back to full.
505
+ - **Tool descriptions are cut by pixels** (`toolLines`). The hub cut them at 50 or
506
+ 60 characters, about one line, before the app saw them. It now sends the whole
507
+ description as well, and the app cuts it at the end of the last line allowed.
508
+ - **Suggested prompts** (`showSuggestions`). Claude Code draws a suggestion as dim
509
+ text in its input box and records it nowhere else: not in the transcript, not
510
+ through a hook. The plain screen read can't tell it from typed text, but the
511
+ host already paints a styled screen for a client that attaches, and an attach
512
+ that names no size resizes nothing. The hub takes that, drops the connection,
513
+ and looks for dim text alone in the box. This needed no change to the host,
514
+ which matters because a running host only takes new code when its last session
515
+ ends. Two taps send a shown suggestion (`sendSuggestionOnTap`): the first asks
516
+ for the second, and the hub then types the text as any prompt from the glasses.
517
+
518
+ **Restoring sessions after a hub restart.** A session in a host pane was dropped
519
+ when the process id saved for it had exited, and came back, as "starting", only at
520
+ its next hook. A pane session is now restored whatever that id says, and the first
521
+ sweep asks the host, as the sweep itself already did.
522
+
523
+ Smaller findings:
524
+
525
+ - `cmd.exe` splits an unquoted argument at `&`. The sideload QR code lost the token
526
+ that way, and the shell tried to run `token=...`. Commands that go through the
527
+ shell on Windows, as `npx` must, are built as one quoted line.
528
+ - `execFileSync("npx", ...)` fails on Windows, where `npx` is a `.cmd` file.
529
+ - The hub client trims its item list in place once it is full, so anything kept
530
+ from one frame to the next has to be a copy.
531
+ - In the simulator, a long press without its release leaves the app deaf to the
532
+ next one.