@gwro/codeaside 0.0.0-stage → 0.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.
- package/CHANGELOG.md +205 -0
- package/LICENSE +22 -0
- package/README.md +387 -2
- package/SECURITY.md +41 -0
- package/app/dist/assets/index-B2xgr0mA.js +20 -0
- package/app/dist/index.html +40 -0
- package/bin/codeaside +603 -0
- package/bin/codeaside-hook.mjs +28 -0
- package/docs/privacy.md +60 -0
- package/docs/windows-design.md +532 -0
- package/host/client.mjs +346 -0
- package/host/host.mjs +336 -0
- package/hub/awake.mjs +45 -0
- package/hub/brand.mjs +17 -0
- package/hub/config.mjs +129 -0
- package/hub/feed.mjs +30 -0
- package/hub/notify.mjs +39 -0
- package/hub/pane.mjs +326 -0
- package/hub/procs.mjs +24 -0
- package/hub/server.mjs +441 -0
- package/hub/service.mjs +181 -0
- package/hub/sessions.mjs +507 -0
- package/hub/stt.mjs +149 -0
- package/hub/transcript.mjs +318 -0
- package/hub/voice.mjs +151 -0
- package/package.json +62 -4
package/docs/privacy.md
ADDED
|
@@ -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.
|