remote-for-herdr 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/LICENSE ADDED
@@ -0,0 +1,202 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright 2026 remote-for-herdr contributors
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
package/README.md CHANGED
@@ -1,3 +1,207 @@
1
- # Temporary Holding Version
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.
1
+ # remote-for-herdr
2
+
3
+ A small web app you run on the Windows PC where [Herdr](https://herdr.dev) runs. Open it from your Android phone over Tailscale to watch your agent sessions live, answer them, and get a push notification when one needs you or finishes.
4
+
5
+ > **Unofficial. Not affiliated with or endorsed by Herdr.** It is a separate project that talks to herdr-core through its `hc` command.
6
+
7
+ **Tested:** Windows 11 + Node 22 host, desktop Chrome at phone width. Real-phone end-to-end: pending (see the [manual end-to-end checklist](docs/e2e-checklist.md)).
8
+
9
+ ## Install
10
+
11
+ Check the [prerequisites](#prerequisites) first (Herdr's `hc`, Node.js 22+, Tailscale with HTTPS certificates). Then, in a normal (non-admin) PowerShell:
12
+
13
+ ```powershell
14
+ npm i -g remote-for-herdr
15
+ remote-for-herdr setup
16
+ ```
17
+
18
+ That is the recommended way: start-at-login needs a stable install, and a global install stays where it is. To just try it without installing:
19
+
20
+ ```powershell
21
+ npx remote-for-herdr setup
22
+ ```
23
+
24
+ npx runs it from a temporary cache that npm may clean up, so setup never installs start-at-login from there. If you say yes to start-at-login, it starts the app in the background instead: the app keeps running until you stop it, log off or restart the PC, and nothing restarts it after a crash. Your setup is saved in `%APPDATA%\remote-for-herdr` either way. To keep it for good:
25
+
26
+ ```powershell
27
+ npm i -g remote-for-herdr
28
+ remote-for-herdr install-task
29
+ remote-for-herdr restart
30
+ ```
31
+
32
+ `restart` stops the copy started from npx and starts the app again through the new start-at-login task. You do not need to run setup again.
33
+
34
+ `remote-for-herdr setup` is interactive. It:
35
+
36
+ 1. Checks `hc` runs and lists your terminals (asks for the path if `hc` is not on PATH).
37
+ 2. Checks Tailscale is running with HTTPS certificates, and asks for the allowed Tailscale login (default: the one you are signed in with).
38
+ 3. Asks for a PIN (at least 6 characters, typed hidden) and generates push (VAPID) keys.
39
+ 4. Offers to run `tailscale serve --bg 4780` for you. If you say no, run it yourself.
40
+ 5. Asks whether to start remote-for-herdr at Windows login (Enter means yes). If yes, it installs the task and starts the app right away, then waits until it answers. If no, it prints the command to start it.
41
+ 6. Prints the URL to open on your phone, e.g. `https://box.example.ts.net`, and a QR code of it to scan with the phone's camera.
42
+
43
+ Check it any time with `remote-for-herdr status` (running or not, its pid, the phone URL, whether start-at-login is installed).
44
+
45
+ **Update:**
46
+
47
+ ```powershell
48
+ npm i -g remote-for-herdr@latest
49
+ remote-for-herdr restart
50
+ ```
51
+
52
+ **Uninstall:**
53
+
54
+ ```powershell
55
+ remote-for-herdr stop
56
+ remote-for-herdr uninstall-task
57
+ npm rm -g remote-for-herdr
58
+ ```
59
+
60
+ Then, if you like: `tailscale serve --https=443 off`, delete `%APPDATA%\remote-for-herdr` (config, PIN hash, keys, logs) and remove the app icon from the phone. See [Uninstall](#uninstall).
61
+
62
+ ### Upgrading from herdr-remote
63
+
64
+ This project used to be called herdr-remote. Install `remote-for-herdr` as above (`npm i -g remote-for-herdr`), then run `remote-for-herdr restart` (`setup`, `start` and `install-task` do it too; `status` only tells you the move is pending). On that first run it moves your config from `%APPDATA%\herdr-remote` to `%APPDATA%\remote-for-herdr` (if the folder cannot be moved, it is copied and the old one kept). It stops the old server first if it still runs from there; if that server does not stop, nothing is moved and it tells you its pid. It also replaces the old `herdr-remote` start-at-login task with the new `remote-for-herdr` one. Your PIN, push keys and Tailscale settings are kept, so the phone link does not change: just re-open the app on the phone. `HERDR_REMOTE_HOME` still works (`REMOTE_FOR_HERDR_HOME` is the new name), and the `herdr-remote` command remains as an alias for now. If you ran it from a git clone, you can delete that folder afterwards. If you had a herdr-remote start-at-login task, run the upgrade from the global install, not through `npx`: from npx's temporary cache the task cannot be moved, so nothing is changed and you are asked to `npm i -g remote-for-herdr` first.
65
+
66
+ ## Why
67
+
68
+ Away from your desk, agents (Claude Code, Codex, ...) stop and wait for you: a permission prompt, a question, a plan to approve. Nothing moves until you are back. Herdr's own phone app does not find a Windows desktop install, so this fills the gap: a live terminal view, a few answer buttons, and a buzz on your phone.
69
+
70
+ ## What it does
71
+
72
+ - Lists your agent sessions grouped by Herdr space, most urgent first (needs you, working, done, idle).
73
+ - Shows a session live in a real terminal view (xterm.js). Watching is read-only: it never resizes or types into the session on your PC.
74
+ - Answers: key buttons (1 2 3 4, arrows, Enter, Tab, Shift+Tab, Esc) and a text box that sends a line.
75
+ - Push notifications when an agent needs you and when it finishes. Both can be switched off in Settings.
76
+ - Desk mode: a toggle that pauses all pushes while you are at the computer.
77
+
78
+ Out of scope for v1: macOS/Linux hosts (only Windows is tested), iPhone, starting new work from the phone, several users per install.
79
+
80
+ ## Prerequisites
81
+
82
+ - Windows 10/11 with Herdr (or herdr-core alone). `hc` must be on PATH (tested with 0.1.21). The server must run on the same PC as herdr-core.
83
+ - Node.js 22 or newer (with npm).
84
+ - Tailscale on the PC and on the phone, same tailnet. The free personal plan is enough.
85
+ - In the Tailscale admin console: MagicDNS and HTTPS certificates enabled (DNS page). Setup stops and tells you if HTTPS is not ready. Do this before pairing the phone: push subscriptions and the home-screen install are tied to the `https://<machine>.<tailnet>.ts.net` address.
86
+ - Android with Chrome.
87
+
88
+ ## Running it
89
+
90
+ With start-at-login installed, the app starts hidden when you log on to Windows and is restarted after a crash; you do not need to start it by hand. Otherwise `remote-for-herdr start` runs the server under a supervisor that restarts it 1 to 30 seconds after a crash. Use `remote-for-herdr start --foreground` to run it in the current console instead (no restart): it is the lightest way to run it, one Node process instead of two (see [Memory](#memory)). The server listens on `127.0.0.1:4780` only; `tailscale serve` is the only way in. Never use Tailscale Funnel.
91
+
92
+ Commands (`remote-for-herdr ...`; from a source checkout, `node src/cli.js ...`):
93
+
94
+ | Command | What it does |
95
+ |---|---|
96
+ | `setup [--proxy] [--home <dir>]` | Interactive setup. Safe to re-run, but only while the server is stopped (it refuses otherwise). |
97
+ | `status [--home <dir>]` | Whether it is running (pid, port), the phone URL, whether start-at-login is installed, the config folder. |
98
+ | `start [--foreground [--log]] [--home <dir>]` | Run the server; restarts on crash unless `--foreground`. `--log` sends its output to `<home>\logs\server.log` instead of the console. Refuses (exit 78) if another copy already runs for the same home. |
99
+ | `stop [--home <dir>]` | Stop the running server, supervised, `--foreground` or started at login (prints `stopped` or `not running`). |
100
+ | `restart [--home <dir>]` | Stop it, then start it again through the start-at-login task. Without the task, it starts the app in the background (no restart after a crash or at login) and says how to add the task. |
101
+ | `install-task [--home <dir>]` | Start at Windows login (Task Scheduler task `remote-for-herdr`, hidden window). Also removes an old `herdr-remote` task. |
102
+ | `uninstall-task [--home <dir>]` | Remove that task (both the `remote-for-herdr` and an old `herdr-remote` one; ends its hidden launcher; a running server stays up until `stop`). |
103
+
104
+ The start-at-login task is created from an XML definition (`<home>\remote-for-herdr-task.xml`, next to the hidden launcher `start-hidden.vbs`). It triggers only when you log on to Windows (your `DOMAIN\user` account), runs without elevation, has no time limit (Task Scheduler's default would stop it after 72 hours) and keeps running on battery. A normal, non-admin prompt is enough to install it. `uninstall-task` ends the task's hidden launcher, then removes the task and both files. It does not stop a running server: that keeps running, with no restart after a crash, until `remote-for-herdr stop`. Ending the task in Task Scheduler ("End") likewise ends only the launcher: the server keeps running, but is no longer restarted.
105
+
106
+ The task runs the server directly (`start --foreground --log`), without the supervisor, to save a whole Node process (see [Memory](#memory)). The hidden launcher waits for it and, if it crashes (or is ended in Task Manager), runs it again after 1 s, then 2, 4, 8, 16 and 30 s between tries (back to 1 s once a run lasted a minute). `remote-for-herdr stop` (also while it waits to restart it), a missing setup or a busy port end it for good, as before. Task Scheduler's "restart on failure" (every minute, up to 999 times) is only a backstop in case the launcher itself fails. The launcher holds the full paths to `node.exe` and to the installed package: run `install-task` again after moving the install or upgrading/reinstalling Node (an `npm i -g remote-for-herdr@latest` update keeps the same path).
107
+
108
+ To change settings later: `remote-for-herdr stop`, then `remote-for-herdr setup` (it starts the app again at the end if you keep start-at-login). The running server keeps its config in memory, so setup refuses to run while it answers on its port.
109
+
110
+ Config and state live in `%APPDATA%\remote-for-herdr\` (override with `--home <dir>` or the `REMOTE_FOR_HERDR_HOME` environment variable; the old `HERDR_REMOTE_HOME` still works). Logs are in `<home>\logs\server.log` (rotated at 5 MB to `server.log.1`).
111
+
112
+ ## Phone steps
113
+
114
+ 1. On the phone, open the URL setup printed in Chrome (Tailscale must be connected).
115
+ 2. Enter the PIN. You do this once per device.
116
+ 3. Chrome menu, Add to Home screen. Open the app from the icon.
117
+ 4. In the app: Settings, Enable notifications, allow the permission. Use Send test notification to check it.
118
+
119
+ ## Keep the PC awake
120
+
121
+ The phone can only reach the app while the PC is on and awake. Set Windows power settings to never sleep while plugged in. The app cannot do this for you.
122
+
123
+ ## Using it
124
+
125
+ - Sessions needing you are at the top. Tap one for the live view.
126
+ - The live view starts fitted to the screen width. A very wide terminal (say 200 columns) is shown at half size and you pan sideways; the minimum fit scale is 50%. Turning the phone to landscape also helps.
127
+ - Zoom with the buttons just above the terminal: `−` and `+` zoom out and in (25% to 200%), and the middle button shows the current zoom (`Fit`, or a percentage such as `80% · Fit`); tap it to fit the width again. Fit can be more than 200% when a narrow terminal fills a wide screen; `−` or a pinch from there starts at 200%. You can also pinch with two fingers on the terminal; one finger still scrolls and pans. On a desktop browser, Ctrl + mouse wheel zooms. Whenever the terminal is wider than the screen, you pan sideways inside the terminal. Your zoom is remembered on each device.
128
+ - Drag with one finger to scroll; flick to keep it gliding. Dragging down past the top of the screen scrolls up into the session's history (the last 1000 lines are loaded when you open it). While you are scrolled up (or zoomed in and not at the bottom), new output does not pull you down; tap `↓ Latest` at the bottom right to jump back. After a reconnect (for example when the phone wakes up) the view starts again at the latest output. On a desktop browser the mouse wheel does the same. Pulling down in the live view never reloads the app; on the session list, pull down to reload as usual.
129
+ - Key bar: `1 2 3 4 ↑ ↓` on the top row, `Enter Tab ⇧Tab ← → Esc` below (Esc is the outlined key at the right edge). A key that reached the terminal shows a small ✓ for a moment; Send shows `Sent ✓`. In landscape the keys form one row.
130
+ - While you type a reply, the header details and the zoom buttons fold away so the terminal (and its dialog) stays as big as possible; tapping keys or Send keeps the keyboard up. They come back when you leave the text box.
131
+ - Replies take about a second to show: each send starts a fresh `hc` process.
132
+ - Answer dialogs (questions, permission prompts) with the key buttons. While a session shows a dialog, the Send button reads `Type into dialog` and asks for a second tap: Herdr normally refuses typing into a dialog, so the app only types into one when you confirm.
133
+ - To answer a dialog's "Type something" option: press its number on the key bar (for example `3`, or move to it with `↓`), type your answer in the text box, tap `Type into dialog`, then tap `Tap again to type` (wait about half a second; a quicker second tap is ignored, and it must come within 2 seconds). While armed, the hint shows which dialog you are typing into. Ctrl+Enter (⌘+Enter) follows the same two-step rule; holding it down does nothing. The confirm disarms after 2 seconds, when you change the text, when you press a key-bar key, or when the dialog changes. The hint under the box warns you: until "Type something" is chosen, letters and digits you send act as key presses in the dialog.
134
+ - Only the dialog you saw is typed into: if it changed or was answered (for example from the PC) before your second tap, nothing is sent and the app says so. If it closed while you were confirming, Send ignores taps for a second and then sends normal replies again.
135
+ - Typing into other dialogs, permission prompts included, works the same way and needs the same confirm. Be careful: text typed into a prompt that isn't waiting for text can be read as key presses.
136
+ - The app never marks sessions as seen in Herdr, so things you handled from the phone may still look unread on the PC.
137
+ - No notification is sent for a session you are looking at on the phone right now.
138
+ - Claude Code's plain questions and "shall I go ahead?" pauses end the turn and show as done, not blocked, so the "finished" push is what tells you about them.
139
+
140
+ ## Security model
141
+
142
+ - Tailnet only: the server binds `127.0.0.1` and is exposed only through `tailscale serve`. It is never on the public internet.
143
+ - Owner login: `tailscale serve` adds the signed-in user's login; only the one login set during setup is allowed. Anyone else gets 403.
144
+ - PIN once per device, then a session cookie (HttpOnly, Secure, SameSite=Strict) valid 30 days, renewed while you use it. Only a hash of the PIN and of session tokens is stored. PIN attempts are rate limited.
145
+ - Settings, Sign out everywhere ends all sessions, closes open live views and forgets every device's push subscription (a device re-registers when you sign in on it again). Changing the PIN in setup also signs every device out.
146
+ - Because the app can type into your agents, keep your Tailscale login and devices secure.
147
+ - Pushes go through Google's FCM (that is how Web Push works on Android). They are encrypted and carry only the agent name, the space name, the terminal address and fixed text (for example "Claude Code in api needs you" / "Tap to open"), never screen content, paths or titles.
148
+ - Nothing personal is stored in the repo; your config is in the app-data folder above.
149
+
150
+ ## Switching tailnets or accounts
151
+
152
+ The web address and the login change. Run `remote-for-herdr stop`, re-run `remote-for-herdr setup` (it starts the server again if you keep start-at-login), then open the new URL on the phone, enter the PIN again and enable notifications again (old subscriptions and sessions are cleared).
153
+
154
+ ## Troubleshooting
155
+
156
+ - **"This account or network isn’t allowed to open remote-for-herdr."** (HTTP 403): the phone is signed in to Tailscale as a different login than the one set up. Sign in with the right account, or re-run setup with the right login.
157
+ - **Page does not load:** is the PC awake, is the server running (check `<home>\logs\server.log`), and is `tailscale serve --bg 4780` active (`tailscale serve status`)?
158
+ - **Server never starts at logon (start-at-login task):** open `taskschd.msc`, find `remote-for-herdr` and check its "Last Run Result" (1 means the launcher could not start node at all), then `<home>\logs\server.log`. After moving the install or upgrading/reinstalling Node, run `remote-for-herdr install-task` again: the launcher holds the full paths to both.
159
+ - **"needs setup" / server exits at start:** config is missing or invalid. Run `remote-for-herdr setup`. Neither the supervisor nor the start-at-login task restarts it in this case.
160
+ - **"remote-for-herdr is already running (pid N) — use "remote-for-herdr stop" first."**: `server.pid` names a live process and something answers on the configured port, so a copy for this home is most likely running. Leave it, or stop it first. A pid file left behind by a logoff or shutdown is replaced automatically when nothing answers on the port. If remote-for-herdr isn't actually running (another program holds the port), delete `<home>\server.pid` (the message prints the full path); the same hint follows a `stop` that times out.
161
+ - **"port 4780 already in use — is remote-for-herdr already running?"** in the log: another copy (or another program) holds the port. Run `remote-for-herdr stop`, or free the port. Neither restarts it in this case either.
162
+ - **"remote-for-herdr is running — stop it first: remote-for-herdr stop"** from setup: stop the server, run setup, then start it again.
163
+ - **No push:** the address must be the https `ts.net` one (HTTPS certificates enabled); notification permission must be allowed in Android/Chrome site settings; desk mode must be off; the matching trigger must be on in Settings; and you must have tapped Enable notifications on this device after the last setup change.
164
+ - **Messages arrive as if from an agent terminal, or new terminals get a parent:** remote-for-herdr strips `HC_TERMINAL_ID`, `HC_TERMINAL_SOCKET` and `HC_SCOPE` from every `hc` it runs, so messages are sent as from a plain client even when remote-for-herdr is started inside a Herdr terminal.
165
+ - **`hc` not found:** put herdr-core's folder (default `%LOCALAPPDATA%\Programs\herdr-core\`) on PATH, or re-run setup and give the full path to `hc`.
166
+ - **Send says a dialog is open / `Type into dialog` appears:** the session is showing a question or permission prompt, and Herdr refuses plain typing there. Answer with the key bar, or choose "Type something" and use the two-tap confirm (see Using it). "A dialog just opened — wait a moment" means Herdr refused a plain send because a dialog opened a moment ago; the button turns on once the list shows the dialog.
167
+ - **"The dialog changed — nothing was sent."**: between your two taps the dialog was answered, closed or replaced by another one. Nothing reached the agent. Look at the terminal and try again.
168
+ - **"May or may not have been delivered — check the terminal before resending"**: `hc` did not answer in time. The text may still have arrived; look at the terminal before sending it again.
169
+ - **Start-at-login does not start it:** run `remote-for-herdr install-task` again, then check `schtasks /Query /TN remote-for-herdr /V /FO LIST` (its "Run As User" must be your account) and the log file.
170
+
171
+ ## Uninstall
172
+
173
+ 1. `remote-for-herdr stop`, then `remote-for-herdr uninstall-task` (removes the login task, and an old `herdr-remote` one).
174
+ 2. `tailscale serve --https=443 off` (stops exposing it).
175
+ 3. Delete `%APPDATA%\remote-for-herdr` (config, PIN hash, keys, logs).
176
+ 4. `npm rm -g remote-for-herdr` (or delete the folder, for a source checkout).
177
+ 5. Remove the app icon from the phone.
178
+
179
+ ## Advanced: other networks (unsupported)
180
+
181
+ `remote-for-herdr setup --proxy` sets `access: "proxy"` for people who put their own HTTPS front end (Cloudflare Tunnel with Access, a reverse proxy on a VPN, ...) in front of the server. This is not tested beyond a local smoke test and not supported. You are responsible for TLS and for keeping it off the open internet.
182
+
183
+ - The Tailscale identity check is off. The PIN is still required, with rate limiting, Secure cookies and the Origin check.
184
+ - Setup asks for the public origin (for example `https://remote.example.com`) and optionally one identity header and the value to trust (for example `Cf-Access-Authenticated-User-Email` = `you@example.com`).
185
+ - The server still binds `127.0.0.1` unless you explicitly set `bind` in `config.json`.
186
+
187
+ ## Memory
188
+
189
+ Measured on Windows 11 with Node 22.13.1, idle after 20 s and then with one live view open on a terminal printing 3 bursts of 20,000 lines (working set / private bytes, MB). Every child also has its own hidden `conhost.exe` (about 7.5 / 1.2 MB each), counted in the totals.
190
+
191
+ | Way to run | Supervisor (node) | Server (node) | hc events | hc attach (1 live view) | Total with conhosts |
192
+ |---|---|---|---|---|---|
193
+ | Before this change: `remote-for-herdr start` and the start-at-login task (supervisor + server) | 46.5 / 55.6 | 50.9 / 56.6 | 11.3 / 1.7 | 11.3 / 1.7 | 149.6 / 120.4 |
194
+ | Now: `remote-for-herdr start` (unchanged, supervisor + server) | 46.7 / 55.3 | 51.4 / 57.3 | 11.4 / 1.7 | 11.3 / 1.7 | 150.4 / 120.8 |
195
+ | Now: start-at-login task (`start --foreground --log`) | none | 51.1 / 57.1 | 11.4 / 1.7 | 11.4 / 1.7 | 96.0 / 64.1 |
196
+
197
+ So the start-at-login task now uses about 53.6 MB less working set and 56.3 MB less private memory than before (149.6 / 120.4 down to 96.0 / 64.1: the supervisor's Node process and its console host are gone); the hidden `wscript.exe` launcher stays resident to restart the server (not measured here). Node/V8 flags were tried on the server and none is used (`SERVER_NODE_FLAGS` in `src/supervisor.js` is empty): `--max-semi-space-size=1`, `--optimize-for-size`, `--max-old-space-size=128`, `--v8-pool-size=1` and their combination each changed the server by less than 2 MB with the same burst latency (about 250 ms), and `--lite-mode` stops it from starting at all (it turns off WebAssembly, and Node 22 then throws as soon as the server imports `node:http`, which loads its bundled undici).
198
+
199
+ ## Development
200
+
201
+ From a clone of [the repository](https://github.com/julsxxzz/remote-for-herdr): `npm install`, then `node src/cli.js <command>` (`npm run setup`, `npm start` work too). `npm test` runs the unit tests against a fake `hc`. `npm run dev` runs the server in the foreground with config in `.dev/`.
202
+
203
+ The installed app (manifest) is named "remote-for-herdr"; its home-screen label (`short_name`) is "Herdr Remote", kept to 12 characters so Android does not cut it off under the icon.
204
+
205
+ ## Licence
206
+
207
+ Apache-2.0, see [LICENSE](LICENSE). Unofficial; not affiliated with Herdr.
@@ -0,0 +1,39 @@
1
+ # Manual end-to-end checklist (real Android phone)
2
+
3
+ Owner checks that cannot be automated. Record results in the "Tested" line of the README.
4
+
5
+ - [ ] Run `remote-for-herdr setup` in tailscale mode; open the `ts.net` URL on Android Chrome.
6
+ - [ ] Enter the PIN; the session list loads.
7
+ - [ ] Add to Home screen; open from the icon.
8
+ - [ ] Settings, Enable notifications; Send test notification arrives.
9
+ - [ ] Let a Claude Code session finish a turn with the phone locked; the "finished" push arrives.
10
+ - [ ] Tap the push; it opens that session's live view.
11
+ - [ ] Send a reply from the phone; it appears on the PC within about 1 s.
12
+ - [ ] Make Claude Code ask a question with options (e.g. "Use the AskUserQuestion tool to ask me which colour I prefer, with options Red and Blue."). When the session shows as needing you, the Send button reads `Type into dialog` and the hint about "Type something" shows under the reply box.
13
+ - [ ] Press the "Type something" option's number on the key bar, type an answer, tap `Type into dialog`: it turns to a highlighted `Tap again to type` and nothing is sent. Wait 2 s: it goes back. Tap twice: the answer reaches Claude Code.
14
+ - [ ] While armed, edit the text: it disarms. In a session that isn't showing a dialog, Send sends on the first tap as before.
15
+ - [ ] A permission prompt that shows as blocked also gets `Type into dialog` with the same two-tap confirm.
16
+ - [ ] Two taps with the keyboard up: the keyboard stays up through both taps (and through key-bar taps), and the Send button does not move while its label changes.
17
+ - [ ] Tap `Type into dialog` twice very quickly (under half a second): the second tap is ignored, the button stays `Tap again to type`; a slower second tap types.
18
+ - [ ] Arm, then answer the dialog on the PC (or let it change) before the second tap: nothing is sent and the app says the dialog changed / closed.
19
+ - [ ] Arm, then press a key-bar key: it disarms.
20
+ - [ ] Tap the reply box while a dialog shows: the answering layout hides the header details and zoom buttons, and the dialog stays visible in the terminal.
21
+ - [ ] Turn desk mode on; no push arrives.
22
+ - [ ] Open a wide terminal (about 200 columns): fits at half size and pans; zooming in and landscape both help.
23
+ - [ ] On that wide terminal, pinch out and in with two fingers: text zooms around your fingers (25% to 200%), the page itself never zooms, and one finger still scrolls and pans.
24
+ - [ ] Tap `+` and `−`: the zoom steps up and down and the middle button shows the percentage. Tap it: back to `Fit`.
25
+ - [ ] Set a zoom, reload the page (or close and reopen the app): the same zoom is back.
26
+ - [ ] In a session with long output, drag down with one finger: it scrolls past the screen into older output (history), and a flick keeps it gliding and slowing down.
27
+ - [ ] While scrolled up, new output arrives without pulling the view down; `↓ Latest` shows at the bottom right and tapping it jumps to the newest output (the button then hides).
28
+ - [ ] While scrolled up or while a flick is still gliding, the key bar, the reply box and `↓ Latest` still take taps; touching the terminal stops a flick.
29
+ - [ ] After scrolling into history, start a drag on the far right edge of the terminal (where the thin scrollbar shows): it scrolls once with your finger, no jump.
30
+ - [ ] Pull down hard at the very top of the history in the live view: the page never reloads. On the session list, pull-to-refresh reloads as usual.
31
+ - [ ] Pinch at the bottom edge of the terminal with one finger landing on the key bar: no key is sent and no zoom jump happens.
32
+ - [ ] Key bar shows `1 2 3 4 ↑ ↓` / `Enter Tab ⇧Tab ← → Esc`; a successful key shows a brief ✓, a successful reply shows `Sent ✓`; in landscape the keys are one row.
33
+ - [ ] `node src/cli.js install-task`, then reboot or log off and on: the server is running. Then `uninstall-task` removes it.
34
+ - [ ] After `install-task` and a log on: Task Manager shows one `node` for remote-for-herdr (no supervisor), plus `hc` and the hidden `wscript.exe` launcher. End that `node` task: within a few seconds it is back (the phone reconnects, a new `starting (pid …)` line is in `<home>\logs\server.log`). End it twice more, each time within a minute of it coming back (kill again within a minute): it still comes back, after 2 s, then 4 s.
35
+ - [ ] With the task running, `node src/cli.js stop` prints `stopped`, the server is gone and stays gone (no restart a minute later), and no `wscript.exe` is left.
36
+ - [ ] With the task running, end the `node` task and run `node src/cli.js stop` within a second (it prints `not running`): the server does not come back, no `wscript.exe` is left and `<home>\server.stop` is gone.
37
+ - [ ] With the task running, `node src/cli.js uninstall-task`: no `wscript.exe` left; `node` keeps running until `node src/cli.js stop`.
38
+ - [ ] The PIN prompt in `remote-for-herdr setup` hides the typed characters in a real terminal.
39
+ - [ ] Does Herdr ever report `blocked` for a Claude Code permission prompt? (Design spec section 7, risk 2. If never, a permission dialog mid-turn stays "working" and needs a fallback.)
package/package.json CHANGED
@@ -1,6 +1,51 @@
1
- {
2
- "name": "remote-for-herdr",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
1
+ {
2
+ "name": "remote-for-herdr",
3
+ "version": "0.1.0",
4
+ "description": "Unofficial phone web app for Herdr: watch and answer your coding-agent terminals from your phone over Tailscale, with push notifications",
5
+ "keywords": [
6
+ "herdr",
7
+ "coding-agents",
8
+ "claude-code",
9
+ "tailscale",
10
+ "remote",
11
+ "phone",
12
+ "terminal"
13
+ ],
14
+ "homepage": "https://github.com/julsxxzz/remote-for-herdr#readme",
15
+ "bugs": {
16
+ "url": "https://github.com/julsxxzz/remote-for-herdr/issues"
17
+ },
18
+ "repository": {
19
+ "type": "git",
20
+ "url": "git+https://github.com/julsxxzz/remote-for-herdr.git"
21
+ },
22
+ "type": "module",
23
+ "license": "Apache-2.0",
24
+ "engines": {
25
+ "node": ">=22"
26
+ },
27
+ "bin": {
28
+ "remote-for-herdr": "src/cli.js",
29
+ "herdr-remote": "src/cli.js"
30
+ },
31
+ "files": [
32
+ "src/",
33
+ "public/",
34
+ "README.md",
35
+ "LICENSE",
36
+ "docs/e2e-checklist.md"
37
+ ],
38
+ "scripts": {
39
+ "start": "node src/cli.js start",
40
+ "setup": "node src/cli.js setup",
41
+ "dev": "node src/cli.js start --foreground --home .dev",
42
+ "test": "node --test \"test/*.test.js\"",
43
+ "prepublishOnly": "npm test"
44
+ },
45
+ "dependencies": {
46
+ "@xterm/xterm": "^6.0.0",
47
+ "uqr": "^0.1.3",
48
+ "web-push": "^4.0.0",
49
+ "ws": "^8.23.0"
50
+ }
51
+ }
package/public/api.js ADDED
@@ -0,0 +1,33 @@
1
+ // REST helper. Every call goes through api(); any 401 (except a wrong PIN) hands control to the sign-in screen.
2
+
3
+ let onSignedOut = () => {};
4
+
5
+ export function setSignedOutHandler(fn) {
6
+ onSignedOut = fn;
7
+ }
8
+
9
+ export function signedOut() {
10
+ onSignedOut();
11
+ }
12
+
13
+ export async function api(path, { method = 'GET', body } = {}) {
14
+ const init = { method, credentials: 'same-origin', headers: {} };
15
+ if (method !== 'GET' && method !== 'HEAD') {
16
+ init.headers['content-type'] = 'application/json';
17
+ init.body = JSON.stringify(body ?? {});
18
+ }
19
+ let res;
20
+ try {
21
+ res = await fetch(path, init);
22
+ } catch {
23
+ return { ok: false, status: 0, data: { error: 'offline' } };
24
+ }
25
+ let data = null;
26
+ if (res.status !== 204) {
27
+ try { data = await res.json(); } catch { data = null; }
28
+ }
29
+ if (res.status === 401 && path !== '/api/login') onSignedOut();
30
+ return { ok: res.ok, status: res.status, data };
31
+ }
32
+
33
+ export const terminalPath = (address, action) => `/api/terminals/${encodeURIComponent(address)}/${action}`;