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.
- package/CHANGELOG.md +432 -0
- package/README.md +228 -73
- package/dist/accounts/audit.js +154 -12
- package/dist/accounts/builtin.js +100 -25
- package/dist/accounts/delegate.js +199 -35
- package/dist/accounts/policy.js +79 -0
- package/dist/accounts/registry.js +39 -21
- package/dist/agents/adapter.js +29 -0
- package/dist/agents/claude.js +246 -0
- package/dist/agents/codex.js +186 -0
- package/dist/agents/copilot.js +56 -0
- package/dist/agents/cursor.js +58 -0
- package/dist/agents/index.js +26 -86
- package/dist/agents/snippets.js +43 -13
- package/dist/cli/args.js +38 -6
- package/dist/cli/commands/accounts.js +119 -52
- package/dist/cli/commands/auto.js +121 -33
- package/dist/cli/commands/browser-identity.js +514 -0
- package/dist/cli/commands/browser-session.js +102 -0
- package/dist/cli/commands/browser-vault.js +193 -0
- package/dist/cli/commands/browser.js +319 -138
- package/dist/cli/commands/complete.js +14 -3
- package/dist/cli/commands/completion.js +8 -2
- package/dist/cli/commands/config.js +186 -24
- package/dist/cli/commands/demo.js +321 -0
- package/dist/cli/commands/doctor.js +525 -123
- package/dist/cli/commands/handoff.js +33 -22
- package/dist/cli/commands/identity.js +192 -54
- package/dist/cli/commands/init.js +648 -0
- package/dist/cli/commands/limit.js +84 -16
- package/dist/cli/commands/mcp-call.js +240 -0
- package/dist/cli/commands/mcp-oauth.js +221 -0
- package/dist/cli/commands/mcp-observe.js +539 -0
- package/dist/cli/commands/mcp-share.js +201 -0
- package/dist/cli/commands/mcp.js +816 -187
- package/dist/cli/commands/mcpd.js +388 -76
- package/dist/cli/commands/migrate.js +6 -4
- package/dist/cli/commands/open.js +115 -27
- package/dist/cli/commands/profile.js +396 -78
- package/dist/cli/commands/resolve.js +14 -3
- package/dist/cli/commands/run.js +36 -6
- package/dist/cli/commands/secret.js +80 -76
- package/dist/cli/commands/session.js +17 -6
- package/dist/cli/commands/sessions.js +48 -12
- package/dist/cli/commands/setup.js +214 -164
- package/dist/cli/commands/status.js +227 -44
- package/dist/cli/commands/statusline.js +311 -114
- package/dist/cli/commands/ui.js +78 -68
- package/dist/cli/commands/undo.js +193 -18
- package/dist/cli/commands/uninstall.js +481 -0
- package/dist/cli/commands/upgrade.js +172 -79
- package/dist/cli/commands/usage.js +125 -51
- package/dist/cli/commands/version.js +21 -7
- package/dist/cli/commands/which.js +9 -24
- package/dist/cli/compile-cache.js +32 -0
- package/dist/cli/diagnostics.js +184 -0
- package/dist/cli/exit.js +65 -0
- package/dist/cli/group.js +24 -12
- package/dist/cli/help.js +62 -0
- package/dist/cli/highlight.js +236 -0
- package/dist/cli/hints.js +30 -0
- package/dist/cli/io.js +186 -1
- package/dist/cli/launch.js +52 -39
- package/dist/cli/launchers.js +161 -95
- package/dist/cli/main.js +201 -31
- package/dist/cli/optional.js +144 -0
- package/dist/cli/output.js +123 -0
- package/dist/cli/picker.js +459 -0
- package/dist/cli/registry.js +61 -6
- package/dist/cli/safe.js +87 -0
- package/dist/cli/secret-input.js +63 -0
- package/dist/cli/security.js +561 -0
- package/dist/cli/style.js +311 -0
- package/dist/cli/topics.js +142 -0
- package/dist/core/config.js +181 -23
- package/dist/core/exhausted.js +6 -8
- package/dist/core/fsutil.js +39 -0
- package/dist/core/journal.js +294 -16
- package/dist/core/manifest.js +153 -6
- package/dist/core/paths.js +14 -13
- package/dist/core/profiles.js +160 -10
- package/dist/core/resolve.js +139 -23
- package/dist/core/secrets.js +68 -23
- package/dist/core/sessions.js +13 -20
- package/dist/core/state-file.js +107 -0
- package/dist/core/update.js +31 -18
- package/dist/core/version.js +57 -10
- package/dist/demo/server.js +42 -0
- package/dist/mcpd/cache.js +23 -10
- package/dist/mcpd/calllog.js +254 -0
- package/dist/mcpd/client-names.js +46 -0
- package/dist/mcpd/connectors.js +188 -18
- package/dist/mcpd/daemon.js +472 -115
- package/dist/mcpd/folder-sets.js +42 -0
- package/dist/mcpd/gateway.js +473 -51
- package/dist/mcpd/health.js +313 -0
- package/dist/mcpd/importer.js +453 -36
- package/dist/mcpd/instances.js +453 -65
- package/dist/mcpd/jsonrpc.js +11 -1
- package/dist/mcpd/launchd.js +65 -48
- package/dist/mcpd/middleware.js +144 -0
- package/dist/mcpd/modern.js +686 -0
- package/dist/mcpd/oauth.js +845 -0
- package/dist/mcpd/peerpid.js +134 -6
- package/dist/mcpd/pressure.js +88 -0
- package/dist/mcpd/rss.js +166 -0
- package/dist/mcpd/service.js +191 -0
- package/dist/mcpd/share.js +217 -0
- package/dist/mcpd/state.js +183 -0
- package/dist/mcpd/sync.js +72 -87
- package/dist/mcpd/systemd.js +83 -0
- package/dist/mcpd/tokens.js +85 -0
- package/dist/mcpd/upstream.js +163 -46
- package/dist/statusline/cost.js +167 -44
- package/dist/statusline/input.js +78 -0
- package/dist/statusline/render.js +9 -3
- package/dist/ui/fonts.js +8 -3
- package/dist/ui/settings.js +33 -16
- package/npm-shrinkwrap.json +1102 -0
- package/package.json +10 -9
- 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>
|
|
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
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
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
|
+

|
|
31
48
|
|
|
32
49
|
## Install
|
|
33
50
|
|
|
34
51
|
```sh
|
|
35
|
-
npx turno-cli
|
|
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
|
-
|
|
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
|
-
|
|
46
|
-
|
|
47
|
-
|
|
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
|
-
|
|
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
|
|
58
|
-
|
|
59
|
-
|
|
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
|
|
72
|
-
`turno mcp config --agent <name>` prints their entries. See
|
|
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
|
-
- **
|
|
76
|
-
|
|
77
|
-
|
|
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
|
|
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
|
|
137
|
-
with an `Origin` header are rejected so web pages cannot reach it.
|
|
138
|
-
|
|
139
|
-
**Linux? Windows?** Linux works
|
|
140
|
-
|
|
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
|
|
144
|
-
|
|
145
|
-
|
|
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
|
|
159
|
-
| `turno
|
|
160
|
-
| `turno
|
|
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
|
|
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
|
|
169
|
-
| `turno
|
|
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`
|
|
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.
|
|
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 #
|
|
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
|
|
231
|
-
injected scripts
|
|
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.
|
|
242
|
-
|
|
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
|
|
261
|
-
|
|
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
|
|
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 `
|
|
314
|
-
terminal. turno
|
|
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),
|
|
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).
|
|
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).
|