@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 ADDED
@@ -0,0 +1,205 @@
1
+ # Changelog
2
+
3
+ CodeAside is versioned on its own, starting at 0.1.0. It was forked
4
+ from [GlanceCode](https://github.com/sousyllc/glancecode) 0.6.2 (glasses app 0.3.1)
5
+ and does not track later upstream releases. Upstream's own history up to the fork
6
+ is kept at the end for reference.
7
+
8
+ ## 0.1.0
9
+
10
+ First release: a Windows port of the hub and command-line tool of
11
+ [GlanceCode](https://github.com/sousyllc/glancecode), with a glasses app of its own.
12
+ It has been exercised against a real hub on Windows 11 with Even's simulator, and
13
+ used with G2 glasses.
14
+
15
+ ### The glasses app and its settings
16
+
17
+ The fork's copy of the glasses app gains seven settings in the hub's config. They
18
+ need that copy of the app (`codeaside pair --dev`, or your own build); upstream's
19
+ build in Even Hub ignores them.
20
+
21
+ - `replyFromStart`, on by default. A reply that arrives while a session is open,
22
+ and is too long for the glasses display, is held at its first line until you
23
+ scroll down or tap for the latest, instead of showing its end. A session you
24
+ open starts on its latest lines.
25
+ - `workingBrightness`, 0 to 4, 0 by default. Below 4, a session's screen dims to
26
+ that level while the session works and returns to full brightness when it
27
+ finishes or needs you.
28
+ - `latestOnTalk`, on by default. Starting a hold to talk in a session that is
29
+ scrolled up or held at the start of a reply jumps to its latest lines first.
30
+ - `toolLines`, 1 to 6, 2 by default. A tool call's description takes up to that
31
+ many lines and is cut where the display runs out, measured in pixels. The hub
32
+ now sends the whole description alongside its one-line cut, so the lines can
33
+ be filled; before, a description was cut at 50 or 60 characters whatever the
34
+ setting, which is about one line.
35
+ - `latestOnPrompt`, on by default. A prompt sent to a session, or a dialog in it
36
+ answered, at the desk as well as from the glasses, brings a scrolled view back
37
+ to the latest lines.
38
+ - `showSuggestions`, on by default. When Claude Code suggests the next prompt in
39
+ its input box, the glasses show it under the session's latest lines. The hub
40
+ reads it off the screen of sessions that run in the host: dim text alone in
41
+ the input box, which typed text never is.
42
+ - `sendSuggestionOnTap`, on by default. A tap on a shown suggestion asks for a
43
+ second tap, and the second sends the suggestion as the next prompt. The wait
44
+ for the second tap ends after eight seconds, or at a double-tap or a swipe.
45
+ - PowerShell tool calls are labelled as Bash ones are: by their description, or
46
+ by the command when there is none.
47
+ - The fork's copy of the glasses app is now versioned with the fork, from 0.1.0,
48
+ instead of carrying upstream's 0.3.1. `npm run pack:personal` works on Windows.
49
+ - A hub restart no longer loses a session that runs in the host when the process
50
+ id saved for it has exited; it used to reappear only at its next hook.
51
+ - A scrolled transcript now stays on the same line while new lines arrive, and the
52
+ header counts the lines below the view (`↓13`).
53
+ - `pair --dev` printed a sideload QR code without the token on Windows, because
54
+ the shell cut the address at its `&`. The address is now quoted.
55
+ - The project is named CodeAside throughout, so that it isn't taken for upstream's
56
+ GlanceCode: the repository ([gwro/CodeAside](https://github.com/gwro/CodeAside)),
57
+ the glasses app and its package ID, the `codeaside` command, the npm package,
58
+ the config and data folders, the scheduled task, the host's named pipe and the
59
+ `CODEASIDE_` environment variables. An install made before the rename has to
60
+ be removed and set up again; nothing is carried over by itself.
61
+ - The app's built-in demo shows Claude Code sessions only, as the hub runs, and
62
+ one of them has a suggested prompt. The listing's screenshots are retaken from
63
+ it, and there is a cover image.
64
+ - The phone screen of the fork's copy of the app links to this repository's setup
65
+ guide and privacy policy, not upstream's.
66
+ - Documentation: the README covers the fork's copy of the app, how to sideload it
67
+ or install it as your own build, and what to check when the glasses can't reach
68
+ the hub. The store listing, privacy policy and security notes are rewritten for
69
+ the fork: Claude Code only, Windows paths, and what the hub reads on the PC.
70
+ ### Sessions
71
+
72
+ - A **session host** replaces tmux: a small Node process runs Claude Code in a
73
+ ConPTY pseudo-console, keeps a headless terminal screen for it, and serves the
74
+ hub and the CLI over a user-private named pipe. It is started through a hidden
75
+ launcher so it belongs to no process tree: hub restarts leave sessions running
76
+ and the hub picks them up again, and the host exits by itself when its last
77
+ session ends.
78
+ - `codeaside claude [args]` starts Claude Code in the host and attaches the
79
+ console; Ctrl+] or closing the window detaches; `attach` and `ls` work as
80
+ upstream's tmux versions do. The detach chord is recognised in the plain,
81
+ win32-input-mode and kitty keyboard encodings Windows terminals use.
82
+ - Claude Code reports to the hub through a Node hook script run under PowerShell;
83
+ Git Bash is not required. Sessions started in a plain terminal appear view-only,
84
+ with Claude's process id resolved while the hook's shell is still alive.
85
+ - Live transcript, approvals with the real option labels, questions, interrupt,
86
+ model switch and compact through the same hub API as upstream, so upstream's
87
+ Even Hub glasses app works unchanged. New session in a recent project and Resume
88
+ of a past session work from the glasses.
89
+
90
+ ### Service
91
+
92
+ - `codeaside service install|uninstall|restart|stop|status`: the hub as a Task
93
+ Scheduler task for the signed-in user, started hidden at logon, restarted within
94
+ a minute if it fails, logging to `%LOCALAPPDATA%\codeaside\logs\hub.log`.
95
+ - The PC is held awake (system, not display) while the hub runs on AC power;
96
+ `preventSleep: false` turns it off.
97
+ - `doctor` reports Node, Claude Code, the hook, the host, the hub, the service,
98
+ whisper.cpp, Tailscale and HTTPS; `setup` runs the whole install; `pair` draws
99
+ the pairing code as a QR code.
100
+
101
+ ### Voice
102
+
103
+ - `codeaside setup-voice` downloads whisper.cpp's Windows release (pinned build)
104
+ and the speech model, resuming interrupted downloads. With an NVIDIA GPU it
105
+ installs the CUDA build, which transcribes a sentence in about 70 ms against
106
+ about real time on the CPU; `--cuda` and `--cpu` choose. The hub warms the
107
+ model up at start. `whisperThreads` sizes the CPU build to the machine.
108
+
109
+ ### Robustness
110
+
111
+ - Dialog reads reject numbered lists with a gap (a read taken while Claude Code's
112
+ UI was mid-redraw) and wait for two matching reads, so a tap on "Yes" cannot
113
+ land on the next option.
114
+ - A hub that starts while Claude Code is already waiting on a dialog finds it on
115
+ screen and reports it as waiting.
116
+ - Claude Code's menus ignore arrow keys arriving through ConPTY, so menu
117
+ navigation uses vi keys and the trust dialog is confirmed only once "Yes" has
118
+ the focus. A bare Escape is sent as a win32-input-mode key record so conhost
119
+ delivers it at once. Nested-session markers inherited from a parent Claude Code
120
+ session are stripped from launched sessions.
121
+
122
+ ### Not included
123
+
124
+ - Codex and Gemini CLI support, tmux, launchd and systemd.
125
+
126
+ ### Paths
127
+
128
+ - Configuration in `%APPDATA%\codeaside`; speech model, whisper.cpp, logs and
129
+ launchers in `%LOCALAPPDATA%\codeaside`.
130
+
131
+ ---
132
+
133
+ ## Upstream history (before the fork)
134
+
135
+ ## 0.6.2
136
+
137
+ - Codex: resuming a session the hub can't open now says why, and what to do, rather
138
+ than "couldn't open that Codex session". Sessions owned by another Codex server
139
+ (the ChatGPT app's, an IDE's) or living in Codex Cloud can't be opened locally.
140
+
141
+ ## 0.6.1
142
+
143
+ - Codex: the hub joins Codex's own shared server when Codex's standalone build is
144
+ installed, so the ChatGPT app's remote, the terminal and the glasses can all use
145
+ the same session. Before, the hub ran a separate server and the two collided.
146
+ `glancecode doctor` says which server is in use.
147
+
148
+ ## 0.6.0 (glasses app 0.3.1)
149
+
150
+ - Gemini CLI support. `glancecode install` adds the hook to Gemini CLI's settings,
151
+ and `glancecode gemini` starts it in tmux. Gemini sessions get the live
152
+ transcript, approvals, hold to talk, interrupt, compact, and new or resumed
153
+ sessions from the glasses.
154
+ - The glasses app offers every installed agent when starting a session, and shows
155
+ Gemini's model names.
156
+ - Fixed: a session started from the glasses could be matched to another tmux
157
+ server's session, since pane ids repeat across servers.
158
+ - Fixed: a session whose tmux pane has gone now ends even if its process lingers.
159
+ - Fixed: a transcript replaced by a rewritten file is read again from the start.
160
+
161
+ ## 0.5.0 (glasses app 0.3.0)
162
+
163
+ - Codex support. The hub joins Codex's app server as one more client, so Codex
164
+ sessions show on the glasses with their live transcript, approvals, questions,
165
+ hold to talk, interrupt, compact and model switching, while the terminal shows
166
+ the same thing.
167
+ - `glancecode codex` starts Codex attached to that server, like `glancecode claude`.
168
+ - New session on the glasses asks whether to start Claude Code or Codex, and Resume
169
+ lists past sessions from both, including ones from the Codex desktop app.
170
+ - The session menu lists the models the session's agent offers.
171
+ - A new, empty session says to hold to talk instead of showing a blank screen.
172
+
173
+ ## 0.4.1
174
+
175
+ - The hub keeps a plugged-in Mac awake, so a sleeping machine no longer looks
176
+ like a dead hub from the glasses. Turn it off with `"preventSleep": false`.
177
+
178
+ ## 0.4.0
179
+
180
+ - Removed the Plausible stats calendar feed (`glancecode stats`, `statsProducts`,
181
+ `/api/stats.ics`). It had nothing to do with Claude Code sessions.
182
+
183
+ ## 0.3.0 (glasses app 0.2.4)
184
+
185
+ - Terminal tabs show Claude Code's session title for sessions inside tmux.
186
+ - Voice: a transcript waits for a tap to send; it no longer sends by itself.
187
+ Hold again to re-record, double-tap to cancel.
188
+ - Sessions no longer freeze on "Loading…" after opening the glasses menu or a
189
+ dropped connection; the app recovers after the hub restarts and keeps the
190
+ WebView awake while a working session is on screen.
191
+
192
+ ## 0.2.0
193
+
194
+ First public release.
195
+
196
+ - Hub follows every Claude Code session through hooks and transcripts, and
197
+ types into sessions that run inside tmux.
198
+ - Glasses app: session list, live transcript, approvals and questions with the
199
+ real option labels, hold to talk with a live preview, new and resumed
200
+ sessions, and a menu for interrupt, model switch and compact.
201
+ - Local speech to text with whisper.cpp.
202
+ - `glancecode setup`, `doctor`, `serve` (HTTPS through tailscale serve) and `pair`.
203
+ - Background service on macOS (launchd) and Linux (systemd user unit).
204
+ - Built-in demo in the glasses app, used before pairing.
205
+ - Optional Plausible stats as a subscribed calendar for the G2 dashboard.
package/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sousy LLC
4
+ Portions copyright (c) 2026 Grzegorz Wrobel (Windows port)
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,388 @@
1
- # Temporary Holding Version
1
+ # CodeAside
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > **Provided as-is.** This port comes with no guarantees or support; use it at
4
+ > your own risk, as the [MIT license](LICENSE) states.
5
+
6
+ CodeAside is a Windows-native port of [GlanceCode](https://github.com/sousyllc/glancecode):
7
+ drive your Claude Code sessions from Even Realities G2 glasses. See the live
8
+ transcript, approve tool calls, answer questions, and hold to talk. Everything runs
9
+ on your own PC and your own Tailscale network.
10
+
11
+ GlanceCode is an independent project by [sousy](https://github.com/sousyllc). This
12
+ fork adapts its hub and command-line tool to Windows, as `codeaside`, and carries
13
+ its own copy of the glasses app, which adds a few things for reading on the
14
+ glasses; see [The fork's copy of the glasses app](#the-forks-copy-of-the-glasses-app).
15
+ Upstream's GlanceCode app in Even Hub pairs with this hub too, as it would with the
16
+ original.
17
+ Neither project is affiliated with Anthropic, Even Realities or Microsoft.
18
+
19
+ ## About this fork
20
+
21
+ Upstream GlanceCode runs on macOS and Linux and relies on tmux to hold each Claude
22
+ Code session, type into it and read its screen; on launchd or systemd for the
23
+ background service; and on Homebrew for whisper.cpp. None of those exist on Windows,
24
+ and running them through WSL would put Claude Code in a different operating system
25
+ from your editor and your files.
26
+
27
+ This fork replaces each of those pieces with its Windows equivalent and keeps
28
+ everything else: the hub's HTTP API, the session model and the transcript reader
29
+ are upstream's, so the same Even Hub app works with both. What the hub sends
30
+ beyond upstream's API is extra fields that upstream's app ignores.
31
+
32
+ | Upstream | This fork |
33
+ |---|---|
34
+ | tmux server, `send-keys`, `capture-pane` | A **session host**: a small Node process that runs Claude Code in a Windows pseudo-console (ConPTY), keeps a headless copy of its screen, and serves the hub and the CLI over a user-private named pipe |
35
+ | `glancecode-hook` (bash + curl) | A Node script that Claude Code runs under PowerShell; no Git Bash required |
36
+ | launchd / systemd user service | A Task Scheduler task for the signed-in user, started hidden at logon, restarted on failure, logging to `%LOCALAPPDATA%\codeaside\logs` |
37
+ | `caffeinate` | A helper holding the system awake (not the display) while on AC power |
38
+ | `brew install whisper-cpp` | `setup-voice` downloads whisper.cpp's Windows release and the speech model; on a PC with an NVIDIA GPU it installs the CUDA build |
39
+ | Codex and Gemini CLI support | Not included. The fork follows Claude Code only. |
40
+
41
+ The fork is versioned on its own, starting at 0.1.0. It was taken from upstream
42
+ 0.6.2 (glasses app 0.3.1) and does not track later upstream releases; see
43
+ [CHANGELOG.md](CHANGELOG.md).
44
+
45
+ The design, the decisions behind it and what the implementation found along the way
46
+ are written up in [docs/windows-design.md](docs/windows-design.md). Two of those
47
+ findings apply to upstream as well: a screen read taken while Claude Code's UI is
48
+ mid-redraw can miss a line of a numbered dialog, and a hub that starts while Claude
49
+ is already waiting on a dialog should find it on screen. Both are handled here.
50
+
51
+ **Status.** The port is feature-complete. Sessions, the live transcript, approvals
52
+ with the real option labels, interrupt, model switching, new and resumed sessions,
53
+ the background service and hold to talk have all been exercised against a real hub
54
+ on Windows 11, using Even's simulator for the glasses app. It has since been used
55
+ with G2 glasses, with the fork's own copy of the app: pairing, the transcript,
56
+ voice, answering a question, and dimming while a session works.
57
+
58
+ ## How it works
59
+
60
+ Every session is ordinary Claude Code running inside the session host, the way
61
+ upstream runs it inside tmux. The host runs Claude Code in a pseudo-console, keeps a
62
+ copy of its screen, and lets the hub type into it and read it back. The hub follows
63
+ your sessions through Claude Code hooks and their transcript files. The glasses app
64
+ talks only to the hub, over your private Tailscale network.
65
+
66
+ ```
67
+ claude.exe (in ConPTY) ◀── keys ─── session host ◀── named pipe ──┬── codeaside claude / attach (your terminal)
68
+ │ screen ──────────────────▶ (headless terminal) └── hub (127.0.0.1)
69
+ └── hooks ──────────────────────────────────────────────────────▶ hub ◀── tailscale serve (HTTPS) ◀── Even app ◀── G2
70
+ transcript ─────────────────────────────────────────────────▶ hub
71
+ ```
72
+
73
+ Claude Code itself is never replaced or modified, so your model, permission mode,
74
+ background tasks and Remote Control keep working. There is only ever one Claude
75
+ process per session, and the terminal and the glasses see the same conversation.
76
+ The host is a separate process from the hub, so restarting or upgrading the hub
77
+ leaves your sessions running, and the hub picks them up again when it comes back.
78
+
79
+ ## What you get on the glasses
80
+
81
+ - A list of every Claude Code session on your PC, with live state: working, idle,
82
+ or waiting for you.
83
+ - The live transcript of any session: prompts, replies, progress notes and tool
84
+ calls, wrapped for the G2 display.
85
+ - Approvals and questions with the exact options the session is offering. Keys are
86
+ only pressed after that dialog has been read back from the terminal.
87
+ - Start a new session in a recent project, or resume a past session.
88
+ - A menu to interrupt, compact, or switch the session's model without changing
89
+ your default.
90
+ - Hold to talk. Words appear while you speak. Release to review, then tap to send.
91
+
92
+ With the fork's own copy of the app, also:
93
+
94
+ - A long reply is held at its first line, so you read it from the start.
95
+ - The screen dims while a session works and comes back to full brightness when it
96
+ finishes or needs you.
97
+ - Tool descriptions fill the lines you allow them and are cut where the display
98
+ ends, not at a fixed number of characters.
99
+ - The next prompt Claude Code suggests, when it suggests one. Two taps send it.
100
+
101
+ ## Requirements
102
+
103
+ On your PC (Windows 10 version 1809 or newer; Windows 11 recommended):
104
+
105
+ - Node.js 20 or newer
106
+ - [Claude Code](https://claude.com/claude-code), signed in. The native installer,
107
+ WinGet and npm installs all work. Git for Windows is not required.
108
+ - [Tailscale](https://tailscale.com/download/windows), signed in, with HTTPS
109
+ certificates enabled for your tailnet at
110
+ [login.tailscale.com/admin/dns](https://login.tailscale.com/admin/dns)
111
+ - Optional, for voice: nothing to install by hand. `codeaside setup-voice`
112
+ downloads whisper.cpp and the speech model (about 550 MB) into
113
+ `%LOCALAPPDATA%\codeaside`. With an NVIDIA GPU it takes the CUDA build (about
114
+ 685 MB, runtime included; only the normal driver is needed), which transcribes a
115
+ sentence in under a tenth of a second. The CPU build (`--cpu`) takes about as
116
+ long as the speech itself. Transcription is local and offline; there is no API
117
+ key or subscription. Without it, everything except hold to talk still works.
118
+
119
+ On your phone:
120
+
121
+ - The Even Realities app, paired with your G2 glasses
122
+ - Tailscale for iPhone or Android, signed in to the same Tailscale account as the PC
123
+
124
+ ## Install
125
+
126
+ In PowerShell:
127
+
128
+ ```powershell
129
+ npm install -g @gwro/codeaside
130
+ codeaside setup
131
+ ```
132
+
133
+ Or from a checkout of this repository, which is what you want for changing the
134
+ code or building the glasses app yourself:
135
+
136
+ ```powershell
137
+ git clone https://github.com/gwro/CodeAside.git
138
+ cd CodeAside
139
+ npm install
140
+ npm run build:app
141
+ node bin\codeaside setup
142
+ ```
143
+
144
+ `setup` checks the requirements, adds the hook to `%USERPROFILE%\.claude\settings.json`,
145
+ registers the hub as a Task Scheduler task that starts at logon, serves it over
146
+ HTTPS on your `*.ts.net` name, downloads the speech model, and prints a pairing
147
+ code. Each step is also its own command (`install`, `service install`, `serve`,
148
+ `setup-voice`, `pair`), and `doctor` reports which pieces are missing.
149
+
150
+ Then open the glasses app and paste the pairing code on the phone screen, or scan
151
+ the QR code that `pair` prints. The fork's own app is CodeAside; see
152
+ [The fork's copy of the glasses app](#the-forks-copy-of-the-glasses-app) for how to
153
+ get it. Upstream's GlanceCode app from Even Hub pairs the same way, without the
154
+ fork's additions.
155
+
156
+ To let the glasses drive a session you start at your desk, start it through the
157
+ host:
158
+
159
+ ```powershell
160
+ codeaside claude # takes the same arguments as claude
161
+ ```
162
+
163
+ Sessions started any other way still appear on the glasses, marked view only.
164
+ Closing the terminal window only detaches; the session keeps running and
165
+ `codeaside attach` opens it again. Ctrl+] detaches deliberately.
166
+
167
+ In a checkout, `npm install -g .` puts `codeaside` on your PATH as a link to the
168
+ checkout, so the examples below work as written; without it, write
169
+ `node bin\codeaside` in place of `codeaside`.
170
+
171
+ ## The fork's copy of the glasses app
172
+
173
+ The app in `app/` started as upstream's 0.3.1 and is now versioned with the fork.
174
+ It has a name of its own, **CodeAside**, so that it isn't taken for upstream's app
175
+ or an edition of it. The hub and its command are `codeaside` as well.
176
+ It reads seven display settings from the hub, all described under
177
+ [Configuration](#configuration):
178
+
179
+ | Setting | What it does |
180
+ |---|---|
181
+ | `replyFromStart` | holds a long reply at its first line until you scroll on or tap for the latest |
182
+ | `workingBrightness` | dims a session's screen while it works |
183
+ | `latestOnTalk` | jumps to the latest lines when you start to talk |
184
+ | `latestOnPrompt` | jumps to the latest lines when a prompt is sent or a dialog answered, at the desk too |
185
+ | `toolLines` | how many lines a tool call's description may take |
186
+ | `showSuggestions` | shows the next prompt Claude Code suggests |
187
+ | `sendSuggestionOnTap` | lets two taps send that suggestion |
188
+
189
+ Apart from the settings, a view you have scrolled stays on the same line while new
190
+ lines arrive, and the header shows how many lines are below it (`↓13`).
191
+
192
+ Upstream's app in Even Hub has none of this and ignores the settings. There are
193
+ two ways to run the fork's copy, and both need a developer account with Even:
194
+ sign in once at [hub.evenrealities.com](https://hub.evenrealities.com/login) with
195
+ the account you use in the Even Realities app, then force-quit and reopen that app.
196
+
197
+ **Sideload it from the hub.** Nothing to upload, and it always runs the build in
198
+ your checkout:
199
+
200
+ ```powershell
201
+ npm run build:app
202
+ codeaside pair --dev
203
+ ```
204
+
205
+ In the Even Realities app, open the Even Hub tab, then the developer section in
206
+ its top-right corner, choose Scan QR and scan the second code, the one under
207
+ "Development sideload". It carries the hub address and the token, so the app opens
208
+ paired. Even's app suspends a sideloaded page when the phone app goes to the
209
+ background, and it usually has to be scanned again afterwards.
210
+
211
+ **Install your own build.** It stays on the phone like any Even Hub app, without
212
+ being published:
213
+
214
+ 1. Give it an identity of your own in `app\app.local.json`, which git ignores. The
215
+ package ID has to be one nobody else has claimed:
216
+ ```json
217
+ { "package_id": "com.example.codeaside", "name": "My CodeAside" }
218
+ ```
219
+ 2. Run `npm run pack:personal`. It raises the app's version, builds it and writes
220
+ `codeaside.ehpk` in the checkout. Even's portal only offers phones an update
221
+ when the version is new, which is why every pack raises it; add `-- --no-bump`
222
+ to pack the current version again.
223
+ 3. At hub.evenrealities.com, create an app for it and upload the file under
224
+ Builds. If the portal asks for a name and package ID, they must match the ones
225
+ in the package. The upload arrives as a private build.
226
+ 4. To have it on the glasses menu and running with the phone locked, add yourself
227
+ under Testing group, accept the invitation email, and promote the build to
228
+ Beta. Then install it in the Even Realities app under Me > Beta tester. A build
229
+ left private installs from Me > Apps > Private builds, with those two limits.
230
+ 5. Open it and pair with the code from `codeaside pair`.
231
+
232
+ ## Using it
233
+
234
+ | Gesture | Session list | Session |
235
+ |---|---|---|
236
+ | Swipe | move | scroll, or move between options |
237
+ | Tap | open | choose the highlighted option, or jump to the latest; twice, to send a suggested prompt |
238
+ | Hold | talk to the highlighted session | talk, or answer an open question; hold again to redo |
239
+ | Double-tap | exit | back |
240
+ | Tap then hold | menu | interrupt, jump to latest, switch model, compact |
241
+
242
+ After a hold, the transcript of what you said waits on screen: tap sends it, hold
243
+ records again, double-tap discards it.
244
+
245
+ In a session's transcript, `»` marks your prompts and `▷` a tool call; calls to the
246
+ same tool in a row collapse into one line (`Read ×3`), and only the last three
247
+ groups of a run show, under a line that counts the others. Tool output is not
248
+ shown, and a reply is cut at 4,000 characters. With the fork's copy of the app,
249
+ `↓13` in the header counts the lines below the view, and `→` marks a prompt Claude
250
+ Code suggests.
251
+
252
+ At your desk:
253
+
254
+ | Command | What it does |
255
+ |---|---|
256
+ | `codeaside claude [args]` | start Claude Code in the host and attach this console |
257
+ | `codeaside attach [name]` | open a running session in this terminal |
258
+ | `codeaside ls` | list sessions |
259
+ | `codeaside feed` | a readable live feed of every session |
260
+ | `codeaside status` | hub and sessions |
261
+ | `codeaside doctor` | check every piece and say what to fix |
262
+ | `codeaside pair [--dev]` | print the pairing code and its QR code; `--dev` adds the QR code that sideloads the fork's copy of the app |
263
+ | `codeaside service restart` | restart the hub; running sessions are untouched |
264
+ | `codeaside setup-voice [--cuda\|--cpu]` | install or switch the whisper.cpp build |
265
+
266
+ Logs are in `%LOCALAPPDATA%\codeaside\logs`: `hub.log` for the hub and `host.log`
267
+ for the session host.
268
+
269
+ The examples use PowerShell. In Git Bash, write paths with forward slashes
270
+ (`node bin/codeaside status` in a checkout): Bash reads a backslash as an escape.
271
+
272
+ ### If the glasses can't reach the hub
273
+
274
+ The app says so, with the address it tried and the reason in brackets.
275
+
276
+ - `(bad token)`: the phone reached the hub with an old token. Pair again.
277
+ - Anything else, such as `(Failed to fetch)`: the request never arrived. Run
278
+ `codeaside doctor` on the PC, then open the hub's address
279
+ (`https://<your-pc>.<tailnet>.ts.net:7443`) in the phone's browser.
280
+ - If the page loads there, the phone reaches the PC and something on the phone
281
+ is keeping the Even Realities app off Tailscale, for example app-based split
282
+ tunnelling.
283
+ - If it doesn't, check that Tailscale on the phone is connected, on the same
284
+ account as the PC, and not put to sleep by battery optimisation. No exit node
285
+ is needed.
286
+
287
+ ## Security
288
+
289
+ - The hub listens on 127.0.0.1 only. Your phone reaches it through
290
+ `tailscale serve`, so traffic stays inside your tailnet and is encrypted.
291
+ - Every request needs the pairing token. Anyone with that token and access to your
292
+ tailnet can type into your sessions, so keep it private. To replace it, delete
293
+ the `token` line in `%APPDATA%\codeaside\config.json` and restart the hub.
294
+ - The hook port accepts connections from 127.0.0.1 only.
295
+ - The session host listens on a named pipe that only your Windows user can open.
296
+ It never listens on the network.
297
+ - Voice is transcribed on your PC. Audio is not sent anywhere else.
298
+
299
+ See [SECURITY.md](SECURITY.md) and [docs/privacy.md](docs/privacy.md).
300
+
301
+ ## Configuration
302
+
303
+ `%APPDATA%\codeaside\config.json` is created on first run.
304
+
305
+ | Key | Default | Purpose |
306
+ |---|---|---|
307
+ | `port` | 7717 | hub API on 127.0.0.1 |
308
+ | `httpsPort` | 7443 | HTTPS port on your `*.ts.net` name |
309
+ | `hookPort` | 7718 | hook intake on 127.0.0.1 |
310
+ | `hostPipe` | `\\.\pipe\codeaside-host-<user>` | the session host's named pipe |
311
+ | `claudeArgs` | `[]` | extra arguments for sessions started from the glasses |
312
+ | `whisperBin` | `%LOCALAPPDATA%\codeaside\whisper\whisper-server.exe` | whisper.cpp server, as installed by `setup-voice`; point it at your own build to use that instead |
313
+ | `whisperThreads` | half the logical CPUs, 2 to 8 | CPU threads for transcription (CPU build) |
314
+ | `sttVocabulary` | | words the speech model should expect |
315
+ | `ntfyTopic` | empty | optional phone push through ntfy when a session finishes or needs you |
316
+ | `preventSleep` | true | keep the PC awake (not the display) while the hub runs and the PC is on AC power |
317
+ | `bindTailscaleIP` | false | also listen on the raw Tailscale IP over plain HTTP, for development |
318
+ | `replyFromStart` | true | on the glasses, hold a reply that arrives while a session is open, and is too long for the screen, at its first line, so you read it from the start; swipe down to read on, tap for the latest. A session you open always starts on its latest lines. With `false`, a session always shows its latest lines, as upstream's app does |
319
+ | `workingBrightness` | 0 | on the glasses, the text brightness of a session's screen while it is working, from 0 (dimmest) to 4 (full). Below 4, the screen dims while Claude works and returns to full when it finishes or needs you; text you have scrolled to, a held reply, and what you dictate stay at full. With `4`, nothing dims, as in upstream's app |
320
+ | `latestOnTalk` | true | on the glasses, when you hold to talk in a session that is scrolled up or held at the start of a reply, jump to its latest lines before listening. With `false`, the view stays where it was, as in upstream's app |
321
+ | `toolLines` | 2 | on the glasses, the lines a tool call's description may take, 1 to 6. A longer description is cut where the display runs out, measured in pixels, and ends in "…" |
322
+ | `latestOnPrompt` | true | on the glasses, jump to a session's latest lines when a prompt is sent to it or a dialog in it is answered, at the desk as well as from the glasses. With `false`, a view you have scrolled stays where it is |
323
+ | `showSuggestions` | true | on the glasses, show the next prompt Claude Code suggests, when it suggests one, under an idle session's latest lines, marked `→`. Claude Code only draws it in its input box, so the hub reads it off the screen of sessions started with `codeaside claude`; view-only sessions show none. With `false`, the hub doesn't look |
324
+ | `sendSuggestionOnTap` | true | on the glasses, let a tap on a shown suggestion send it as your next prompt once a second tap confirms it. After the first tap the glasses ask for the second for eight seconds; a double-tap or a swipe calls it off. With `false`, a suggestion is only shown |
325
+
326
+ The last seven are for [the fork's copy of the glasses app](#the-forks-copy-of-the-glasses-app).
327
+ Upstream's build in Even Hub ignores them and behaves as it always has. A setting
328
+ left out of the file has its default, so the file only needs the ones you change.
329
+
330
+ Restart the hub after changing the file: `codeaside service restart`. Sessions
331
+ keep running through a restart; a message being dictated at that moment is lost.
332
+
333
+ ## Limitations
334
+
335
+ - Even Hub apps only run while they are open on the glasses. To hear about a
336
+ session while another app is open, set `ntfyTopic`.
337
+ - The G2 display has one font weight, so markdown is shown as plain text.
338
+ - Sessions must be started with `codeaside claude` for the glasses to type into
339
+ them. Others are view only, and show no suggested prompts, since the hub can't
340
+ read their screen.
341
+ - A suggested prompt appears a few seconds after Claude Code draws it, and only
342
+ when Claude Code offers one. Sending it types it into the session as a prompt
343
+ of yours, so it runs with whatever permissions the session has.
344
+ - The app makes no sound and no vibration; the screen is its only signal. Dimming
345
+ while a session works is the nearest thing to an alert: the screen brightens
346
+ when it is done.
347
+ - How dim the lowest brightness is depends on the glasses and the light. If
348
+ `workingBrightness` 0 is too dark to read, use 1.
349
+ - Voice on the CPU build runs at about real time, so the live preview while holding
350
+ lags behind speech; the CUDA build does not. There is no prebuilt whisper.cpp
351
+ server for AMD or Intel GPUs, but `whisperBin` can point at your own build.
352
+ - Codex and Gemini CLI, which upstream supports, are not included.
353
+
354
+ ## Development
355
+
356
+ ```powershell
357
+ npm install
358
+ npm run build:app # build the glasses app
359
+ npm test # hub, host and app tests
360
+ node bin\codeaside hub # run the hub in the foreground
361
+ npm run pack:personal # pack the glasses app as codeaside.ehpk
362
+ ```
363
+
364
+ The hub itself has no runtime dependencies, as upstream's doesn't. The session host
365
+ uses two: `@lydell/node-pty` for ConPTY, which ships prebuilt binaries for x64 and
366
+ ARM64 Windows, and `@xterm/headless` for the screen buffer. The CLI uses
367
+ `qrcode-terminal` for the pairing code.
368
+
369
+ [CONTRIBUTING.md](CONTRIBUTING.md) covers testing against a scratch configuration
370
+ and driving the glasses app in Even's simulator without hardware.
371
+ [docs/windows-design.md](docs/windows-design.md) is the design and the record of
372
+ what each stage of the port found.
373
+
374
+ ## Acknowledgements
375
+
376
+ This fork exists because of [GlanceCode](https://github.com/sousyllc/glancecode) by
377
+ [sousy](https://github.com/sousyllc), whose hub design, transcript reader and
378
+ glasses app are used here with gratitude. Upstream in turn credits
379
+ [cc-g2](https://github.com/wmoto-ai/cc-g2),
380
+ [claude-code-g2](https://github.com/sam-siavoshian/claude-code-g2) and Even
381
+ Realities' [templates](https://github.com/even-realities/evenhub-templates). The
382
+ Windows port adds [node-pty](https://github.com/lydell/node-pty) by Simon Lydell,
383
+ [xterm.js](https://github.com/xtermjs/xterm.js) and
384
+ [whisper.cpp](https://github.com/ggml-org/whisper.cpp). All MIT licensed.
385
+
386
+ ## License
387
+
388
+ [MIT](LICENSE), as upstream.
package/SECURITY.md ADDED
@@ -0,0 +1,41 @@
1
+ # Security
2
+
3
+ CodeAside lets a paired phone drive Claude Code sessions on your PC, so security
4
+ issues matter here. Please report them privately.
5
+
6
+ ## Reporting a vulnerability
7
+
8
+ Use GitHub's private vulnerability reporting on this repository (Security tab,
9
+ "Report a vulnerability"). Please include steps to reproduce and the version
10
+ (`codeaside version`). This fork is provided as-is, without a promised response
11
+ time.
12
+
13
+ Don't open a public issue for a security problem. A problem that is also in
14
+ upstream's GlanceCode is worth reporting [there](https://github.com/sousyllc/glancecode/security)
15
+ too.
16
+
17
+ ## Security model
18
+
19
+ - The hub API listens on 127.0.0.1. Phones reach it through `tailscale serve`,
20
+ which terminates HTTPS on the machine's `*.ts.net` name and forwards to the hub.
21
+ - Every API request needs the pairing token (24 random bytes, compared in constant
22
+ time). The token is stored in `%APPDATA%\codeaside\config.json`, in your Windows
23
+ profile, and is never bundled into the glasses app. `codeaside pair` prints it,
24
+ and the QR code from `pair --dev` carries it, so treat both like a password.
25
+ - The Claude Code hook posts to a separate port on 127.0.0.1 that is never served
26
+ over Tailscale.
27
+ - The session host, which runs Claude Code and holds its screen, listens on a named
28
+ pipe that only your Windows user can open. It never listens on the network.
29
+ - Keys are only sent to a session after the matching dialog is read back from the
30
+ terminal, and prompts are refused while a permission dialog is open.
31
+ - The hub reads a session's screen to do that, and to find a prompt Claude Code
32
+ suggests. A suggested prompt is shown on the glasses and sent only when you tap
33
+ it and then tap again to confirm; `sendSuggestionOnTap` turns that off.
34
+
35
+ ## Out of scope
36
+
37
+ - Anyone who already has the pairing token and access to your tailnet. That is
38
+ the trust boundary by design.
39
+ - Claude Code's own permission system, which CodeAside doesn't change.
40
+ - Other programs running as your user account. They can already run Claude Code
41
+ directly.