worktrust 0.11.7 → 0.11.8

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/README.md CHANGED
@@ -1,330 +1,214 @@
1
- # worktrust
2
-
3
- ## 0.11.7: a menu, folders without typing, and agent modes you allow here
4
-
5
- **A menu.** `npx worktrust` in your own terminal now opens a menu: move with the arrow keys, Enter opens, Esc or the left
6
- arrow goes back, q quits, 1 to 9 jump. The first item, Check this computer, does what the bare command did before
7
- (connect, or show what is connected). Every item shows the short command it runs, so you can type it next time. Without a
8
- terminal (a script, a hook, the MCP door) nothing changes and nothing waits for a key; every command works as before.
9
-
10
- **Remote Agent: approve with `remote app` or `remote web`.** `npx worktrust remote app` approves this computer with the
11
- WorkTrust app (a QR code here), `npx worktrust remote web` in the browser. Each makes the computer's remote keys, asks you
12
- first, sets up the service and shows the phone's QR code, with `--gateway` and `--device` as before. `remote enable` is
13
- gone: it now says which two commands to use. While you approve, a bar under the QR code or link counts the request's
14
- time down; when it runs out, Enter draws a new one. `npx worktrust remote connections` lists every phone and browser
15
- linked to this computer, and `remote disconnect` closes one (or `--all`), each after a typed confirmation.
16
-
17
- **Folders without typing.** In the menu, Remote Agent, Roots: tick the folders your projects live in (Desktop, Documents,
18
- Developer, Projects, code, src, each with the number of projects found), make a new folder for projects, or choose any
19
- folder with your system's folder picker. A phone can now open the projects that are already inside a root, not only make
20
- new ones. The rules stay: never your home folder or above it, never a folder of secrets. On a Mac, a folder in Desktop,
21
- Documents, Downloads or iCloud Drive makes macOS ask once, right away, whether the Remote Agent service may read it.
22
-
23
- **Agent modes, with a ceiling you set here.** A phone may start Manual (asks for every change) and Plan, as before.
24
- `npx worktrust remote modes allow edit` lets it start Edit automatically (Claude Code's acceptEdits), and
25
- `remote modes allow auto` Claude Code's auto mode (which includes edit); `remote modes deny edit` takes both back. The
26
- computer refuses any mode above what you allowed, whatever a phone sends. No push, no install, no deploy and no secret, in
27
- every mode; in Edit and Auto the agent also cannot edit its own rules or the files that say what a test runs. Claude Code's
28
- effort level and extra projects in one session (`--add-dir`) come along where your Claude Code offers them.
29
-
30
- No measure change: the measure rules stay 4.
31
-
32
- ## 0.11.6: approve a computer with your phone
33
-
34
- **Two roads to approve this computer for Remote Agent.** `npx worktrust remote app` shows the approval as a QR code in
35
- the terminal, without opening a browser: scan it with the WorkTrust app, check the code and key, accept Remote Agent's
36
- terms and approve with your authenticator code. `npx worktrust remote web` opens the approval page in your browser, as
37
- before. (Until 0.11.7, `npx worktrust remote enable` asked which one you want.) A request lives ten minutes; the page and the app count
38
- it down and tell you when to run the command again.
39
-
40
- **A command the CLI does not know** now says so ("Unknown command: …") before the help, and ends with a failure code.
41
-
42
- No measure change: the measure rules stay 4.
43
-
44
- ## 0.11.5: Remote Agent (the new name), and a link needs your authenticator
45
-
46
- **Remote Agent.** What was called MOCHI is now called Remote Agent everywhere you read it: in this CLI's messages, in
47
- Settings › Remote Agent on app.worktrust.io and on your phone, where its tab is Devs. Its terms moved to
48
- worktrust.io/remote-agent-terms; the old address forwards there. Nothing it does changed.
49
-
50
- **A link needs your authenticator.** Approving this computer on app.worktrust.io, and adding a new phone or browser, now
51
- asks for a code from your authenticator app; an e-mailed code no longer does. A link stays with the account and the phone
52
- that made it, and it ends when you remove that authenticator. A phone asked by code is still confirmed at this keyboard:
53
- `npx worktrust remote phones confirm <fingerprint>`. What is measured for the passport is unchanged: the measure rules
54
- stay 4.
55
-
56
- ## 0.11.4: local models measured, confidential client work, OpenCode in Remote Agent
57
-
58
- **Local models, used directly.** The Ollama app's chats and Open WebUI's are now read like every other database client:
59
- the model, the time of each turn and, for Open WebUI, the token counts it kept (the Ollama app keeps none, so none are
60
- sent or estimated). Never a title, a message, a file or a prompt. A model used through OpenCode, Goose, Hermes or OpenClaw
61
- was already measured with that client. Because these are days no earlier version measured, the measure rules become 4:
62
- `npx worktrust update` on a computer measured by rules 3 offers the re-measure once and says why.
63
-
64
- **Confidential client work.** `npx worktrust project confidential [folder]` marks a client's repository: its hours and
65
- token counts still count, under one fixed marker, and no repository name, branch, remote, path, commit or app title
66
- leaves the computer. Your passport names that share inside your verified hours as "Confidential client work".
67
- `npx worktrust project exclude [folder]` leaves a folder out entirely, `project normal` undoes either, and `project list`
68
- shows what you set. Only you change these at your keyboard; an agent's shell may only list them.
69
-
70
- **OpenCode in Remote Agent.** Your phone can steer OpenCode on this computer, and through it a local model such as Qwen on
71
- Ollama. Like Codex it is off by default: `npx worktrust remote opencode on` says what OpenCode can do without asking and
72
- asks for a typed yes; `off` switches it off again. Its runs ask your phone before every command, edit and fetch, and a
73
- remote-steered session never counts as your hours.
74
-
75
- **The import window.** An AI app on this computer is shown the `import_history` tool only in the hour after you copy the
76
- import prompt in Sources on app.worktrust.io, so it no longer costs every session the tool's description.
77
- `npx worktrust history` is unchanged.
78
-
79
- ## 0.11.3: every device off this computer at once
80
-
81
- `npx worktrust remote phones remove --all` disconnects every phone and browser from this computer in one act, after one
82
- confirmation at the keyboard. The computer refuses them from their next message. Sessions they started keep running here:
83
- stop them with `npx worktrust remote disable`, or pause everything with `npx worktrust remote pause`. To end their keys for
84
- your whole account too, use Settings › Remote Agent on app.worktrust.io or Remote Agent settings on your phone. What is measured for the
85
- passport is unchanged: remote-steered sessions never count as your hours, and the measure rules stay 3.
86
-
87
- ## 0.11.2: your phone adds a browser
88
-
89
- A browser where you use app.worktrust.io can steer this computer's agents without a walk to its keyboard: the browser
90
- shows a code, your phone scans it and asks Face ID, and this computer adds the browser only if you allowed it here once
91
- (`npx worktrust remote phones allow-endorse on`, off by default), only for a browser of your own account, and only within
92
- five minutes. The terminal says when a browser was added and `npx worktrust remote phones` lists which phone added it;
93
- each one stays revocable. The Passport's issuer key stays pinned. What is measured for the passport is unchanged:
94
- remote-steered sessions never count as your hours, and the measure rules stay 3.
95
-
96
- ## 0.11.1: terminal sessions, and the live preview you can touch
97
-
98
- `npx worktrust remote terminal on` lets the phone start Claude Code in a terminal session on WorkTrust's own tmux socket
99
- (off until you turn it on), which you can also join at the desk with `npx worktrust remote attach <id>`. The phone reads
100
- the session's screen, is sent it when it changes while someone follows it, and answers a dialog the agent shows only
101
- when the screen still looks the way it did when you read it. The local preview can now be live: the page itself, on the
102
- phone, touchable, through this computer's own browser. Codex gets the same three planning tools as Claude Code. What is
103
- measured for the passport is unchanged: remote-steered sessions never count as your hours, and the measure rules stay 3.
104
-
105
- ## 0.11.0: steer your own agents from your phone
106
-
107
- `npx worktrust remote` pairs this computer with the WorkTrust app and lets the phone steer the coding agents that run
108
- here (Claude Code and Codex): start a chat in a project, choose the agent and its model from the ones this computer
109
- reports, send photos and files into the project's inbox (at most 25 MB a file), approve what the agent asks, and follow
110
- its work. Everything between the phone and this computer is sealed end to end; the relay passes it without reading it.
111
- The local agent plans its own work with three tools on its session (a release, its tasks, their state and estimate), so
112
- the phone's Status shows one table of what runs, what waits ("after release 22") and what ended. A session reports its
113
- active time, the background jobs an agent left running, and, inside a git worktree, the repository it belongs to. A
114
- local preview renders a dev server you allowed, as desktop, tablet or phone, with this computer's own browser. A phone
115
- app from before this version cannot read what 0.11.0 sends: update both. What is measured for the passport is unchanged:
116
- remote-steered sessions never count as your hours, and the measure rules stay 3.
117
-
118
- ## 0.10.38: an export says what it can about its own clock
119
-
120
- `npx worktrust history --export` now sends, beside each run's timeline, the facts WorkTrust checks to tell an edited
121
- ChatGPT or Claude-on-the-web export from one as the vendor made it: every model slug of the run (`models`), how many kept
122
- steps are dated more than ten minutes before the step they follow (`tree_inversions`), and, for a ChatGPT conversation
123
- whose id carries a clock, how far its creation time sits from that clock (`id_skew`). Once per export batch it sends the
124
- export's envelope: its kind (a zip, several zips, a folder or a bare file), the moment the vendor's zip name gives, the
125
- first and last write time of its conversations entries, its last message, and whether its shape is the vendor's (no extra
126
- field but zip64's, no data descriptor, no Finder litter, parts in order). Never a conversation's id, title or text, never
127
- the archive's file name. A line whose clock does not hold up goes to Review with its reason named, never refused or
128
- deleted; a re-zipped export alone is only a label. Lines that arrived from 0.10.37 or older are not judged again. One new
129
- module, `export-facts.mjs`. What is measured is unchanged: the measure rules stay 3.
130
-
131
- ## 0.10.37: an export arrives whole; progress, Ctrl+C and the reason in WorkTrust's words; CLI active and updating itself
132
-
133
- An export send no longer stops at WorkTrust's upload budget per minute: the person's own send waits it out (at most 90
134
- seconds a wait) and goes on, and a batch WorkTrust stored in part is sent again at once until it holds every line; a line
135
- already received is kept once. Every long step shows how far it is, and Ctrl+C stops cleanly, keeping what has not arrived
136
- for the next run. A batch that did not arrive is said in WorkTrust's own words instead of "Not all of it arrived". The
137
- receipt after an export names its hours as reconstructed by WorkTrust, beside the measured ones, never as measured.
138
- CLI active per computer: a pause set in Sources › Devices is kept by the computer at its next session, and turning it back
139
- on lets the computer update itself, verified (SECURITY.md, "Updating itself when you turn it on"). A computer on 0.10.36
140
- or older updates once by hand: `npx worktrust@latest update`. What is measured is unchanged: the measure rules stay 3.
141
-
142
- ## 0.10.36: large and cut-off ChatGPT exports; hours only with `mcp off`; a re-measure reported whole or not at all
143
-
144
- `npx worktrust history --export` now reads a ChatGPT export of any size: a zip64 archive (an export over 4 GB), and a
145
- download that stopped part way, which is read up to the last whole `conversations-NNN.json` part and said as such ("The
146
- archive was cut off after conversations-NNN.json; this is not the whole export"), so you decide whether to send what was
147
- read before the cut. ChatGPT's loose `conversations-NNN.json` parts, a folder of them or one part beside its siblings, are
148
- read as one export in part order; a missing part is refused by its name. An empty element in an export is counted and
149
- left out instead of refusing the whole export. What is sent from an export is unchanged: hours and tokens per day, never
150
- text. (The reader can also count an export's file kinds, searches and model switches between model families, but nothing
151
- asks for them and nothing of them is sent.)
152
-
153
- `npx worktrust mcp off` keeps the hours and takes the WorkTrust door out of every AI app here; `mcp on` puts it back (see
154
- "Hours only, or also work lines" below). A choice made for this computer in Sources › Devices is done by the computer
155
- at its next session. `update` no longer takes Codex's door out on every second run at the same version.
156
-
157
- A re-measure says "Re-measured" only when WorkTrust holds every batch of the run; otherwise it says how many it holds and
158
- gives WorkTrust's own reason for a refused batch, and the session hook exits with an error. What is measured is
159
- unchanged, so the measure rules stay 3 and no re-measure is offered.
160
-
161
- ## 0.10.35: Gemini CLI read; every earlier line can name its AI app
162
-
163
- Gemini CLI's sessions are read in place, as Copilot's are: the files Gemini CLI records itself under
164
- `~/.gemini/tmp/<project>/chats/session-*.jsonl` (or an older `.json`), each message's role and clock, the model and
165
- the token counts, and each tool call's name and status; the messages, the thoughts and the tool calls' arguments and
166
- results are parsed with the file and never kept or sent. A subagent's session lies inside its parent's and is not
167
- counted. The project folder is not read, so these lines name no repository. Their lines go as `gemini-cli`.
168
-
169
- WorkTrust now records which AI app each line came from (Copilot in VS Code, Gemini CLI, Antigravity …), so its AI apps
170
- table can give them their own rows. Lines measured before carry only their product ("Other apps"). The measure rules
171
- go to 3: `update` offers the re-measure once, and it sends every day again; WorkTrust replaces only the lines of
172
- "Other apps" and "App not recorded" that name no app, with the same counted seconds, and keeps every other line as it is.
173
- `npx worktrust history --rebuild --force-days` does the same at any time: every day of every AI app, even the days
174
- WorkTrust already holds unchanged (every app at once, so no day loses another app's line).
175
-
176
- ## 0.10.34: your own commits, measured on this computer (`npx worktrust git`)
177
-
178
- GitHub shows an App that reads commits as "Read access to code", and has no narrower permission. `npx worktrust git`
179
- reads your own commits HERE instead, with `git log`, only those whose author e-mail is yours (git's `user.email`, plus
180
- any you add with `git emails add`), in the repositories your AI sessions ran in or that you add with `git add <folder>`.
181
- It asks once, with the list; Enter and `--yes` are No, and a No is remembered. Each commit's file names are turned into
182
- the same closed keys the GitHub sync makes (kinds of files, technologies, architecture and security markers, one-way
183
- markers per folder and file) on this computer, and what is sent is counts, keys and markers: never a file name, a
184
- message, code, the commit's id or the remote's address. A commit travels as an owner-keyed reference only WorkTrust's
185
- side can match against what GitHub saw. `git list` shows what is offered and agreed, `git remove <folder>` reads nothing
186
- more from it, `--dry-run` reads and sends nothing.
187
-
188
- ## 0.10.33: one line per autonomous process per day; a fair-use limit keeps the line
189
-
190
- A finished headless or scheduled run (a run no person started) is no longer a line of its own. It waits on this
191
- computer, in `~/.worktrust/process-days`, folded into its process's UTC day: a process is the AI app, how the session
192
- was started, the timer's opaque reference when a timer started it, and the project folder, as a hash (`process_ref`),
193
- never a name or a path. Once the day is over and quiet it goes as ONE line with how many runs it holds
194
- (`process_runs`); the runs' timelines are joined at minute resolution, which keeps every counted second, with each
195
- run's call outcomes, its turns' length buckets and its subagent runs kept in step (every turn and each minute's first
196
- completed call stay). A run that
197
- finishes after its day was sent becomes the day's next part, and once WorkTrust holds its parts it is merged into the
198
- last one, which goes again whole. When WorkTrust answers a fair-use limit (429 with Retry-After) nothing is lost: the
199
- line stays where it was and goes after the wait. What is measured is unchanged, so the measure rules stay 2 and no
200
- re-measure is offered.
201
-
202
- ## 0.10.32: a re-measure sends only the days that changed; which subagents were active at once; each call's outcome
203
-
204
- Before a re-measure sends anything, the CLI asks WorkTrust, once per AI app, which of this computer's days it holds as
205
- current. The question carries nothing but the question (`import_history` with `rebuild` and `fingerprint`, no line).
206
- The answer is the digest this computer sent with each such day, its own submission and never the record: no hours, no
207
- lines, no figure. A day whose digest on this computer is the same is not sent, so a re-run with nothing new sends
208
- nothing and says so; one changed day sends that day alone. If the answer is not one (an older WorkTrust, an error, no
209
- network), every day is sent as before. The digest covers each line as it is sent, without the CLI's own version, so
210
- an update that measures the same sends nothing. When WorkTrust names where the run waits, the command prints
211
- `queued, position N, about M min`.
212
-
213
- A Claude Code session's subagents (the transcripts Claude Code keeps in `<session>/subagents/`) now travel with the day's
214
- stretch as `agents`: per run, by position only, its kind (`builtin`, `own` for an agent type of your own, `background`,
215
- `fork`, read from the run's `.meta.json`), when it started in whole seconds from the stretch's start, the stretches of time
216
- it was active (a gap over five minutes ends one) and how many of its tool steps failed and how many of those a later step
217
- of the same kind recovered. Never a name, a prompt, a path, a tool or an id. At most 64 runs a stretch, 12 active stretches
218
- a run and 256 in all; the longest are kept. WorkTrust counts a run only while the session it belongs to is steered by you
219
- (within 8 hours of your last input), and shows how many agents were active at once beside the sessions at once; it is never
220
- added to your hours.
221
-
222
- Beside the timeline, each model answer's outcome travels as one character (`call_outcomes`: completed, failed or not
223
- known), and in a run no person started (headless or scheduled) the length of each of your own turns as a bucket
224
- (`input_lengths`: short, medium or long) and, when a timer started the run, its cadence word with an opaque reference
225
- (`schedule_cadence`, `schedule_ref`). Never a word, a command, a path or the timer's name. WorkTrust credits Agentic Hours
226
- only for calls recorded as completed.
227
-
228
- The measure rules go to 2, so `update` offers a re-measure once, naming these changes.
229
-
230
- The session hook no longer reads a Claude Code transcript from its first byte on every run. Beside each session's
231
- watermark in `~/.worktrust/sessions.json` it keeps where its last read ended: the file's identity (device and inode), the
232
- offset, a hash of eight 4 KB samples before it, the offset of the first message not yet sent, and what a full read would
233
- know at that point (the session's working folder, how it was started, a subagent's first moment). That stays on this
234
- computer and is never sent. The next run reads from the first unsent message, so a day that spans the offset is read
235
- again from its start, and gives exactly what a full read gives. A file that was truncated, rewritten, replaced or
236
- compacted, a new CLI version, other measure rules, or a state without positions is read whole, as before. A re-measure
237
- (`history`, `history --rebuild`, the offer after an update) always reads everything. Measured: 1 MB appended to a 600 MB
238
- transcript reads about 1 MB.
239
-
240
- ## 0.10.31: a re-measure is offered only when measuring changed
241
-
242
- `update` offers to re-measure this computer's sessions only when the new version MEASURES differently from the one it
243
- replaces: a different timeline, seconds, tokens, steering, session kinds or readers. A release that changes something
244
- else (consent, coupling, words) offers nothing. The offer lists what changed, one line each. The CLI carries the
245
- version of its measuring rules beside its own version and records it in `~/.worktrust/installed-release.json` and
246
- `~/.worktrust/history.json`; an install from before 0.10.31, which did not record it, counts as measuring by 0.10.29's
247
- rules, so 0.10.29 or 0.10.30 updated to 0.10.31 is offered nothing. A history sent completely by a version with the
248
- same rules counts as done, so the bare `npx worktrust` does not offer it again either.
249
-
250
- ## 0.10.30: an update asks only what is new
251
-
252
- `update` remembers what you said yes to. Each AI app's WorkTrust door, the session hook, Codex's `notify` line and
253
- Antigravity's `Stop` hook that you agreed to are brought onto the new version without a question, each printed as
254
- `✓ … refreshed (you agreed on <date>)`. Only the launcher's path changes; nothing else about what was agreed. A NEW AI
255
- app, or a wake hook that is no longer there (you took it out), is shown in full and asked about; `--yes` leaves it as
256
- it is and lists it as `skipped: new, run without --yes to decide`. A No drops the agreement, and `disconnect` deletes
257
- the record. It is one small file, `~/.worktrust/consent.json` (see [SECURITY.md](SECURITY.md)). The first update that
258
- keeps it counts the WorkTrust entries already on this computer as agreed, because only a yes ever wrote them.
259
-
260
- The re-measure after a new version is one question, asked after its plan (the plan is counted on this computer and
261
- sends nothing): `Send them (re-measured; …)? [y/N]`. Enter and `--yes` are No. `--rebuild` agrees in advance.
262
-
263
- One line that updates a computer you coupled before, with no question at all:
1
+ # WorkTrust CLI
264
2
 
265
- ```
266
- npx -y worktrust@latest update --yes --rebuild
267
- ```
3
+ WorkTrust CLI measures the work you do with AI on your own computer and lets you steer your own coding agents from your phone.
4
+
5
+ It counts hours, tokens and tools for your verified AI Passport on [WorkTrust](https://worktrust.io): counts and metadata,
6
+ never your prompts, your code or what the AI answered. With Remote Agent, the same tool lets your phone start and follow
7
+ the coding agents on this computer, inside the folders you allow. You run every command yourself, each one shows its plan
8
+ first, and nothing is sent before you say yes.
268
9
 
269
- - `npx -y`: npm's own flag. It answers npm's `Ok to proceed?` before it downloads the package; WorkTrust never sees it.
270
- - `worktrust@latest`: the newest published version, never a copy npm cached earlier.
271
- - `update`: this computer onto that version, the same key, no new pairing.
272
- - `--yes`: every question whose answer is Yes by default. Anything new stays as it is (skipped, and listed).
273
- - `--rebuild`: yes in advance to re-measuring this computer's sessions with the new version's rules. WorkTrust
274
- replaces this computer's earlier lines for those days, each withdrawn and kept, never deleted. Leave it out to
275
- be asked.
276
- - `--codex` and `--antigravity` say yes in advance to a NEW Codex or Antigravity wake hook as well.
10
+ ## What you can do
277
11
 
278
- ## 0.10.29: history in calls WorkTrust takes; how each session was started
12
+ - **Measure.** A session hook measures each stretch of AI work on this computer: when, how long, which model, how many tokens, what kind of work.
13
+ - **Import history.** Send the earlier sessions your AI apps still hold, or a ChatGPT or Claude data export, as earlier work. It is shown with its origin, never as verified hours.
14
+ - **Preserve evidence.** See how long each AI app keeps its sessions, keep them longer, and write a local, hash-chained record of your measured days. This needs no account and sends nothing.
15
+ - **Remote Agent.** Start, follow and answer the coding agents on this computer from your phone or a browser, end-to-end sealed.
16
+ - **Connect your AI apps.** Give the AI apps on this computer the WorkTrust door, so your AI can log a finished piece of work. Or run hours only, without the door.
279
17
 
280
- A history call carries at most 1.9 MB and 1.4 MB of timelines (WorkTrust takes 2 MB and 1.5 MB). A batch an earlier
281
- version queued larger, or one WorkTrust answers with 413, is cut smaller in `~/.worktrust/history-outbox` and sent in
282
- pieces, never again as it was; a re-measure's run is cut again whole, under a new run id. A run WorkTrust already holds
283
- part of, or one line too large for any call, is let go and counted, and `npx worktrust@latest history` measures again.
18
+ What WorkTrust shows is observed work within a stated period. The scores built on it are not calibrated and are not a
19
+ hiring instrument.
20
+
21
+ ## Install and first run
22
+
23
+ ```sh
24
+ npx worktrust
25
+ ```
284
26
 
285
- Each line now says how its session was started, as the AI app recorded it: `interactive`, `headless` (`claude -p`, an
286
- Agent SDK program, `codex exec`, a Codex subagent) or `scheduled` (a timer started it), beside its timeline. A session
287
- the app said nothing about is left unsaid. WorkTrust counts a headless or scheduled session as Agent operations, never
288
- as the person's hours. `--history --dry-run --summary` prints the planned batches and the session kinds, counts only.
27
+ In your own terminal this opens the menu. On a computer that is not connected yet, Check this computer shows the plan,
28
+ asks, and you approve the computer in your browser with your own account and second factor. Before WorkTrust starts,
29
+ npm itself may ask `Ok to proceed?`; `npx -y worktrust` answers that in advance.
289
30
 
290
- ## 0.10.28: an honest receipt for a re-measure
31
+ **With Python instead.** The Python package runs the same CLI and brings its own Node, so it needs no Node on the computer:
291
32
 
292
- A re-measure that lands as new lines over lines WorkTrust had withdrawn (support's withdrawal of client-computed
293
- figures, a rebuild) is said as new lines, never as "Nothing changed"; entries WorkTrust refused for carrying no
294
- timeline are named. This CLI sends every session's timeline and no figure of its own since 0.10.20; WorkTrust times
295
- every second itself under its own idle cap, so a locally changed constant changes nothing it counts.
33
+ ```sh
34
+ pipx run worktrust
35
+ pip install worktrust
36
+ ```
296
37
 
297
- ## 0.10.27: history kept on the server
38
+ **What you need.**
298
39
 
299
- A re-measure (`worktrust history`) sends its batches as one run; WorkTrust keeps each batch it
300
- receives and rebuilds the days itself once the run is whole, so no `--resume` is needed. A line
301
- under no product name is replaced only where the new lines overlap it.
40
+ - Node 18 or later for measuring, importing and preserving. Reading the AI apps that keep their sessions in a database needs Node 22.5 or later.
41
+ - Node 22.4 or later for Remote Agent, or the Python package.
42
+ - macOS, Linux or Windows. Every release is built and tested on six platforms: Linux x64 and arm64, macOS on Intel and Apple silicon, Windows x64 and arm64.
43
+ - A WorkTrust account for everything except `preserve`, which is for everyone.
302
44
 
303
- ## 0.10.26: OS credential storage
45
+ **If your Node is older than 22.4.** Measuring keeps working. A `remote` command, and the menu's Remote Agent item, say so
46
+ and show the ways forward, each with its exact command:
304
47
 
305
- Explicit `worktrust protect-key` migration: an OS-vault wrapping key protects the locally
306
- encrypted coupling credentials. It does not attest that local activity is truthful. See
307
- [credential protection](#credential-protection) before enabling it.
48
+ 1. Update this computer's Node. The CLI reads how Node is installed here and shows the matching command (nvm, fnm, Volta,
49
+ asdf, Homebrew, winget, or the installer from nodejs.org). For fnm, Volta and Homebrew it can run the command for you,
50
+ after showing it and only when you type yes. It never uses sudo and never runs a system package manager. Afterwards it
51
+ runs `npx worktrust update`, so the session hook and your AI apps point at the new Node, and continues what you started.
52
+ 2. Use the Python package, which brings its own Node: `pipx run worktrust remote app`.
308
53
 
309
- After an approved update, WorkTrust receives the running version without
310
- an activity upload. Pending metadata batches can be resumed with `worktrust history --resume`,
311
- even after an AI app removed the original session files. Review-held revisions need review;
312
- reconnecting does not approve them. Keep archives for work that was never queued.
54
+ Without a terminal nothing is asked and nothing runs: the same text is printed and the command ends with a failure code.
313
55
 
314
- The server limits new personal registrations to five active device
315
- identities. AI apps sharing one key share one slot; cloned keys share account upload capacity.
316
- Retiring a device preserves earlier data. Existing accounts above the limit are preserved but
317
- cannot add another identity. Version labels and device signatures are not independent evidence
318
- of time or correctness. A CLI update does not automatically publish a passport.
56
+ **Update.** `npx worktrust@latest update` brings this computer's hook and AI-app doors to the newest version. Your key and
57
+ pairing stay.
319
58
 
59
+ **Stop.** `npx worktrust disconnect` takes WorkTrust out of every AI app here and removes the key. Then revoke the
60
+ computer in WorkTrust under Sources, Devices. More under [Undo](#undo).
320
61
 
321
- Couple a computer to [WorkTrust](https://worktrust.io) in one command. WorkTrust keeps a verified
322
- record of the work you do with AI without anyone reading that work: it receives metadata only.
62
+ ## The menu
323
63
 
324
64
  ```
325
- npx worktrust@latest
65
+ WorkTrust CLI 0.11.8
66
+ Connected as you@example.com · Remote Agent on
67
+
68
+ > 1 Update WorkTrust · up to date (0.11.8) npx worktrust update
69
+ Brings this computer's hook and AI-app doors to this version again; your key and pairing stay.
70
+ 2 Check this computer npx worktrust
71
+ Shows what is coupled here and finishes what still waits; a change asks first.
72
+ 3 Remote Agent › npx worktrust remote …
73
+ Opens the choices for steering this computer's agents from your phone. Nothing changes yet.
74
+ 4 Import earlier history › npx worktrust history …
75
+ Opens the ways to send earlier sessions as history. Each one shows its plan and asks first.
76
+ 5 Preserve evidence › npx worktrust preserve …
77
+ Opens the ways to keep your AI history on this computer. Nothing is sent.
78
+ 6 WorkTrust in your AI apps: On npx worktrust mcp off
79
+ Takes the WorkTrust door out of every AI app here; the session hook keeps measuring your hours.
80
+ 7 Status npx worktrust status
81
+ Shows the key, the hook, the door and what this computer measured. It only reads.
82
+ 8 Disconnect this computer npx worktrust disconnect
83
+ Takes WorkTrust out of every AI app here and ends this computer's key. It asks first.
84
+ 9 Help · all commands npx worktrust help
85
+ Lists every command and option. Tip: npx -y worktrust skips npm's own "Ok to proceed?" question.
86
+ Quit q
87
+ Leaves the menu. Nothing keeps running.
88
+
89
+ ↑/↓ move · Enter open · q quit · 1-9 jump
326
90
  ```
327
91
 
92
+ Every item shows the command it runs, so you can type it next time. Without a terminal (a script, a hook, the MCP door)
93
+ there is no menu and nothing waits for a key.
94
+
95
+ ## Commands
96
+
97
+ | Command | What it does |
98
+ |---|---|
99
+ | `npx worktrust` | In your terminal: the menu. Without a terminal, or with any option: connects this computer (shows the plan, asks, you approve in your browser), or shows what is connected. |
100
+ | `npx worktrust connect` | Connects this computer again, also when it is already connected. Asks first. |
101
+ | `npx worktrust update` | Brings this computer onto the newest CLI: same key, no new pairing. Something new is asked about. |
102
+ | `npx worktrust history` | Sends this computer's earlier sessions as history. `--rebuild` measures them again, `--export <path>` reads a ChatGPT or Claude export, `--from-archive` and `--from-folder <dir>` read your own copies. Always shows the plan and asks. |
103
+ | `npx worktrust disconnect` | Takes WorkTrust out of every AI app here. Asks first. |
104
+ | `npx worktrust status` | Shows what is connected here. It only reads. |
105
+ | `npx worktrust project` | Sets a folder's mode: exclude (nothing read), confidential (hours and tokens count; no name, branch, path or commit is sent) or normal. `project list` shows them. |
106
+ | `npx worktrust remote` | Remote Agent: `app` or `web` approve this computer, `pair` links a phone, then `status`, `pause`, `resume`, `disable`, `connections`, `disconnect`, `projects`, `roots` and `modes`. |
107
+ | `npx worktrust mcp off` | Hours only: the WorkTrust door out of every AI app here. The session hook keeps measuring. |
108
+ | `npx worktrust mcp on` | The door back in, so your AI can log finished work. |
109
+ | `npx worktrust mcp` | Says which of the two this computer is in. |
110
+ | `npx worktrust protect-key` | After an update: moves the key's protection into the operating system's vault. Asks first. |
111
+ | `npx worktrust orchestration report --file recording.jsonl` | Inspects a local recording of agent metadata. Sends nothing. |
112
+ | `npx worktrust mod` | The WorkTrust mod for Claude Code: what it counts and whether it is on. `mod install` turns it on, `mod remove` turns it off. |
113
+ | `npx worktrust git` | Sends your own commits as counts and kinds, measured on this computer: never a file name, a message, code or the commit's id. Asks once. |
114
+ | `npx worktrust preserve` | Keeps your AI history: the report, then `--apply` (keep sessions longer), `--archive`, `--verify` and `--summary` for the local record. For everyone, with or without an account. |
115
+
116
+ `npx worktrust help` prints these with every option. `--dry-run` shows a plan and stops; `--no-color` or `NO_COLOR` turns
117
+ colours off.
118
+
119
+ ## How it works
120
+
121
+ 1. **A plan, then a question.** A command lists what it found and what it would change, and asks. Nothing is written or sent before you answer.
122
+ 2. **You approve the computer in your browser**, signed in to WorkTrust with your second factor. The terminal never sees a password and cannot choose an account.
123
+ 3. **A session hook measures** each stretch of AI work when a session ends, and sends the measurement.
124
+
125
+ **What it reads.** Your AI apps' own session files on this computer, to take clocks, token counts, model names and the
126
+ kind of work from them.
127
+
128
+ **What it sends.** Per stretch of work: its timeline, token counts, the model's name, the kind of work and closed
129
+ technology keywords. For a repository on GitHub, GitLab or Bitbucket also its owner/name and the hashes of the commits
130
+ made; for any other repository a code that names nothing. The full list is in
131
+ [What it reads, writes and sends](#what-it-reads-writes-and-sends).
132
+
133
+ **What it never sends.** Your prompts, the AI's answers, your code, file contents or file paths.
134
+
135
+ **Where the key lives.** In a private file on this computer, and after `protect-key` wrapped by the operating system's
136
+ vault (Keychain, Credential Manager or the Secret Service). See [Credential protection](#credential-protection).
137
+
138
+ **What you can check.** The package has no dependencies and is published with provenance. Each release is signed, and the
139
+ launcher checks the package's files against that signature before it starts. A signature shows that a release is ours. It
140
+ does not prove that work happened: see [Why you can check it](#why-you-can-check-it) and
141
+ [Release signatures and the limits of verification](#release-signatures-and-the-limits-of-verification).
142
+
143
+ The long versions start at [What happens](#what-happens).
144
+
145
+ ## Remote Agent
146
+
147
+ Remote Agent lets your phone, or a browser, steer the coding agents on this computer. It is off until you turn it on at
148
+ this keyboard, and it has its own key, apart from the measuring key.
149
+
150
+ **Pairing in three steps.**
151
+
152
+ 1. `npx worktrust remote app` shows a QR code here. You scan it with the WorkTrust app and approve this computer with your authenticator. `npx worktrust remote web` does the same in your browser.
153
+ 2. `npx worktrust remote projects add <folder>` allows a folder. A phone can start an agent only in folders you allowed here.
154
+ 3. `npx worktrust remote pair` shows a QR code for a phone: five minutes, one phone, once.
155
+
156
+ **What a phone can do.** Start an agent in an allowed folder, follow it, answer it, and approve by class: a file edit
157
+ inside the project, a test, build or lint command from a short reviewed list, and a message an agent wants to send, shown
158
+ whole.
159
+
160
+ **What a phone cannot do.** Install from the network, push, deploy, delete outside the project, read secret files or
161
+ grant an "always allow". Those are decided at this keyboard or not at all.
162
+
163
+ **Modes with a ceiling.** Manual and Plan are always there. Edit automatically and Auto exist only once you allow them
164
+ here with `remote modes allow`. The computer refuses a mode above what you allowed.
165
+
166
+ **Sealed end to end.** The computer holds one outbound connection and opens no port. Messages are sealed between your
167
+ phone and this computer; the relay passes them on and cannot read a prompt, a file, a path, an output or a model name.
168
+
169
+ A session steered from a phone is recorded as an agent run. It never counts as your AI Hours.
170
+
171
+ The details: [Remote Agent: steer this computer's agents](#remote-agent-steer-this-computers-agents-from-your-phone-or-browser-npx-worktrust-remote).
172
+
173
+ ## The phone app
174
+
175
+ The WorkTrust app is coming to the App Store and Google Play. It is in TestFlight testing now, and there is no date yet.
176
+ News is on [worktrust.io](https://worktrust.io). Until then, Remote Agent also works from a browser at app.worktrust.io.
177
+
178
+ ## Supported AI apps and agents
179
+
180
+ - **Measured** (their sessions are read): Claude Code, Codex, Gemini CLI, Antigravity, Cursor, Copilot in VS Code, Hermes Agent, Goose, OpenCode, OpenClaw, the Ollama app and Open WebUI.
181
+ - **Connected** (they can get the WorkTrust door): Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code (Copilot agent mode), Windsurf, Mistral Vibe, Antigravity, Grok Build, Zed, Cline, Goose, OpenCode and OpenClaw.
182
+ - **Steered by Remote Agent:** Claude Code, Codex, OpenCode and a terminal session.
183
+
184
+ Only what is on this computer is found. Which sessions can be read depends on the format each app keeps.
185
+
186
+ ## Privacy and security
187
+
188
+ - Counts and metadata only. No prompt, answer, code or file content leaves this computer.
189
+ - Nothing is written or sent before you say yes, and `--dry-run` shows any plan without doing it.
190
+ - An AI agent cannot run these commands for you: they stop in an agent's shell. See [AGENTS.md](AGENTS.md).
191
+ - The key stays on this computer, and you can revoke it in WorkTrust at any time.
192
+ - A signature proves a release is ours and that a key was present. It is not independent proof of the work.
193
+
194
+ The threat model and the known limits are in [SECURITY.md](SECURITY.md). To report a vulnerability, write to
195
+ **hello@worktrust.io** with "security" in the subject. Please keep credentials, transcripts and account data out of
196
+ public issues.
197
+
198
+ ## Links
199
+
200
+ - [worktrust.io](https://worktrust.io): the site. [worktrust.io/preserve](https://worktrust.io/preserve): keeping your history, with or without an account.
201
+ - [What changed in each version](CHANGELOG.md)
202
+ - [SECURITY.md](SECURITY.md) and [AGENTS.md](AGENTS.md)
203
+ - [Licence](#licence): the WorkTrust CLI Licence, in [LICENSE](LICENSE)
204
+ - The reference below: everything above, in full.
205
+
206
+ ## Reference
207
+
208
+ The long versions of what is above. The headings are the ones other pages link to.
209
+
210
+ ## The npm package and the Python package, in full
211
+
328
212
  **The official npm package** is `worktrust`, published by the npm account **worktrustio** with
329
213
  provenance from this repository (github.com/fhomey/worktrust-cli). Check it on npmjs.com before you run
330
214
  it; a package of another name or from another publisher is not ours. Use the complete package:
package/cli-colour.mjs ADDED
@@ -0,0 +1,86 @@
1
+ /**
2
+ * COLOUR WITH MEANING (CLI 0.11.8, owner 2026-11-13). One small module, no dependency, used by the menu (cli-menu.mjs) and by
3
+ * the commands' status lines (worktrust.mjs `say`, so update, check, status, remote and the rest speak the same way):
4
+ *
5
+ * accent a spinner while something runs green a success line (✓, Done)
6
+ * yellow a warning (!) red an error (✗, `worktrust: …` on stderr; the exit code stays as it was)
7
+ * dim secondary text: the command an item runs, a hint bold a title
8
+ *
9
+ * NEVER COLOUR ALONE: a colour only wraps a line that already carries its word or symbol; with colours off the text is byte
10
+ * for byte what it was before 0.11.8. And colours are OFF (colourWanted) for anything a program reads: a hook, the MCP door,
11
+ * a pipe, CI. In order: a hook or the MCP door never, whatever is set; `--no-color` and NO_COLOR turn them off; FORCE_COLOR
12
+ * turns them on (0 or false: off); otherwise only on a terminal whose TERM is not `dumb`. Windows: Node's console layer
13
+ * translates these sequences on a real terminal from Windows 10 on; an older console stays plain.
14
+ */
15
+ import { release } from "node:os";
16
+
17
+ /** Whether this stream gets colours. Pure: the caller passes what it knows. `machine`: a hook or the MCP door is speaking. */
18
+ export function colourWanted({ env = {}, args = [], isTTY = false, platform = "", osRelease = "", machine = false } = {}) {
19
+ if (machine || env.WORKTRUST_HOOK_INPUT || env.WORKTRUST_MCP_TOKEN) return false;
20
+ if (args.includes("--no-color") || args.includes("--no-colour")) return false;
21
+ if (env.NO_COLOR) return false;
22
+ if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "") return !["0", "false"].includes(String(env.FORCE_COLOR).toLowerCase());
23
+ if (!isTTY || env.TERM === "dumb") return false;
24
+ if (platform === "win32" && Number(String(osRelease).split(".")[0]) < 10) return false;
25
+ return true;
26
+ }
27
+
28
+ const SGR = { bold: "1", dim: "2", inverse: "7", red: "31", green: "32", yellow: "33", accent: "36" };
29
+
30
+ /** The painters for one answer of colourWanted. Off, each returns its text unchanged. */
31
+ export function painter(on) {
32
+ const wrap = (code) => (text) => (on ? `\x1b[${code}m${text}\x1b[0m` : text);
33
+ const p = Object.fromEntries(Object.entries(SGR).map(([name, code]) => [name, wrap(code)]));
34
+ /** A whole status line by the symbol or word it already carries; any other line is returned as it is. */
35
+ const status = (line) => {
36
+ if (!on || typeof line !== "string" || line === "") return line;
37
+ if (/^\s*✓ /.test(line) || /^\s*Done\b/.test(line)) return p.green(line);
38
+ if (/^\s*! /.test(line)) return p.yellow(line);
39
+ if (/^\s*✗ /.test(line) || /^worktrust: /.test(line)) return p.red(line);
40
+ if (/^\s*WorkTrust · /.test(line)) return p.bold(line);
41
+ return line;
42
+ };
43
+ return { on: Boolean(on), ...p, status };
44
+ }
45
+
46
+ /** The painters for a stream of this process (stdout by default), by this process's own environment and arguments. */
47
+ export function coloursFor(stream = process.stdout, { machine = false } = {}) {
48
+ return painter(colourWanted({ env: process.env, args: process.argv.slice(2), isTTY: Boolean(stream?.isTTY), platform: process.platform, osRelease: release(), machine }));
49
+ }
50
+
51
+ /** What a person sees of a text: its length without the colour sequences. */
52
+ export const visibleLength = (text) => [...String(text).replace(/\x1b\[[0-9;]*m/g, "")].length;
53
+
54
+ /** A text cut to `width` visible characters (… at the cut), its colour sequences kept and closed. A line never wraps. */
55
+ export function clip(text, width) {
56
+ if (width < 1 || visibleLength(text) <= width) return text;
57
+ let out = "", seen = 0;
58
+ for (const part of String(text).split(/(\x1b\[[0-9;]*m)/)) {
59
+ if (part.startsWith("\x1b[")) { out += part; continue; }
60
+ for (const char of part) { if (seen === width - 1) return `${out}…${text.includes("\x1b[") ? "\x1b[0m" : ""}`; out += char; seen += 1; }
61
+ }
62
+ return out;
63
+ }
64
+
65
+ const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
66
+
67
+ /**
68
+ * A spinner in the accent colour while something runs: → stop(). Only on a real terminal with colours on; anywhere else it
69
+ * writes nothing at all, so a pipe, a hook and CI read the same bytes as before. stop() removes the line it drew.
70
+ * It draws on the line the cursor is on, which must be empty: start it between lines, never in the middle of one.
71
+ */
72
+ export function spinner(words, { stream = process.stdout, paint = coloursFor(stream), interval = 80, delay = 150 } = {}) {
73
+ if (!paint.on || !stream?.isTTY) return () => {};
74
+ let at = 0, shown = false, stopped = false, timer = null;
75
+ const frame = () => { shown = true; stream.write(`\r ${paint.accent(FRAMES[at % FRAMES.length])} ${paint.dim(words)}\x1b[K`); at += 1; };
76
+ // Work that ends at once shows no spinner at all: a line that flashes is worse than none.
77
+ const wait = setTimeout(() => { frame(); timer = setInterval(frame, interval); timer.unref?.(); }, delay);
78
+ wait.unref?.();
79
+ return () => { if (stopped) return; stopped = true; clearTimeout(wait); clearInterval(timer); if (shown) stream.write("\r\x1b[K"); };
80
+ }
81
+
82
+ /** Run `work` behind a spinner; the spinner is gone before anything else is said, also when the work fails. */
83
+ export async function busyWith(words, work, options) {
84
+ const stop = spinner(words, options);
85
+ try { return await work(); } finally { stop(); }
86
+ }