turno-cli 0.1.1 → 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.
Files changed (121) hide show
  1. package/CHANGELOG.md +432 -0
  2. package/README.md +228 -73
  3. package/dist/accounts/audit.js +154 -12
  4. package/dist/accounts/builtin.js +100 -25
  5. package/dist/accounts/delegate.js +199 -35
  6. package/dist/accounts/policy.js +79 -0
  7. package/dist/accounts/registry.js +39 -21
  8. package/dist/agents/adapter.js +29 -0
  9. package/dist/agents/claude.js +246 -0
  10. package/dist/agents/codex.js +186 -0
  11. package/dist/agents/copilot.js +56 -0
  12. package/dist/agents/cursor.js +58 -0
  13. package/dist/agents/index.js +26 -86
  14. package/dist/agents/snippets.js +43 -13
  15. package/dist/cli/args.js +38 -6
  16. package/dist/cli/commands/accounts.js +119 -52
  17. package/dist/cli/commands/auto.js +121 -33
  18. package/dist/cli/commands/browser-identity.js +514 -0
  19. package/dist/cli/commands/browser-session.js +102 -0
  20. package/dist/cli/commands/browser-vault.js +193 -0
  21. package/dist/cli/commands/browser.js +319 -138
  22. package/dist/cli/commands/complete.js +14 -3
  23. package/dist/cli/commands/completion.js +8 -2
  24. package/dist/cli/commands/config.js +186 -24
  25. package/dist/cli/commands/demo.js +321 -0
  26. package/dist/cli/commands/doctor.js +525 -123
  27. package/dist/cli/commands/handoff.js +33 -22
  28. package/dist/cli/commands/identity.js +192 -54
  29. package/dist/cli/commands/init.js +648 -0
  30. package/dist/cli/commands/limit.js +84 -16
  31. package/dist/cli/commands/mcp-call.js +240 -0
  32. package/dist/cli/commands/mcp-oauth.js +221 -0
  33. package/dist/cli/commands/mcp-observe.js +539 -0
  34. package/dist/cli/commands/mcp-share.js +201 -0
  35. package/dist/cli/commands/mcp.js +816 -187
  36. package/dist/cli/commands/mcpd.js +388 -76
  37. package/dist/cli/commands/migrate.js +6 -4
  38. package/dist/cli/commands/open.js +115 -27
  39. package/dist/cli/commands/profile.js +396 -78
  40. package/dist/cli/commands/resolve.js +14 -3
  41. package/dist/cli/commands/run.js +36 -6
  42. package/dist/cli/commands/secret.js +80 -76
  43. package/dist/cli/commands/session.js +17 -6
  44. package/dist/cli/commands/sessions.js +48 -12
  45. package/dist/cli/commands/setup.js +214 -164
  46. package/dist/cli/commands/status.js +227 -44
  47. package/dist/cli/commands/statusline.js +311 -114
  48. package/dist/cli/commands/ui.js +78 -68
  49. package/dist/cli/commands/undo.js +193 -18
  50. package/dist/cli/commands/uninstall.js +481 -0
  51. package/dist/cli/commands/upgrade.js +172 -79
  52. package/dist/cli/commands/usage.js +125 -51
  53. package/dist/cli/commands/version.js +21 -7
  54. package/dist/cli/commands/which.js +9 -24
  55. package/dist/cli/compile-cache.js +32 -0
  56. package/dist/cli/diagnostics.js +184 -0
  57. package/dist/cli/exit.js +65 -0
  58. package/dist/cli/group.js +24 -12
  59. package/dist/cli/help.js +62 -0
  60. package/dist/cli/highlight.js +236 -0
  61. package/dist/cli/hints.js +30 -0
  62. package/dist/cli/io.js +186 -1
  63. package/dist/cli/launch.js +52 -39
  64. package/dist/cli/launchers.js +161 -95
  65. package/dist/cli/main.js +201 -31
  66. package/dist/cli/optional.js +144 -0
  67. package/dist/cli/output.js +123 -0
  68. package/dist/cli/picker.js +459 -0
  69. package/dist/cli/registry.js +61 -6
  70. package/dist/cli/safe.js +87 -0
  71. package/dist/cli/secret-input.js +63 -0
  72. package/dist/cli/security.js +561 -0
  73. package/dist/cli/style.js +311 -0
  74. package/dist/cli/topics.js +142 -0
  75. package/dist/core/config.js +181 -23
  76. package/dist/core/exhausted.js +6 -8
  77. package/dist/core/fsutil.js +39 -0
  78. package/dist/core/journal.js +294 -16
  79. package/dist/core/manifest.js +153 -6
  80. package/dist/core/paths.js +14 -13
  81. package/dist/core/profiles.js +160 -10
  82. package/dist/core/resolve.js +139 -23
  83. package/dist/core/secrets.js +68 -23
  84. package/dist/core/sessions.js +13 -20
  85. package/dist/core/state-file.js +107 -0
  86. package/dist/core/update.js +31 -18
  87. package/dist/core/version.js +57 -10
  88. package/dist/demo/server.js +42 -0
  89. package/dist/mcpd/cache.js +23 -10
  90. package/dist/mcpd/calllog.js +254 -0
  91. package/dist/mcpd/client-names.js +46 -0
  92. package/dist/mcpd/connectors.js +188 -18
  93. package/dist/mcpd/daemon.js +472 -115
  94. package/dist/mcpd/folder-sets.js +42 -0
  95. package/dist/mcpd/gateway.js +473 -51
  96. package/dist/mcpd/health.js +313 -0
  97. package/dist/mcpd/importer.js +453 -36
  98. package/dist/mcpd/instances.js +453 -65
  99. package/dist/mcpd/jsonrpc.js +11 -1
  100. package/dist/mcpd/launchd.js +65 -48
  101. package/dist/mcpd/middleware.js +144 -0
  102. package/dist/mcpd/modern.js +686 -0
  103. package/dist/mcpd/oauth.js +845 -0
  104. package/dist/mcpd/peerpid.js +134 -6
  105. package/dist/mcpd/pressure.js +88 -0
  106. package/dist/mcpd/rss.js +166 -0
  107. package/dist/mcpd/service.js +191 -0
  108. package/dist/mcpd/share.js +217 -0
  109. package/dist/mcpd/state.js +183 -0
  110. package/dist/mcpd/sync.js +72 -87
  111. package/dist/mcpd/systemd.js +83 -0
  112. package/dist/mcpd/tokens.js +85 -0
  113. package/dist/mcpd/upstream.js +163 -46
  114. package/dist/statusline/cost.js +167 -44
  115. package/dist/statusline/input.js +78 -0
  116. package/dist/statusline/render.js +9 -3
  117. package/dist/ui/fonts.js +8 -3
  118. package/dist/ui/settings.js +33 -16
  119. package/npm-shrinkwrap.json +1102 -0
  120. package/package.json +10 -9
  121. package/dist/cli/commands/available.js +0 -18
