dsh-screensaver 0.0.0-stage → 0.3.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 +21 -0
- package/LICENSE-ASSETS.md +43 -0
- package/README.md +212 -2
- package/README.zh-CN.md +182 -0
- package/app/agents.js +745 -0
- package/app/dirs.js +14 -0
- package/app/helper.js +62 -0
- package/app/lidawake.js +205 -0
- package/app/main.js +140 -0
- package/app/paths.js +60 -0
- package/app/preload.cjs +21 -0
- package/app/saver.js +460 -0
- package/app/shell/index.html +70 -0
- package/app/shell/main.js +169 -0
- package/app/themes.js +95 -0
- package/assets/icon.png +0 -0
- package/bin/dsh-screensaver.js +42 -0
- package/cordis.patch.yml +23 -0
- package/docs/themes.md +63 -0
- package/lib/bridge.js +74 -0
- package/lib/cli.js +167 -0
- package/lib/command.js +71 -0
- package/lib/index.js +67 -0
- package/lib/launcher.js +88 -0
- package/lib/lines.js +10 -0
- package/lib/settings.js +94 -0
- package/lib/tool.js +44 -0
- package/llms.txt +50 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/native/unlock/main.swift +277 -0
- package/package.json +95 -4
- package/themes/basic/LICENSE +6 -0
- package/themes/basic/index.html +56 -0
- package/themes/basic/saver.json +1 -0
- package/themes/subspace/LICENSE +9 -0
- package/themes/subspace/README.md +52 -0
- package/themes/subspace/THIRD_PARTY_NOTICES.md +15 -0
- package/themes/subspace/index.html +4512 -0
- package/themes/subspace/saver.json +1 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 realRoc
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Visual assets license / 视觉素材授权
|
|
2
|
+
|
|
3
|
+
**Code is MIT. Visual assets are CC BY-NC-SA 4.0: no commercial use.**
|
|
4
|
+
**代码是 MIT;视觉素材是 CC BY-NC-SA 4.0,禁止商用。**
|
|
5
|
+
|
|
6
|
+
## What is a visual asset here / 哪些算视觉素材
|
|
7
|
+
|
|
8
|
+
| Path | What | License |
|
|
9
|
+
| --- | --- | --- |
|
|
10
|
+
| `themes/**` (every theme: `basic` Clock, `subspace` Subspace Jump, and future themes in this repo) | The theme's visual design and everything that draws it: HTML, CSS, scenes, shaders, animation, generated `index.html` | [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) |
|
|
11
|
+
| `docs/images/**`, `assets/icon.png` | Screenshots, plugin icon | [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) |
|
|
12
|
+
| Everything else: `app/`, `lib/`, `bin/`, `native/`, `test/`, docs text | The screen saver engine, dsh plugin, Touch ID helper, session detection, theme API | [MIT](LICENSE) |
|
|
13
|
+
|
|
14
|
+
| 路径 | 内容 | 授权 |
|
|
15
|
+
| --- | --- | --- |
|
|
16
|
+
| `themes/**`(本仓库所有主题:基础版「时钟」、「亚空间跃迁」,以及以后加进来的) | 主题的视觉设计和画出它的一切:HTML、CSS、场景、着色器、动画、打包出来的 `index.html` | [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/deed.zh-hans) |
|
|
17
|
+
| `docs/images/**`、`assets/icon.png` | 截图、插件图标 | [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/deed.zh-hans) |
|
|
18
|
+
| 其余:`app/`、`lib/`、`bin/`、`native/`、`test/`、文档文字 | 屏保引擎、dsh 插件、Touch ID 小程序、会话识别、主题接口 | [MIT](LICENSE) |
|
|
19
|
+
|
|
20
|
+
## You may / 你可以
|
|
21
|
+
|
|
22
|
+
- Use, modify and share the themes in personal, open-source and other **non-commercial** projects, with attribution
|
|
23
|
+
(`realRoc/dsh-screensaver`), and share adaptations under CC BY-NC-SA 4.0.
|
|
24
|
+
- **Not** use them commercially: no selling, no bundling into paid products or services, no use in ads. For commercial
|
|
25
|
+
use, ask the author first (open an issue).
|
|
26
|
+
- Build your own themes on the MIT theme API and license them however you like.
|
|
27
|
+
|
|
28
|
+
- 在个人、开源等**非商业**项目里使用、修改、再分发这些主题,须署名(`realRoc/dsh-screensaver`),改编后的作品须以 CC BY-NC-SA 4.0 发布;
|
|
29
|
+
- **不能商用**:不能卖、不能放进收费的产品或服务、不能用在广告里。商用请先联系作者(开 issue);
|
|
30
|
+
- 用 MIT 的主题接口自己做主题,授权你自己定。
|
|
31
|
+
|
|
32
|
+
## Third-party content inside themes / 主题里的第三方内容
|
|
33
|
+
|
|
34
|
+
These keep their own terms and are not covered by the CC license above:
|
|
35
|
+
|
|
36
|
+
- **three.js** (bundled in `themes/subspace/index.html`): MIT, © three.js authors.
|
|
37
|
+
- **DeepSeek Harness whale** (`themes/subspace/assets/dsh.svg`): MIT, © 2026 DeepSeek (`@deepseek-ai/dsh-web-frontend`).
|
|
38
|
+
- **Claude mark** (`assets/claude.png`) and **Codex app icon** (`assets/codex.png`): trademarks of Anthropic and OpenAI.
|
|
39
|
+
The DeepSeek whale is also a DeepSeek trademark. They are used only to identify which product a session belongs to.
|
|
40
|
+
This project is not affiliated with or endorsed by these companies.
|
|
41
|
+
|
|
42
|
+
以上第三方内容按各自的条款,不在上面的 CC 授权范围内:three.js 是 MIT;DeepSeek Harness 鲸鱼图标是 MIT(© 2026 DeepSeek);
|
|
43
|
+
Claude、Codex 图标和 DeepSeek 鲸鱼是各自公司的商标,只用来标出会话属于哪个产品,本项目与这些公司没有关联。
|
package/README.md
CHANGED
|
@@ -1,3 +1,213 @@
|
|
|
1
|
-
#
|
|
1
|
+
# dsh-screensaver: a macOS screen saver that keeps AI coding agents running while you're away
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
You step away for coffee, a meeting or lunch. Claude Code, Codex or DeepSeek Harness is still working, and you don't
|
|
4
|
+
want people reading your screen. dsh-screensaver covers it with a lock screen that looks like the Mac's own; touch
|
|
5
|
+
Touch ID to unlock when you're back. While it's up the Mac doesn't sleep, the display stays on, and it can stay awake
|
|
6
|
+
with the lid closed too. Themes can show each live **Claude Code**, **OpenAI Codex** and **DeepSeek Harness** session:
|
|
7
|
+
running, waiting for your approval, finished or stopped.
|
|
8
|
+
|
|
9
|
+
It is a [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) plugin, and it also runs on its own
|
|
10
|
+
with `npx`.
|
|
11
|
+
|
|
12
|
+
[中文说明](README.zh-CN.md) · [llms.txt (summary for AI assistants)](llms.txt) · [Theme API](docs/themes.md) · [Visual assets license](LICENSE-ASSETS.md)
|
|
13
|
+
|
|
14
|
+