package/README.md CHANGED
@@ -6,7 +6,7 @@
6
6
  </p>
7
7
 
8
8
  <p align="center">
9
- <b>One MCP gateway and per-folder accounts for Claude Code, Codex, Copilot CLI and Cursor CLI.</b>
9
+ <b>Switch accounts. Keep everything else.</b>
10
10
  </p>
11
11
 
12
12
  <p align="center">
@@ -17,48 +17,88 @@
17
17
  </p>
18
18
 
19
19
  <p align="center">
20
- English · <a href="https://github.com/wimo-dev/turno/blob/main/README.es.md">Español</a>
20
+ <a href="https://turno.wimo.dev"><b>turno.wimo.dev</b></a> · <a href="https://turno.wimo.dev/docs">Docs</a> · <a href="https://turno.wimo.dev/docs/releases">Releases</a> · English · <a href="https://github.com/wimo-dev/turno/blob/main/README.es.md">Español</a>
21
21
  </p>
22
22
 
23
- Every coding-agent session starts its own copy of every MCP server. Eight sessions with six
24
- common servers is **3,163 MiB in 56 processes**. turno starts each server once,
25
- only when a tool is called, behind one local gateway that every session of every agent shares:
26
- **847 MiB while all six run, 103 MiB while they sit idle**
27
- ([benchmark](https://github.com/wimo-dev/turno/blob/main/BENCHMARKS.md)). It also gives each folder its own account, so work repositories
28
- open with your work login and everything else with your personal one.
29
-
30
- ![turno: profiles for two agents, one gateway, the status line](https://raw.githubusercontent.com/wimo-dev/turno/main/docs/assets/demo.gif)
23
+ **Switching accounts? Keep talking.** The same session continues on your other account, with
24
+ its whole context, its MCP servers already signed in and a browser profile that keeps its
25
+ sign-ins. turno is for people who use a work account and a personal account with their coding
26
+ agents.
27
+
28
+ - **Your conversation.** A Claude Code session started with one account continues under
29
+ another, or forks into a second one: `turno session handoff work` prints the command.
30
+ - **Your MCP sign-ins.** One local gateway logs in to each remote OAuth server once per account
31
+ (`turno mcp login <server>`), and every agent session of that account reaches it through the
32
+ gateway.
33
+ - **Your browser session.** A real Chrome profile per identity that keeps its sign-ins (the
34
+ separate `turno-browser` package), and claude.ai links that open with the session's account
35
+ (`turno open`).
36
+ - **Your control.** Three skills of the Claude Code plugin move work between accounts from
37
+ inside a session: `/switch-account`, `/fork-session` and `/copy-artifact`.
38
+ - **The right account by itself.** Each project folder gets its account, in Claude Code, Codex,
39
+ Copilot CLI and Cursor CLI.
40
+ - **Easy to try, easy to undo.** `npx turno-cli demo` runs in a throwaway HOME, and
41
+ `turno undo` puts back every file a command changed.
42
+
43
+ The same gateway starts each MCP server once and shares it between sessions; the measured
44
+ memory saving is in [Benchmark](#benchmark). [turno.wimo.dev](https://turno.wimo.dev) tells the
45
+ whole story, with a small working picture of each part.
46
+
47
+ ![turno demo: two profiles, one gateway, the status line, the picker and turno doctor, in a throwaway HOME](https://raw.githubusercontent.com/wimo-dev/turno/main/docs/assets/demo.gif)
31
48
 
32
49
  ## Install
33
50
 
34
51
  ```sh
35
- npx turno-cli@latest doctor # try it without installing: checks your agents and config
36
- npm install --global turno-cli # macOS or Linux, Node 22.11+
37
- brew tap wimo-dev/turno && brew trust wimo-dev/turno && brew install turno # or Homebrew
52
+ npx turno-cli demo # try it first, in a throwaway HOME; your own setup is not touched
38
53
  ```
39
54
 
40
- The npm package is `turno-cli`; the command it installs is `turno`.
41
-
42
- Then move your MCP servers behind the gateway:
55
+ Then install it with the package manager you already use (macOS or Linux, Node 22.11+):
43
56
 
44
57
  ```sh
45
- turno mcp import --move-secrets --write # mcp.toml from the servers you already have
46
- turno mcp daemon start # the gateway, kept alive by launchd
47
- turno mcp sync # point every agent profile at it
58
+ npm install --global turno-cli
59
+ pnpm add --global turno-cli
60
+ bun add --global turno-cli
61
+ yarn global add turno-cli # yarn 1 (classic); yarn 2 and later have no global installs
62
+ brew tap wimo-dev/turno && brew trust wimo-dev/turno && brew install turno
48
63
  ```
49
64
 
50
- Nothing leaves your machine: no account, no telemetry, no proxy for model traffic.
65
+ The npm package is `turno-cli`; the command it installs is `turno`, and `turno upgrade` later
66
+ updates it with the same tool. `npx turno-cli`, `pnpm dlx turno-cli` and `bunx turno-cli` run it
67
+ once without installing. It runs no install scripts, and npm and Homebrew install exactly the
68
+ dependency versions that were tested, from its `npm-shrinkwrap.json` (pnpm, bun and yarn resolve
69
+ the dependencies of its dependencies themselves). CI installs it each of these ways on macOS and
70
+ Linux. Nothing leaves your machine: no account, no telemetry, no proxy for model traffic.
51
71
 
52
72
  ## What it does
53
73
 
74
+ - **A conversation that continues on another account.** Your Claude Code profiles share
75
+ conversations, skills, commands, hooks, plugins and settings, and keep only their own login.
76
+ `turno work --resume <id>` continues a session that another account started, and
77
+ `turno session handoff work` prints the exact command (`--fork` keeps this session open and
78
+ starts a copy). [What profiles share](https://turno.wimo.dev/docs/concepts/profiles).
79
+ - **MCP sign-ins, once per account.** The gateway logs in to each OAuth remote server once per
80
+ account (`turno mcp login <server>`) and every agent session of that account uses it; a
81
+ variant per profile lets work and personal reach two accounts of the same service. Secrets
82
+ live in the macOS Keychain or the Linux Secret Service, not in agent configs.
83
+ [The gateway](https://turno.wimo.dev/docs/concepts/gateway).
84
+ - **A browser per identity** (separate package `turno-browser`): an MCP server that drives your
85
+ installed Chrome with one persistent profile per identity, so an agent works in the sessions
86
+ you signed into by hand, and `turno open <profile> <url>` opens a claude.ai link with the
87
+ account that owns it. See [Browser with real profiles](#browser-with-real-profiles).
88
+ - **Skills that move work between accounts.** The Claude Code plugin adds `/switch-account`,
89
+ `/fork-session` and `/copy-artifact`, and the accounts bridge lets a session delegate a task to
90
+ a service only another profile is signed into, asking before it writes.
91
+ [Skills](https://turno.wimo.dev/docs/concepts/skills).
92
+ - **The folder picks the account.** `turno profile assign ~/code/acme work` and every agent you
93
+ open in that repository uses your work login; `turno auto` picks it and says which account and
94
+ why, and `turno status` shows who is logged in where. The same folder rule can choose which
95
+ MCP servers sessions there see. [Folder rules](https://turno.wimo.dev/docs/concepts/folder-rules).
54
96
  - **One MCP gateway for every session.** `mcpd` listens on `127.0.0.1`, answers `initialize` and
55
97
  the tool lists from a cache, starts a server the first time one of its tools is called, shares
56
98
  that process between sessions where it is safe (`shared`, `project` or `session` scope) and
57
- stops it when idle. Secrets live in the macOS Keychain, not in agent configs.
58
- - **An account per folder.** `turno profile assign ~/code/acme work` and every agent you open in
59
- that repository uses your work login; `turno auto` picks it, and `turno status` shows who is
60
- logged in where. Conversations, skills and settings stay shared between your Claude Code
61
- profiles, so `turno work --resume <id>` continues a session started with another account.
99
+ stops it when idle, sooner when memory is low. It speaks MCP 2025-11-25 and 2026-07-28 on the
100
+ same endpoint, and `turno mcp log`, `top` and `savings` show its calls, memory and saving. See
101
+ [docs/mcp.md](https://github.com/wimo-dev/turno/blob/main/docs/mcp.md).
62
102
  - **Four agents, one setup.** The same profiles, folder rules and gateway for:
63
103
 
64
104
  | Agent | Profile | Gateway entries | Example |
@@ -68,28 +108,49 @@ Nothing leaves your machine: no account, no telemetry, no proxy for model traffi
68
108
  | GitHub Copilot CLI | `~/.copilot-<p>`, `copilot-<p>` | `mcp-config.json` | `copilot-work` |
69
109
  | Cursor CLI | `~/.cursor-<p>`, `cursor-agent-<p>` | `~/.cursor/mcp.json`, routed by environment | `cursor-agent-work` |
70
110
 
71
- opencode, Gemini CLI, Goose, Crush, Droid and Kiro can use the gateway too:
72
- `turno mcp config --agent <name>` prints their entries. See [docs/agents.md](https://github.com/wimo-dev/turno/blob/main/docs/agents.md).
111
+ A profile is one account of one agent. opencode, Gemini CLI, Goose, Crush, Droid and Kiro can
112
+ use the gateway too: `turno mcp config --agent <name>` prints their entries. See
113
+ [docs/agents.md](https://github.com/wimo-dev/turno/blob/main/docs/agents.md).
73
114
  - **A status line** for Claude Code with the account, its 5 h and weekly usage, context, branch
74
115
  and cost, with Nerd Font icons it installs for you (or Unicode where there is none).
75
- - **A browser with real profiles** (optional `turno-browser`): an MCP server that drives your
76
- installed Chrome with one persistent profile per identity, so an agent works in the sessions
77
- you signed into by hand.
116
+ - **Easy to check, easy to undo.** `turno doctor` names each problem and its fix (`--fix`
117
+ repairs what is safe, `--report` prints a block for an issue with no secrets), `turno mcp call`
118
+ tries a tool the way a session would, `--no-gateway` opens the agent without turno's gateway to
119
+ tell whose problem it is, and `turno undo` puts back every file a command changed.
120
+ [Troubleshooting](https://turno.wimo.dev/docs/troubleshooting).
78
121
 
79
122
  ## Quick start
80
123
 
124
+ ```sh
125
+ turno init # finds your agents, profiles, folders and MCP servers, shows the diff,
126
+ # then starts the gateway and points every profile at it
127
+ claude-work # sign in once per profile (/login)
128
+ cd ~/code/acme && turno auto # Claude Code, with this folder's account
129
+ turno # where you stand: this folder, accounts, gateway, what to do next
130
+ ```
131
+
132
+ `turno init` asks before it adopts anything and writes everything as one change, so one
133
+ `turno undo <stamp>` reverts it. The gateway runs as a login service (launchd on macOS,
134
+ systemd --user on Linux); `turno init --no-start` leaves it for later (`turno mcp daemon start`,
135
+ then `turno mcp sync`). Step by step instead:
136
+
81
137
  ```sh
82
138
  turno profile add work --color violet # ~/.claude-work and the claude-work command
83
139
  turno profile add personal
84
140
  claude-work # sign in once per profile (/login)
85
141
  turno profile assign ~/code/acme work # this folder and everything under it
86
142
  turno config set default personal # folders without a rule
143
+ turno mcp import --move-secrets --write # mcp.toml from the servers you already have
144
+ turno mcp daemon start && turno mcp sync # the gateway, and every profile pointed at it
87
145
  cd ~/code/acme && turno auto # Claude Code, signed in as work
88
146
  ```
89
147
 
90
148
  Codex, Copilot and Cursor profiles are the same with `--agent codex|copilot|cursor`. Point your
91
149
  terminal or editor at `turno auto` (or the `turno-auto` launcher) and every folder opens with
92
- its account.
150
+ its account. Launchers go in `~/.local/bin`; when it is not on your `PATH`, `turno profile add`
151
+ prints the line to add, and `turno work` works meanwhile. `turno auto` never switches accounts
152
+ in silence: a missing profile or a broken `config.toml` stops it with the command that fixes it
153
+ ([docs/accounts.md](https://github.com/wimo-dev/turno/blob/main/docs/accounts.md)).
93
154
 
94
155
  ## Benchmark
95
156
 
@@ -130,52 +191,92 @@ usage limits or safeguards; see [Vendor terms](#vendor-terms).
130
191
 
131
192
  **Where are my credentials?** Where each agent keeps them, inside that profile's folder (or the
132
193
  Keychain where the agent uses it). turno never reads, copies or forwards login tokens. MCP
133
- secrets you move with `--move-secrets` go to the macOS Keychain.
194
+ secrets you move with `--move-secrets`, and the OAuth tokens of remote MCP servers, go to the
195
+ macOS Keychain or the Linux Secret Service. What turno stores where: [SECURITY.md](https://github.com/wimo-dev/turno/blob/main/SECURITY.md).
134
196
 
135
197
  **Does turno see my prompts or model traffic?** No. It launches the agent and gets out of the
136
- way. Only MCP tool calls go through `mcpd`, on `127.0.0.1`, with a bearer token, and requests
137
- with an `Origin` header are rejected so web pages cannot reach it.
138
-
139
- **Linux? Windows?** Linux works for everything except the Keychain and the LaunchAgent (both
140
- have open issues). Windows is not supported.
198
+ way. Only MCP tool calls go through `mcpd`, on `127.0.0.1`, with a bearer token per profile,
199
+ and requests with an `Origin` header are rejected so web pages cannot reach it.
200
+
201
+ **Linux? Windows?** Linux works too: secrets go to the Secret Service (`secret-tool`), mcpd runs
202
+ as a `systemd --user` unit, and links open with `xdg-open`. Windows is not supported.
203
+
204
+ **Can scripts and agents run turno?** Yes. turno asks only when a person is at a terminal: with
205
+ `--no-input` (or `TURNO_NO_INPUT=1`), when stdin is not a terminal, and inside a Claude Code,
206
+ Codex, Copilot CLI or Cursor agent session it never asks. A command that would ask exits with
207
+ code 2 and names the flag that answers it, for example `turno: init needs an answer; pass --yes
208
+ (or run it in a terminal)`. `TURNO_NO_INPUT=0` lets you answer in an editor terminal that sets
209
+ an agent's variable. A command that needs a profile and gets none (`turno profile assign`,
210
+ `turno run`, `turno session handoff`, `turno limit set`) shows a list to choose from on a
211
+ terminal (arrows or j/k, type to filter, Enter, Esc to cancel); `turno run` lists `auto` first,
212
+ named with the profile this folder resolves to (`auto (work)`). Elsewhere it exits with 2 and
213
+ lists the profiles: `pass a profile: personal, work`.
141
214
 
142
215
  **How do I undo it?** Every command that writes keeps a copy of each file it changes:
143
- `turno undo --list` shows them and `turno undo <stamp>` puts them back. To remove turno,
144
- `turno mcp daemon stop`, undo the `mcp sync`, delete the `claude-<p>`-style launchers in
145
- `~/.local/bin` and `npm uninstall --global turno-cli`. Profile folders stay until you delete them.
216
+ `turno undo --list` shows them and `turno undo <stamp>` puts them back (backups older than 30
217
+ days are pruned, keeping the newest 10). To remove turno, `turno uninstall --dry-run` lists what
218
+ turno set up (service, launchers, MCP entries, status line, config) and `turno uninstall`
219
+ removes it; then `npm uninstall --global turno-cli`. Profile folders, which hold your logins,
220
+ stay until you delete them. `turno uninstall --purge` also removes turno's state and caches
221
+ (backups, logs, usage, installed MCP servers), after which `turno undo` has nothing to restore.
146
222
 
147
223
  ## Reference
148
224
 
149
225
  `turno --help` groups the commands and `turno <command> --help` explains each. Commands that
150
226
  only read take `--json`; commands that write take `--dry-run`, keep a copy of each file they
151
- change, and print the `turno undo <stamp>` that puts them back.
227
+ change, and print the `turno undo <stamp>` that puts them back. `turno mcp import` only previews
228
+ (secrets masked) until `--write`.
152
229
 
153
230
  | Command | What it does |
154
231
  |---|---|
232
+ | `turno` | once set up, the status screen and the next step; before that, the help |
233
+ | `turno init [--dry-run] [--yes] [--start \| --no-start]` | set turno up in one step: agents, profiles, folder rules, mcp.toml, the gateway (one undo) |
234
+ | `turno demo [--keep] [-- <command>]` | try turno in a throwaway HOME (also `npx turno-cli demo`); without a terminal it shows what it set up and ends, `--keep` waits for Ctrl-C |
155
235
  | `turno <profile> [args]`, `turno run <profile\|auto> [args]` | the profile's agent with that account (args pass through) |
156
236
  | `turno auto [--agent codex\|copilot\|cursor]` | the profile assigned to the current folder |
157
- | `turno profile list\|add\|repair\|remove\|which\|assign\|unassign` | the profiles, and which folders use each |
158
- | `turno mcp list\|sync\|config\|import\|install\|refresh\|doctor\|daemon ...` | the MCP gateway, and entries for other agents |
159
- | `turno status` | one screen: this folder, profiles and usage, sessions, mcpd |
160
- | `turno limit show [--watch]\|set\|clear` | usage windows per account, and exhausted marks |
237
+ | `turno profile list\|add\|repair\|remove\|which [--check]\|assign\|unassign` | the profiles, and which folders use each; `which --check` exits 0, 3 or 4 for scripts |
238
+ | `turno mcp list\|sync\|config\|import\|install\|refresh\|doctor` | the MCP gateway's servers, and entries for other agents |
239
+ | `turno mcp export [--profile p]`, `turno mcp import <file>` | move servers to another machine, secrets by name only |
240
+ | `turno mcp call <server> [tool]` | list a server's tools or call one through mcpd, as a profile's session here would |
241
+ | `turno mcp login\|logout <server>` | log mcpd in to an OAuth remote server, once per account |
242
+ | `turno mcp log\|top\|savings` | the gateway's tool call log, memory per server, and what it saves |
243
+ | `turno mcp daemon start\|stop\|restart\|status\|logs`, `turno mcp token rotate` | the gateway service, and its token |
244
+ | `turno status [--json]` | one screen: this folder, profiles and usage, sessions, mcpd, and the next step |
245
+ | `turno limit show [--watch] [--json]\|set\|clear` | usage windows per account, and exhausted marks; `--watch --json` prints NDJSON |
161
246
  | `turno session list\|handoff <p> [--fork]` | open sessions, and the command to continue this one under another profile |
162
- | `turno open [profile] <url>` | open a link; claude.ai links use that profile's Chrome profile |
163
- | `turno identity list\|add\|remove\|login\|prefer\|log` | service accounts for the bridge, browser identities |
164
- | `turno secret set\|has\|rm\|list` | MCP secrets in the macOS Keychain |
165
- | `turno browser bench` | how automation-fingerprint test pages see each browser engine |
247
+ | `turno open [profile] <url>` | open an http(s) or mailto link; claude.ai links use that profile's Chrome profile |
248
+ | `turno identity list\|add\|remove\|login\|prefer\|log [--verify]` | service accounts for the bridge, browser identities, the audit log |
249
+ | `turno secret set\|has\|rm\|list` | MCP secrets in the macOS Keychain or the Linux Secret Service |
166
250
  | `turno ui status\|install` | the status line, its font and icons in every terminal |
167
- | `turno doctor [--fix]` | check everything and repair what is safe to repair |
168
- | `turno config path\|get\|set\|unset\|edit\|check` | config.toml without losing its comments |
169
- | `turno undo [--list] [<stamp>\|last]` | put back the files a command changed |
251
+ | `turno doctor [--fix]`, `turno doctor --security [--fix]` | check everything and repair what is safe to repair; `--security` checks file modes, the port owner, literal secrets, unpinned servers, token age and the audit log |
252
+ | `turno doctor --report`, `turno run <p> --no-gateway` | a Markdown block for an issue (no secrets); the agent without turno's gateway, to tell whether a problem is turno's |
253
+ | `turno config path [--all]\|get\|set\|unset\|edit\|check` | config.toml without losing its comments; `path --all` lists every path turno uses |
254
+ | `turno undo [--list] [<stamp>\|last]`, `turno undo --prune` | put back the files a command changed; prune old backups |
170
255
  | `turno upgrade [--check]`, `turno version` | update turno the way it was installed |
256
+ | `turno uninstall [--dry-run] [--yes] [--keep-config] [--purge]` | remove what turno set up (profile folders stay); `--purge` also removes its state and caches |
171
257
  | `turno completion zsh\|bash\|fish` | shell completion, including profiles and config keys |
258
+ | `turno browser identities\|add\|show\|set\|login\|remove` | browser identities and their settings (needs `turno-browser`) |
259
+ | `turno browser vault add\|list\|remove\|submit` | sign-in credentials per site in the OS secret store, filled by the `browser_login` tool |
260
+ | `turno browser export <id> --out <file>`, `turno browser import <file>` | move an identity's session to another machine as one encrypted file |
261
+ | `turno browser doctor [--fix]`, `turno browser reputation [<id>]` | check Chrome and every identity; how often each site challenged it |
262
+ | `turno browser bench` | developer diagnostic: browser engine compatibility |
263
+
264
+ For scripts and hooks: every `--json` object carries `schemaVersion`, `--json=fields` lists the
265
+ fields and `--json=name,email` keeps only those, `--watch --json` prints one JSON record per
266
+ line, and under `--json` an error is one JSON line on stderr (`turno help json`). Exit codes
267
+ are 0 ok, 1 failure, 2 usage, 3 no profile for the folder, 4 not signed in, 5 mcpd down
268
+ (`turno help exit-codes`); `turno profile which --check` answers with them, for example
269
+ `turno profile which --check || turno profile assign . work`. `turno help environment` lists
270
+ every variable turno reads, colors included (`NO_COLOR`, `FORCE_COLOR`, `CLICOLOR`,
271
+ `CLICOLOR_FORCE`, `TERM=dumb`). Commands that write end with a `Next:` line that says what to
272
+ run after them (never under `--json`); `turno config set hints false` turns those lines off.
172
273
 
173
274
  ### Config
174
275
 
175
276
  `~/.config/turno/config.toml`:
176
277
 
177
278
  ```toml
178
- system = "personal" # account the plain `claude` command uses
279
+ system = "personal" # account the plain `claude` command uses ("" for none)
179
280
  default = "personal" # profile for folders without a rule
180
281
  # fallback = "work" # optional, off unless set; read "Vendor terms" first
181
282
 
@@ -189,8 +290,22 @@ agent = "codex"
189
290
  [[projects]]
190
291
  path = "~/code/acme"
191
292
  profile = "work"
293
+
294
+ [[projects]]
295
+ path = "~/code/oss"
296
+ mcp_deny = ["mail"] # sessions here see every MCP server but mail
297
+
298
+ [mcpd]
299
+ port = 47821
300
+ # idle_under_pressure = "5m" # idle limit while memory is low; false turns it off
301
+ # max_request_body = "32MiB" # between 1MiB and 1GiB
302
+ # call_log = true # logs/calls.jsonl, no arguments or results
192
303
  ```
193
304
 
305
+ A rule may carry a `profile`, a server set (`mcp = [...]` keeps only those servers, `mcp_deny`
306
+ removes some), or both. With `system = ""` there is no default account, so `turno auto` needs a
307
+ rule ([docs/accounts.md](https://github.com/wimo-dev/turno/blob/main/docs/accounts.md)). `turno config --help` lists every key.
308
+
194
309
  ### MCP gateway
195
310
 
196
311
  `~/.config/turno/mcp.toml`:
@@ -198,37 +313,65 @@ profile = "work"
198
313
  ```toml
199
314
  [server.calendar]
200
315
  command = "cal-mcp"
201
- package = "@calcom/cal-mcp@1.4.0" # `turno mcp install` pins it instead of npx per start
316
+ package = "@calcom/cal-mcp@1.4.0" # installed by `turno mcp install` (see below)
202
317
  env = { CAL_API_KEY = "keychain:turno/calendar/api-key" }
203
318
  scope = "shared" # one process for every session
204
319
 
205
320
  [server.devtools]
206
321
  command = "chrome-devtools-mcp"
207
322
  scope = "session" # one per agent session, stopped when it ends
208
- idle = "15m"
209
323
 
210
324
  [server.issues]
211
325
  command = "issues-mcp"
212
326
  [server.issues.variant.work] # the work profile reaches a different account
213
327
  env = { ISSUES_TOKEN = "keychain:turno/issues/work" }
214
328
 
329
+ [server.linear]
330
+ url = "https://mcp.linear.app/mcp"
331
+ auth = "oauth" # mcpd logs in once per account: turno mcp login linear
332
+
215
333
  [server.docs]
216
- url = "https://docs.example.com/mcp" # remote, written straight into each profile
334
+ url = "https://docs.example.com/mcp" # remote, no secrets: written straight into each profile
217
335
  ```
218
336
 
219
337
  Each variant per profile runs separately, so two profiles can reach two accounts of the same
220
- service. Details: [docs/mcp.md](https://github.com/wimo-dev/turno/blob/main/docs/mcp.md).
338
+ service. A remote server with `auth = "oauth"` or secret headers goes through mcpd, so no agent
339
+ logs in to it on its own. `turno mcp install` installs each `package` at an exact version,
340
+ without install scripts (`--allow-scripts` to run them) and with a lockfile per server; until
341
+ then npx runs it, with a warning in the server's log. Details: [docs/mcp.md](https://github.com/wimo-dev/turno/blob/main/docs/mcp.md).
221
342
 
222
343
  ### Browser with real profiles
223
344
 
224
345
  ```sh
225
- npm install --global turno-browser # optional
346
+ npm install --global turno-browser # separate package, not installed with turno
226
347
  turno identity add browser:school # an identity and its mcp.toml entry
227
348
  turno identity login browser:school # sign in by hand once; cookies persist
228
349
  ```
229
350
 
230
- It drives the installed Google Chrome, headed, with a persistent profile per identity and no
231
- injected scripts ([ADR 0005](https://github.com/wimo-dev/turno/blob/main/docs/decisions/0005-stealth-browser-defaults.md)).
351
+ `turno-browser` is its own MCP server. It drives the installed Google Chrome, headed, with a
352
+ persistent profile per identity and no injected scripts; each identity keeps its time zone,
353
+ languages and locale fixed (`turno browser show|set <id>`).
354
+
355
+ - **It cleans up after itself.** At most 8 tabs per session's browser, an unused tab is parked
356
+ after 5 minutes and closed after 15, and popups nobody asked for are closed. Chrome closes
357
+ after 15 minutes without a tool call and opens again on the next one, and mcpd stops the
358
+ server after 30 (see [Browsers](https://github.com/wimo-dev/turno/blob/main/docs/mcp.md#browsers)). When the agent ends, Chrome closes with
359
+ it, and a Chrome that a killed run left open is closed on the next start.
360
+ - **Fewer round trips.** `browser_batch` runs up to 20 actions in one call, and an action that
361
+ fails says which element covers the target, or that it is hidden, disabled or gone.
362
+ - **Sign-ins the agent never sees.** `turno browser vault add` keeps a username, a password and
363
+ an optional TOTP secret per site in the OS secret store, and the `browser_login` tool fills
364
+ them into that site's sign-in page; results are redacted and values are bound to the site.
365
+ - **Sessions you can move.** `turno browser export <id> --out <file>` writes an identity's
366
+ cookies and storage as one file encrypted with a passphrase, with an expiry, and
367
+ `turno browser import <file>` reads it on another machine. The vault never leaves.
368
+ - **Lighter pages, when you want them.** Per identity and off by default: block trackers,
369
+ images, media or fonts, and keep static resources in a cache on disk.
370
+ - **Health you can read.** `turno browser doctor [--fix]` checks Chrome and every identity, and
371
+ `turno browser reputation` shows how often each site challenged it.
372
+
373
+ More in [Browser identities](https://turno.wimo.dev/docs/concepts/browser-identities) and
374
+ [`turno browser`](https://turno.wimo.dev/docs/reference/cli/browser).
232
375
 
233
376
  **Acceptable use.** Use it with your own accounts, on sites whose terms allow automated access
234
377
  by you, and at a human pace. Do not use it to get around access controls, paywalls, CAPTCHAs or
@@ -238,8 +381,10 @@ rate limits, to scrape at scale, or to access accounts that are not yours.
238
381
 
239
382
  A builtin MCP server (`builtin = "accounts"` in `mcp.toml`) lets a session in one profile
240
383
  delegate a task to a service account (a Linear workspace, a mail connector) that only another
241
- profile is signed into. Write tasks need your confirmation, and every call goes to an audit log
242
- (`turno identity log`).
384
+ profile is signed into. Reads run with only the account's read tools; writes, and by default
385
+ every call to a mail or messaging account, need your confirmation. Every call and its decision
386
+ go to a hash-chained audit log (`turno identity log`, `--verify` checks the chain). Details:
387
+ [docs/accounts.md](https://github.com/wimo-dev/turno/blob/main/docs/accounts.md).
243
388
 
244
389
  ### Status line
245
390
 
@@ -257,8 +402,9 @@ Details: [docs/ui.md](https://github.com/wimo-dev/turno/blob/main/docs/ui.md).
257
402
 
258
403
  ### Claude Code plugin
259
404
 
260
- `plugins/turno` adds session handoff and fork skills and a hook that records when a profile
261
- reaches its usage limit, so `turno status` can show it:
405
+ `plugins/turno` adds session handoff and fork skills, a `copy-artifact` skill that copies a
406
+ claude.ai artifact (with its files and assets) from one profile's account to another, and a hook
407
+ that records when a profile reaches its usage limit, so `turno status` can show it:
262
408
 
263
409
  ```
264
410
  /plugin marketplace add wimo-dev/turno
@@ -272,7 +418,7 @@ reaches its usage limit, so `turno status` can show it:
272
418
  | `~/.config/turno/config.toml` | profiles and folder rules |
273
419
  | `~/.config/turno/mcp.toml` | MCP servers behind the gateway |
274
420
  | `~/.config/turno/accounts.toml` | service accounts for the bridge |
275
- | `~/.local/state/turno/` | usage, run records, logs, backups, the mcpd token |
421
+ | `~/.local/state/turno/` | usage, run records, logs (with the tool call log `logs/calls.jsonl`), backups, the gateway tokens |
276
422
  | `~/.local/share/turno/` | installed servers, tool cache, browser identities |
277
423
 
278
424
  All three honor `XDG_CONFIG_HOME`, `XDG_STATE_HOME` and `XDG_DATA_HOME`.
@@ -304,14 +450,18 @@ traffic: every agent logs in by itself, in its own directory. Before you use sev
304
450
 
305
451
  turno is provided "as is", without warranty of any kind (Apache License 2.0, sections 7 and 8).
306
452
  It edits agent config files and launches programs as your user; every write keeps a backup
307
- that `turno undo` restores.
453
+ that `turno undo` restores, and `turno uninstall` removes what it set up.
308
454
 
309
455
  ### Update check
310
456
 
311
457
  Interactive commands ask the npm registry for a newer version at most once a day, sending only
312
458
  the package name. Turn it off with `update_check = false` in config.toml, `DO_NOT_TRACK=1`,
313
- `NO_UPDATE_NOTIFIER=1` or `TURNO_NO_UPDATE_CHECK=1`; it is also off in CI and outside a
314
- terminal. turno sends no other data anywhere.
459
+ `NO_UPDATE_NOTIFIER=1`, `TURNO_NO_UPDATE_CHECK=1` or `TURNO_NO_UPDATE_NOTIFIER=1`; it is also off in CI and outside a
460
+ terminal. Apart from that, turno only goes online when you ask it to: `turno ui install`
461
+ downloads the status line font, `turno mcp install` and `turno upgrade` fetch packages from npm,
462
+ `turno mcp import --write` and `turno init` (once you confirm) ask npm for the command name of
463
+ servers you ran with npx, and `turno mcp login` talks to that server's authorization server.
464
+ Previews (`--dry-run`, `turno mcp import` without `--write`) stay offline. There is no telemetry.
315
465
 
316
466
  ## Contributing
317
467
 
@@ -323,14 +473,19 @@ category). Security issues: [SECURITY.md](https://github.com/wimo-dev/turno/blob
323
473
 
324
474
  ```sh
325
475
  pnpm install && pnpm build
326
- pnpm check # typecheck, tests (sandboxed HOME), repository text rules, licenses
476
+ pnpm check # typecheck, lint (Biome, knip), tests (sandboxed HOME), text rules, licenses
477
+ pnpm test:e2e # also the end-to-end test that needs the network (Cursor)
327
478
  ```
328
479
 
329
- Design: [docs/design](https://github.com/wimo-dev/turno/blob/main/docs/design/2026-11-12-claudio-ecosystem-design.md). Decisions:
330
- [docs/decisions](https://github.com/wimo-dev/turno/blob/main/docs/decisions/). Progress: [docs/STATUS.md](https://github.com/wimo-dev/turno/blob/main/docs/STATUS.md).
331
-
332
480
  ## License
333
481
 
334
482
  Apache License 2.0 ([LICENSE](https://github.com/wimo-dev/turno/blob/main/LICENSE), [NOTICE](https://github.com/wimo-dev/turno/blob/main/NOTICE)). The bundled fonts keep their own
335
483
  licenses ([packages/fonts/LICENSE.txt](https://github.com/wimo-dev/turno/blob/main/packages/fonts/LICENSE.txt)); dependencies are listed in
336
- [THIRD_PARTY_NOTICES.md](https://github.com/wimo-dev/turno/blob/main/THIRD_PARTY_NOTICES.md). Made in Monterrey, Mexico.
484
+ [THIRD_PARTY_NOTICES.md](https://github.com/wimo-dev/turno/blob/main/THIRD_PARTY_NOTICES.md).
485
+
486
+ ## Documentation
487
+
488
+ [turno.wimo.dev](https://turno.wimo.dev) is the site: a landing page that tells the story in
489
+ eight parts, and the [docs](https://turno.wimo.dev/docs) in three areas: guides by problem and
490
+ concepts, the reference generated from the code, and one troubleshooting page per `turno doctor`
491
+ finding, with a filter. English and Spanish. Its source is in [apps/docs](https://github.com/wimo-dev/turno/blob/main/apps/docs).