|
|
15
|
+
|
|
16
|
+
| Clock (built in) | Subspace Jump (built in) |
|
|
17
|
+
| --- | --- |
|
|
18
|
+
|  | A three.js warp tunnel (above): when agents are running it jumps into subspace and lists each session with its own product icon. Inside, it drifts between a nebula storm, a vortex of ocean waves and a tunnel of Gaussian splats. |
|
|
19
|
+
|
|
20
|
+
## Why not the macOS screen saver, the lock screen, or a wallpaper?
|
|
21
|
+
|
|
22
|
+
The lock screen and the system screen saver assume the Mac can rest once you leave. dsh-screensaver assumes your agents
|
|
23
|
+
keep working and you only want the screen covered.
|
|
24
|
+
|
|
25
|
+
| | macOS lock screen (⌃⌘Q) | macOS screen saver | Wallpaper / live wallpaper | `caffeinate` / Amphetamine | **dsh-screensaver** |
|
|
26
|
+
| --- | --- | --- | --- | --- | --- |
|
|
27
|
+
| Covers the screen from passers-by | Yes (real system lock) | Yes, until a key is pressed (lock only if "require password") | No | No | **Yes** (a cover, not a security boundary) |
|
|
28
|
+
| CLI agents in a terminal (Claude Code, Codex CLI, dsh) keep running | Yes | Yes | Yes | Yes | **Yes** |
|
|
29
|
+
| Computer-use agents and extension-driven browsers keep running | No, they stop ([openai/codex#58545](https://github.com/openai/codex/issues/58545), [openai/codex#43869](https://github.com/openai/codex/issues/43869)) | Not tested | Yes | Yes | **Browser-extension agents keep running**; anything that must click the screen is covered |
|
|
30
|
+
| Covered browser windows keep full speed | No, the system treats them as hidden | Not tested | n/a | n/a | **Yes**: the cover is a tiny bit translucent, so the system still treats windows as visible |
|
|
31
|
+
| Prevents display sleep and system idle sleep | No: the display soon goes dark, and whether the Mac then sleeps depends on other apps ([anthropics/claude-code#81832](https://github.com/anthropics/claude-code/issues/81832)) | No | No | Yes | **Yes, while it is up** |
|
|
32
|
+
| Stays awake with the **lid closed** | No | No | No | No (sleep assertions cannot stop lid sleep) | **Yes, on by default** once you allow it (`pmset disablesleep` with a one-time admin authorization, auto-restored) |
|
|
33
|
+
| Unlock | Touch ID or password | Key press (+ password) | n/a | n/a | **Just touch Touch ID**, or press any key / click for Touch ID or the login password |
|
|
34
|
+
| Shows what your agents are doing | No | No | No | No | **Yes** (themes that opt in: names, current step, running / waiting / done / stopped) |
|
|
35
|
+
|
|
36
|
+
In a café or a shared office where you need real security and only run terminal agents, use ⌃⌘Q (run
|
|
37
|
+
`/screensaver lid on` first if you also want lid-closed awake). At home, or when you run computer-use or browser agents,
|
|
38
|
+
use dsh-screensaver.
|
|
39
|
+
|
|
40
|
+
> dsh-screensaver is **not a security boundary**: holding the power button still works, and it does not replace the
|
|
41
|
+
> macOS login. It keeps people walking by from reading your screen or typing into your agents.
|
|
42
|
+
|
|
43
|
+
## Install
|
|
44
|
+
|
|
45
|
+
### As a DeepSeek Harness plugin
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
dsh plugin --profile web add dsh-screensaver
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Use `desktop` instead of `web` for the desktop app profile, then restart dsh. The first start downloads the Electron
|
|
52
|
+
runtime (about 100 MB, once) and compiles the Touch ID helper if the Xcode Command Line Tools are installed.
|
|
53
|
+
|
|
54
|
+
Both themes, Clock and Subspace Jump, ship inside this package; there is nothing else to install.
|
|
55
|
+
|
|
56
|
+
Want the latest unreleased code from GitHub instead of the npm release:
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
dsh plugin --profile web add github:realRoc/dsh-screensaver
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### Without dsh
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
npx dsh-screensaver --now # cover the screen now, exit after you unlock
|
|
66
|
+
npx dsh-screensaver # stay in the background, press ⌃⌥⌘L to start
|
|
67
|
+
npx dsh-screensaver --now subspace # with a theme
|
|
68
|
+
npx dsh-screensaver setup # settings: lid-closed awake (and its one-time authorization), theme, idle start
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Requirements: macOS 12 or later, Node.js 22 or later. Touch-to-unlock needs a Mac with Touch ID (or a Magic Keyboard with
|
|
72
|
+
Touch ID) and the Xcode Command Line Tools (`xcode-select --install`); without them the system Touch ID / password dialog
|
|
73
|
+
is used instead.
|
|
74
|
+
|
|
75
|
+
## Use
|
|
76
|
+
|
|
77
|
+
- **Start:** ⌃⌥⌘L (Control+Option+Command+L), `/screensaver` in dsh, or ask your agent ("I'm stepping away, cover the
|
|
78
|
+
screen"); it calls the `screensaver` tool. You can also start it automatically after N idle minutes.
|
|
79
|
+
- **Unlock:** touch the Touch ID sensor. Pressing any key or clicking opens the system dialog (Touch ID or login password).
|
|
80
|
+
- **Pure mode:** after 30 seconds without input, the hint, the status bar and the session list fade out and only the
|
|
81
|
+
animation is left. Moving the mouse, pressing a key or touching Touch ID brings them back.
|
|
82
|
+
|
|
83
|
+
| Command | What it does |
|
|
84
|
+
| --- | --- |
|
|
85
|
+
| `/screensaver` | Start with the default theme |
|
|
86
|
+
| `/screensaver <theme>` | Start with a theme, e.g. `/screensaver subspace` |
|
|
87
|
+
| `/screensaver themes` | List installed themes |
|
|
88
|
+
| `/screensaver lid` | Show lid-closed awake status |
|
|
89
|
+
| `/screensaver lid authorize` | Allow lid-closed awake (asks for an admin password once; installs a sudoers rule that only allows `pmset -a disablesleep 0/1`) |
|
|
90
|
+
| `/screensaver lid on` / `off` | Turn lid-closed awake on or off by hand |
|
|
91
|
+
| `/screensaver lid revoke` | Remove the sudoers rule |
|
|
92
|
+
|
|
93
|
+
### Configuration
|
|
94
|
+
|
|
95
|
+
Add an entry to your profile's `~/.dsh/profiles/<profile>/cordis.patch.yml` (it replaces the whole config block):
|
|
96
|
+
|
|
97
|
+
```yaml
|
|
98
|
+
- id: dsh-screensaver
|
|
99
|
+
config:
|
|
100
|
+
theme: subspace # default theme id
|
|
101
|
+
idleMinutes: 10 # start after 10 idle minutes; 0 = never (default)
|
|
102
|
+
lidAwake: true # keep the Mac awake with the lid closed while the screen saver is up (default; false turns it off)
|
|
103
|
+
shortcut: Control+Alt+Command+L # Electron accelerator; '' disables the shortcut
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Standalone, the same fields live in `~/.dsh/plugins-data/dsh-screensaver/config.json`:
|
|
107
|
+
|
|
108
|
+
| Command | What it does |
|
|
109
|
+
| --- | --- |
|
|
110
|
+
| `dsh-screensaver setup` | Walk through lid-closed awake (authorizes it on the spot), the theme and idle start |
|
|
111
|
+
| `dsh-screensaver config` | Show the settings and the file they are saved in |
|
|
112
|
+
| `dsh-screensaver config <key> <value>` | Change one, e.g. `config lidAwake off`, `config idleMinutes 10` |
|
|
113
|
+
| `dsh-screensaver config unset <key>` | Back to the default |
|
|
114
|
+
| `dsh-screensaver lid [status\|authorize\|revoke]` | Lid-closed awake authorization, same as `/screensaver lid` |
|
|
115
|
+
| `dsh-screensaver themes` | List installed themes |
|
|
116
|
+
|
|
117
|
+
`DSH_SCREENSAVER_CONFIG='{"theme":"subspace"}'` overrides the file for one run. A `--now` handed to a screen saver that is
|
|
118
|
+
already running (for example the one inside dsh) brings its `lidAwake` along for that start when it sets one (in the file or the variable); otherwise the running one
|
|
119
|
+
uses its own config.
|
|
120
|
+
|
|
121
|
+
## Themes
|
|
122
|
+
|
|
123
|
+
| Theme | id | Ships with | Shows agent sessions |
|
|
124
|
+
| --- | --- | --- | --- |
|
|
125
|
+
| Clock | `basic` | built in | No |
|
|
126
|
+
| Subspace Jump | `subspace` | built in | Yes |
|
|
127
|
+
|
|
128
|
+
More themes are coming. Themes are visual works licensed CC BY-NC-SA 4.0 (no commercial use). A theme is a folder with an `index.html` (runs in a sandboxed iframe, draws only) and a
|
|
129
|
+
`saver.json`. Put your own in `~/.dsh/plugins-data/dsh-screensaver/themes/<id>/`, or publish it as an npm package with
|
|
130
|
+
`"dsh-screensaver": { "theme": "." }` in its `package.json`. See [docs/themes.md](docs/themes.md).
|
|
131
|
+
|
|
132
|
+
## Which agent sessions are detected
|
|
133
|
+
|
|
134
|
+
Only themes that set `"sessions": true` receive sessions, and only while the screen saver is up. Everything is read from
|
|
135
|
+
local files every 2 seconds; nothing is sent anywhere.
|
|
136
|
+
|
|
137
|
+
| Agent | Where it reads | Running / waiting |
|
|
138
|
+
| --- | --- | --- |
|
|
139
|
+
| Claude Code | `~/.claude/sessions/<pid>.json`, `~/.claude/projects/**.jsonl` | process alive and status busy; waiting when status asks for permission or input |
|
|
140
|
+
| OpenAI Codex | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`, `~/.codex/session_index.jsonl` | `task_started` without `task_complete` / `turn_aborted` |
|
|
141
|
+
| DeepSeek Harness | `$DSH_HOME/sessions/*/*/session.v4.jsonl.zstd` + `session.lock` | a dsh process holds the session lock and the last `turn/start` has no `turn/end`; waiting on an open `approval/asked` or `ask_user_question` |
|
|
142
|
+
|
|
143
|
+
The theme shows each product's own icon (the Claude mark, the Codex app icon and the DeepSeek Harness whale) to label
|
|
144
|
+
sessions. They are trademarks of their owners and are used only to identify those products.
|
|
145
|
+
|
|
146
|
+
## How it works
|
|
147
|
+
|
|
148
|
+
- A small always-on-top window covers each display; the primary one runs in kiosk mode (hides the Dock and menu bar,
|
|
149
|
+
blocks ⌘Tab and Force Quit).
|
|
150
|
+
- `desk-unlock`, a Swift helper (`native/unlock/main.swift`), embeds the system Touch ID view (`LAAuthenticationView`) in
|
|
151
|
+
an invisible window above the screen saver, so touching the sensor unlocks with no dialog. With the lid closed the
|
|
152
|
+
built-in sensor is off, so it waits for the lid to open (`AppleClamshellState`) and listens again right away. It also reads battery and
|
|
153
|
+
Wi-Fi for the status bar (IOKit, CoreWLAN; no location permission, the network name is not read).
|
|
154
|
+
- While up: `powerSaveBlocker('prevent-display-sleep')`. With `lidAwake` (default) and the authorization: `pmset -a disablesleep 1`, restored when the
|
|
155
|
+
screen saver closes, when the process dies (a detached watchdog), at the next start if it was left on, and when the
|
|
156
|
+
battery drops to 20%.
|
|
157
|
+
|
|
158
|
+
## FAQ
|
|
159
|
+
|
|
160
|
+
**Will my Claude Code / Codex / DeepSeek Harness session keep running while the screen saver is on?**
|
|
161
|
+
Yes. Terminal agents are not affected at all, the Mac does not idle-sleep, and the display does not turn off.
|
|
162
|
+
|
|
163
|
+
**Does it work when I close the MacBook lid?**
|
|
164
|
+
Yes, after you allow it once: `/screensaver lid authorize` in dsh, or `dsh-screensaver lid authorize` (or `setup`)
|
|
165
|
+
standalone. `lidAwake` is on by default, so from then on every screen saver keeps the Mac awake with the lid closed;
|
|
166
|
+
set `lidAwake: false` to stop that.
|
|
167
|
+
Keep the Mac plugged in; it turns itself off at 20% battery.
|
|
168
|
+
|
|
169
|
+
**Is it a replacement for the macOS lock screen?**
|
|
170
|
+
No. It is a cover for when you step away at home or in the office and want your agents to keep working. For real
|
|
171
|
+
security use ⌃⌘Q.
|
|
172
|
+
|
|
173
|
+
**Do I need DeepSeek Harness?**
|
|
174
|
+
No. `npx dsh-screensaver` runs it standalone. dsh adds the `/screensaver` command, the agent tool and
|
|
175
|
+
config.
|
|
176
|
+
|
|
177
|
+
**Does it work on Windows or Linux?**
|
|
178
|
+
Not yet; it is macOS-only for now.
|
|
179
|
+
|
|
180
|
+
**Does it send data anywhere?**
|
|
181
|
+
No. It reads local session files and system status, and it makes no network requests (apart from the one-time
|
|
182
|
+
Electron download on first run).
|
|
183
|
+
|
|
184
|
+
## Develop
|
|
185
|
+
|
|
186
|
+
```bash
|
|
187
|
+
git clone https://github.com/realRoc/dsh-screensaver && cd dsh-screensaver
|
|
188
|
+
npm install
|
|
189
|
+
npm test # vitest
|
|
190
|
+
npm run now # try it
|
|
191
|
+
npm run build:themes # rebuild themes/subspace/index.html after editing themes/subspace/src
|
|
192
|
+
DSH_SCREENSAVER_DEBUG=1 npm run now # log page console messages
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
### Release
|
|
196
|
+
|
|
197
|
+
Pushing a `v*` tag runs [`.github/workflows/publish.yml`](.github/workflows/publish.yml), which tests and publishes
|
|
198
|
+
`dsh-screensaver` (themes included) to npm through Trusted Publishing (no token). A version already on npm is skipped.
|
|
199
|
+
|
|
200
|
+
1. Bump `version` in `package.json`. Rebuild `themes/subspace/index.html` first if the theme source changed.
|
|
201
|
+
2. Commit and push to `main`.
|
|
202
|
+
3. Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z`. The tag must match the root `package.json` version.
|
|
203
|
+
|
|
204
|
+
## License
|
|
205
|
+
|
|
206
|
+
Code is MIT ([LICENSE](LICENSE)). All visual assets, meaning every theme under `themes/` and the screenshots under
|
|
207
|
+
`docs/images/`, are **CC BY-NC-SA 4.0: no commercial use** ([LICENSE-ASSETS.md](LICENSE-ASSETS.md)). Third-party notices:
|
|
208
|
+
[themes/subspace/THIRD_PARTY_NOTICES.md](themes/subspace/THIRD_PARTY_NOTICES.md).
|
|
209
|
+
|
|
210
|
+
<!-- Keywords: screen saver for AI coding agents, keep Claude Code running when away, keep Codex running, prevent Mac sleep
|
|
211
|
+
while an agent runs, macOS lock screen alternative, Touch ID screen saver, keep Mac awake with lid closed, caffeinate
|
|
212
|
+
alternative, Amphetamine alternative, AFK screen for developers, DeepSeek Harness plugin, dsh plugin, agent session
|
|
213
|
+
monitor, Claude Code status screen, Codex status screen, 屏保, 锁屏, 防休眠, 合盖不睡 -->
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
# dsh-screensaver:让 AI agent 在你离开时继续工作的 macOS 屏保
|
|
2
|
+
|
|
3
|
+
起身倒杯水、开个会、出门吃饭,Claude Code、Codex、DeepSeek Harness 这些 AI coding agent 还在跑,屏幕却不想让人看见。
|
|
4
|
+
dsh-screensaver 就是为这种时候做的:样子跟 Mac 锁屏一样,回来摸一下 Touch ID 就解开;屏保期间电脑不睡、屏幕不黑,
|
|
5
|
+
合上盖子也可以不睡;主题还能实时显示每个 agent 会话在跑、在等你确认,还是已经结束。
|
|
6
|
+
|
|
7
|
+
它是 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(dsh)插件,不装 dsh 也能用 `npx` 单独运行。
|
|
8
|
+
|
|
9
|
+
[English](README.md) · [llms.txt(写给 AI 看的简介)](llms.txt) · [主题开发](docs/themes.md) · [视觉素材授权](LICENSE-ASSETS.md)
|
|
10
|
+
|
|
11
|
+

|
|
12
|
+
|
|
13
|
+
| 时钟(内置) | 亚空间跃迁(独立主题包) |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
|  | 用 three.js 画的跃迁隧道(见上图)。有 agent 在跑就进入亚空间,左侧列出每个会话,用各家产品自己的图标区分。亚空间里在星云雷暴、浪涌龙卷、高斯粒子三种画风之间自然切换。 |
|
|
16
|
+
|
|
17
|
+
## 和系统锁屏、系统屏保、动态壁纸有什么不同
|
|
18
|
+
|
|
19
|
+
系统锁屏和屏保默认你走开后电脑就该歇着;dsh-screensaver 假定 agent 还要继续干活,你只是不想让屏幕被人看见、被人碰。
|
|
20
|
+
|
|
21
|
+
| | 系统锁屏(⌃⌘Q) | 系统屏保 | 壁纸 / 动态壁纸 | caffeinate / Amphetamine | **dsh-screensaver** |
|
|
22
|
+
| --- | --- | --- | --- | --- | --- |
|
|
23
|
+
| 挡住路过的人 | 能,真正的系统锁 | 一碰就退出(勾了「需要密码」才会锁) | 不能 | 不能 | **能**(只是遮挡,不是安全措施) |
|
|
24
|
+
| 终端里的 agent(Claude Code、Codex CLI、dsh) | 照常运行 | 照常运行 | 照常运行 | 照常运行 | **照常运行** |
|
|
25
|
+
| computer use 类 agent、靠浏览器扩展驱动的 agent | 会停([openai/codex#58545](https://github.com/openai/codex/issues/58545)、[openai/codex#43869](https://github.com/openai/codex/issues/43869)) | 未测试 | 照常 | 照常 | **浏览器扩展类照常运行**;需要点击屏幕的操作会被挡住 |
|
|
26
|
+
| 被盖住的浏览器窗口不降频 | 会降频,系统认为窗口不可见 | 未测试 | — | — | **不降频**:屏保保留了一点点透明度,系统仍认为窗口可见 |
|
|
27
|
+
| 不熄屏、不进入空闲睡眠 | 不管:锁屏后很快熄屏,之后睡不睡取决于其他程序([anthropics/claude-code#81832](https://github.com/anthropics/claude-code/issues/81832)) | 不管 | 不管 | 管 | **屏保期间一直管** |
|
|
28
|
+
| 合盖不睡 | 不行 | 不行 | 不行 | 不行(防睡眠断言管不了合盖) | **默认开**,授权一次就生效(`pmset disablesleep`,退出后自动恢复) |
|
|
29
|
+
| 解锁 | Touch ID 或密码 | 按任意键(可能要输密码) | — | — | **直接摸 Touch ID**,或按键、点击后用 Touch ID / 登录密码 |
|
|
30
|
+
| 能看到 agent 在做什么 | 不能 | 不能 | 不能 | 不能 | **能**(支持会话的主题会显示名称、当前步骤和状态) |
|
|
31
|
+
|
|
32
|
+
在咖啡馆、办公室这类需要真正安全的地方,只跑终端 agent 的话用 ⌃⌘Q 更合适,需要合盖不睡可以先执行 `/screensaver lid on`。
|
|
33
|
+
在家临时走开,或者在跑 computer use、浏览器类 agent,就用 dsh-screensaver。
|
|
34
|
+
|
|
35
|
+
> dsh-screensaver 不是安全措施:长按电源键之类的操作拦不住,它也不能代替 macOS 登录密码。它防的是路过的人看到屏幕、碰到键盘。
|
|
36
|
+
|
|
37
|
+
## 安装
|
|
38
|
+
|
|
39
|
+
在 dsh 里使用:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
dsh plugin --profile web add dsh-screensaver
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
DeepSeek Harness 桌面版把 `web` 换成 `desktop`。装好后重启 dsh。第一次启动会下载 Electron 运行时(约 100 MB,只下载一次);
|
|
46
|
+
如果装了 Xcode 命令行工具,还会在本机编译 Touch ID 小程序。
|
|
47
|
+
|
|
48
|
+
「时钟」和「亚空间跃迁」两个主题都随包自带,不用另装。
|
|
49
|
+
|
|
50
|
+
想用 GitHub 上还没发布的最新代码,而不是 npm 上的发布版:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
dsh plugin --profile web add github:realRoc/dsh-screensaver
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
不装 dsh 也能用:
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
npx dsh-screensaver --now # 立即开启,解锁后退出
|
|
60
|
+
npx dsh-screensaver # 在后台待命,按 ⌃⌥⌘L 开启
|
|
61
|
+
npx dsh-screensaver setup # 改配置:合盖不睡(顺手授权)、主题、空闲自动开启
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
系统要求:macOS 12 及以上,Node.js 22 及以上。想「摸一下就解锁」,需要带 Touch ID 的 Mac(或带 Touch ID 的妙控键盘),
|
|
65
|
+
并装好 Xcode 命令行工具(`xcode-select --install`);条件不满足时会改用系统的 Touch ID / 密码验证框。
|
|
66
|
+
|
|
67
|
+
## 使用
|
|
68
|
+
|
|
69
|
+
- **开启**:按 ⌃⌥⌘L;在 dsh 里输入 `/screensaver`;或者直接对 agent 说「我走开一下,帮我把屏幕盖上」,它会调用 `screensaver` 工具。也可以设置空闲几分钟后自动开启。
|
|
70
|
+
- **解锁**:摸一下 Touch ID。按任意键或点一下鼠标,会弹出系统验证框,可以用 Touch ID 或登录密码。
|
|
71
|
+
- **纯享模式**:30 秒没有操作,底部提示、右上角状态栏和会话列表会淡出,只留下动画;动一下鼠标、按个键或摸 Touch ID 就会重新出现。
|
|
72
|
+
|
|
73
|
+
| 命令 | 作用 |
|
|
74
|
+
| --- | --- |
|
|
75
|
+
| `/screensaver` | 用默认主题开启 |
|
|
76
|
+
| `/screensaver <主题>` | 用指定主题开启,例如 `/screensaver subspace` |
|
|
77
|
+
| `/screensaver themes` | 查看已安装的主题 |
|
|
78
|
+
| `/screensaver lid` | 查看合盖不睡的状态 |
|
|
79
|
+
| `/screensaver lid authorize` | 授权合盖不睡:输入一次管理员密码,安装一条只允许 `pmset -a disablesleep 0/1` 的 sudoers 规则 |
|
|
80
|
+
| `/screensaver lid on` / `off` | 手动打开或关闭合盖不睡 |
|
|
81
|
+
| `/screensaver lid revoke` | 撤销授权,删除这条规则 |
|
|
82
|
+
|
|
83
|
+
### 配置
|
|
84
|
+
|
|
85
|
+
在 `~/.dsh/profiles/<profile>/cordis.patch.yml` 里加一段(会整段替换默认配置):
|
|
86
|
+
|
|
87
|
+
```yaml
|
|
88
|
+
- id: dsh-screensaver
|
|
89
|
+
config:
|
|
90
|
+
theme: subspace # 默认主题
|
|
91
|
+
idleMinutes: 10 # 空闲 10 分钟自动开启;0 表示不自动开启(默认)
|
|
92
|
+
lidAwake: true # 开启屏保时顺便打开合盖不睡(默认开,写 false 关掉)
|
|
93
|
+
shortcut: Control+Alt+Command+L # Electron 快捷键写法;填 '' 不注册快捷键
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
单独运行时,同样几项存在 `~/.dsh/plugins-data/dsh-screensaver/config.json`:
|
|
97
|
+
|
|
98
|
+
| 命令 | 作用 |
|
|
99
|
+
| --- | --- |
|
|
100
|
+
| `dsh-screensaver setup` | 一问一答:合盖不睡(当场授权)、主题、空闲自动开启 |
|
|
101
|
+
| `dsh-screensaver config` | 查看配置和配置文件位置 |
|
|
102
|
+
| `dsh-screensaver config <项> <值>` | 改一项,例如 `config lidAwake off`、`config idleMinutes 10` |
|
|
103
|
+
| `dsh-screensaver config unset <项>` | 改回默认 |
|
|
104
|
+
| `dsh-screensaver lid [status\|authorize\|revoke]` | 合盖不睡授权,同 `/screensaver lid` |
|
|
105
|
+
| `dsh-screensaver themes` | 查看已安装的主题 |
|
|
106
|
+
|
|
107
|
+
`DSH_SCREENSAVER_CONFIG='{"theme":"subspace"}'` 只对这一次生效,盖过配置文件。`--now` 交给已经在跑的屏保(比如 dsh 里那个)时,
|
|
108
|
+
如果这次写了 `lidAwake`(配置文件或环境变量里),会一起带过去;没写就按那个屏保自己的配置。
|
|
109
|
+
|
|
110
|
+
## 主题
|
|
111
|
+
|
|
112
|
+
| 主题 | id | 来源 | 显示 agent 会话 |
|
|
113
|
+
| --- | --- | --- | --- |
|
|
114
|
+
| 时钟 | `basic` | 内置 | 否 |
|
|
115
|
+
| 亚空间跃迁 | `subspace` | 内置 | 是 |
|
|
116
|
+
|
|
117
|
+
更多主题陆续推出。每个主题就是一个文件夹:`index.html` 负责绘制(运行在沙盒 iframe 里),`saver.json` 写名称等信息。
|
|
118
|
+
自己做的主题放进 `~/.dsh/plugins-data/dsh-screensaver/themes/<id>/` 就能用,也可以发布成 npm 包,在 `package.json` 里写上
|
|
119
|
+
`"dsh-screensaver": { "theme": "." }`。详见 [docs/themes.md](docs/themes.md)。
|
|
120
|
+
|
|
121
|
+
## 能识别哪些 agent 会话
|
|
122
|
+
|
|
123
|
+
只有声明了 `"sessions": true` 的主题才会收到会话信息,而且只在屏保开启时读取。每 2 秒读一次本机文件,不联网,不上传任何数据。
|
|
124
|
+
|
|
125
|
+
| Agent | 读取位置 | 怎么判断在运行 / 等你确认 |
|
|
126
|
+
| --- | --- | --- |
|
|
127
|
+
| Claude Code | `~/.claude/sessions/<pid>.json`、`~/.claude/projects/**.jsonl` | 进程存活且状态为 busy;请求权限或等待输入时算「等你确认」 |
|
|
128
|
+
| OpenAI Codex | `~/.codex/sessions/年/月/日/rollout-*.jsonl`、`~/.codex/session_index.jsonl` | 最后一个 `task_started` 之后没有 `task_complete` / `turn_aborted` |
|
|
129
|
+
| DeepSeek Harness | `$DSH_HOME/sessions/*/*/session.v4.jsonl.zstd` 和 `session.lock` | 有 dsh 进程持有会话锁,且最后一个 `turn/start` 之后没有 `turn/end`;有未处理的 `approval/asked` 或未回答的 `ask_user_question` 时算「等你确认」 |
|
|
130
|
+
|
|
131
|
+
主题用各家产品自己的图标区分会话(Claude 的标志、Codex 的 App 图标、DeepSeek Harness 的鲸鱼)。这些图标是各公司的商标,这里只用来标明会话来自哪个产品。
|
|
132
|
+
|
|
133
|
+
## 常见问题
|
|
134
|
+
|
|
135
|
+
**屏保开着的时候,Claude Code / Codex / DeepSeek Harness 会话会停吗?**
|
|
136
|
+
不会。终端里的 agent 完全不受影响,电脑不会空闲睡眠,屏幕也不会熄灭。
|
|
137
|
+
|
|
138
|
+
**合上 MacBook 盖子还能继续跑吗?**
|
|
139
|
+
可以,授权一次就行:dsh 里执行 `/screensaver lid authorize`,单独运行时执行 `dsh-screensaver lid authorize`(或 `setup`)。
|
|
140
|
+
`lidAwake` 默认开,之后每次开屏保都会合盖不睡;不想要就设 `lidAwake: false`。
|
|
141
|
+
建议插着电源;用电池且电量降到 20% 时会自动恢复睡眠。
|
|
142
|
+
|
|
143
|
+
**能代替 macOS 锁屏吗?**
|
|
144
|
+
不能。它适合在家或办公室临时走开、又想让 agent 继续工作的场景。需要真正的安全保护时,请用 ⌃⌘Q。
|
|
145
|
+
|
|
146
|
+
**一定要装 DeepSeek Harness 吗?**
|
|
147
|
+
不用。`npx dsh-screensaver` 可以单独运行。装在 dsh 里会多出 `/screensaver` 命令、agent 可调用的工具和配置项。
|
|
148
|
+
|
|
149
|
+
**支持 Windows 或 Linux 吗?**
|
|
150
|
+
暂时只支持 macOS。
|
|
151
|
+
|
|
152
|
+
**会上传数据吗?**
|
|
153
|
+
不会。它只读取本机的会话文件和系统状态,不发任何网络请求(第一次运行时下载 Electron 除外)。
|
|
154
|
+
|
|
155
|
+
## 开发
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
git clone https://github.com/realRoc/dsh-screensaver && cd dsh-screensaver
|
|
159
|
+
npm install
|
|
160
|
+
npm test # 运行测试(vitest)
|
|
161
|
+
npm run now # 立即开启屏保试一下
|
|
162
|
+
npm run build:themes # 修改 themes/subspace/src 后重新打包 index.html
|
|
163
|
+
DSH_SCREENSAVER_DEBUG=1 npm run now # 打印页面里的 console 输出
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
### 发版
|
|
167
|
+
|
|
168
|
+
推送 `v*` 标签会触发 [`.github/workflows/publish.yml`](.github/workflows/publish.yml):跑测试,再通过 Trusted Publishing(不用令牌)
|
|
169
|
+
把 `dsh-screensaver`(含主题)发到 npm。这个版本 npm 上已有就跳过。
|
|
170
|
+
|
|
171
|
+
1. 改 `package.json` 的 `version`。主题源码改过的话先重新打包 `themes/subspace/index.html`。
|
|
172
|
+
2. 提交并推送到 `main`。
|
|
173
|
+
3. 打标签并推送:`git tag vX.Y.Z && git push origin vX.Y.Z`。标签必须和根目录 `package.json` 的版本一致。
|
|
174
|
+
|
|
175
|
+
## 授权
|
|
176
|
+
|
|
177
|
+
代码采用 MIT;所有主题(`themes/`)和截图(`docs/images/`)等视觉素材采用 **CC BY-NC-SA 4.0,禁止商用**。
|
|
178
|
+
详见 [LICENSE-ASSETS.md](LICENSE-ASSETS.md)。
|
|
179
|
+
|
|
180
|
+
<!-- 关键词:AI agent 屏保,Claude Code 离开时继续运行,Codex 后台运行不休眠,Mac 防休眠,合盖不睡,Mac 合盖继续运行,
|
|
181
|
+
锁屏替代,Touch ID 解锁屏保,DeepSeek Harness 插件,dsh 插件,agent 会话监控,AI 编程助手挂机,caffeinate 替代,
|
|
182
|
+
Amphetamine 替代,macOS screensaver for AI coding agents -->
|