cofluxd 0.15.0 → 1.1.0

package/skills/coflux/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: coflux
-description: When you run inside a coflux terminal, this skill documents the local cofluxd commands that open terminals the user can watch and take over from the coflux web/mobile app, report progress, call the user and hand out preview URLs, plus the center MCP for reaching other workspaces and devices. Your coordinates (device / project / workspace / terminal) arrive in a <coflux-session> block at session start, or via the COFLUX_* environment variables. For the workspace your cwd is in always use the zero-credential local cofluxd commands (open, read, wait, send, report progress, call the user, get preview URLs); use the center's coflux MCP only to reach beyond it (child workspaces, other workspaces or devices). Use when the user should be able to watch, step into or stop a command (interactive steps, dev servers, a job they are waiting on), when the user has to decide something, when you want to hand the user a clickable preview URL, or when you need an isolated child workspace for parallel work.
+description: Use coflux to open visible terminals, read, wait, type, report progress, notify the user and obtain preview URLs. Prefer zero-credential local commands in the current workspace; use the account CLI across workspaces and devices. Coordinates arrive through coflux-session or COFLUX_* variables.
 ---
 
 # Working inside coflux
@@ -10,19 +10,32 @@ machines from a browser or a phone and take over at any time. This skill gives y
 user can see and take over, a progress line and a call button on the workspace card, preview URLs,
 and a way to operate the other workspaces and devices under the account when you need to.
 
-Two tracks, one rule: **whatever closes locally uses local commands; only reaching beyond the
-workspace you are in goes through MCP.**
+**Use local commands in this workspace and account CLI commands across workspaces and devices.**
 
 | Track | Credentials | Reach | Use for |
 |---|---|---|---|
-| Local commands `cofluxd terminal/progress/notify/ports` | none (the daemon identifies you by process tree) | **the workspace your cwd is in** | open, read, wait, send, report progress, call the user, preview URLs: the default, fastest, no network dependency |
-| Center MCP `coflux` | one OAuth authorization by the user in the host | **the whole account**: every device, project, workspace and terminal | child workspaces (git worktrees), cross-workspace / cross-device access, joining from outside coflux |
+| Local commands `coflux terminal/progress/notify/ports` | none (the daemon identifies you by process tree) | **the workspace your cwd is in** | open, read, wait, send, report progress, call the user, preview URLs: the default, fastest, no network dependency |
+| Account CLI | app login or `coflux login` | all devices and workspaces in the account | child workspaces and remote terminals; JSON output |
 
 Of the local commands, `send`/`read`/`wait`/`notify`/`progress` complete entirely inside the
 local daemon and never touch the center; `new`/`list`/`ports` are relayed to the center by the
 daemon on your behalf (terminals must appear in the user's sidebar, preview URLs are minted by
 the center). You only ever talk to the local daemon.
 
+## Managed terminal integration
+
+Coflux terminals automatically load this capability for Claude Code and Codex. Use
+`coflux agent status` to inspect this terminal's integration acknowledgements; an
+unconfirmed run has not successfully executed its context hook. It does not prove
+that approval is pending. Codex asks for native hook review when needed; use `/hooks`
+to review it. Do not edit trust hashes or the user's global configuration.
+
+Each agent keeps its own immutable CLI and skill files. Relaunching the agent selects
+the installed device version, including from an already-open supported shell. Use
+`COFLUX_AGENT_INTEGRATION=off claude` or `COFLUX_AGENT_INTEGRATION=off codex` to bypass
+managed integration for one invocation. Use `coflux agent run <claude|codex> -- ...`
+when a custom shell alias takes precedence over automatic integration.
+
 ## Figure out where you are first
 
 With the coflux plugin installed, Claude Code and Codex receive a `<coflux-session>` block at
@@ -36,22 +49,19 @@ env | grep '^COFLUX_'
 
 - **`COFLUX_WORKSPACE_ID` is non-empty** (or the `<coflux-session>` block is present) → you are in
   a coflux terminal with an up-to-date daemon. The variables below are your coordinates; pass
-  these ids to MCP tools directly instead of guessing from `list_*`:
+  these ids to account CLI commands directly instead of guessing from `list_*`:
 
   | Variable | Meaning |
   |---|---|
   | `COFLUX_DEVICE_ID` | id of the device you run on (the id in `list_devices`) |
   | `COFLUX_PROJECT_ID` | owning project id; empty string for a directory workspace without a repository |
-  | `COFLUX_WORKSPACE_ID` | the workspace this terminal was **opened** in (the id in `list_workspaces`). The variable is frozen when the terminal starts; the workspace the terminal *belongs to* can still change — see below. `cofluxd workspace` is the authority |
+  | `COFLUX_WORKSPACE_ID` | the workspace this terminal was **opened** in (the id in `list_workspaces`). The variable is frozen when the terminal starts; the workspace the terminal *belongs to* can still change — see below. `coflux workspace` is the authority |
   | `COFLUX_TASK_ID` | id of this terminal (the taskId / terminalId used by local commands and `read_terminal`) |
   | `COFLUX_SESSION_ID` | id of this PTY session |
-  | `COFLUX_MCP_URL` | the center's MCP URL; the user configures MCP with it |
 
-- **Variables empty or absent** → treat yourself as outside coflux: forget this skill and use your
-  own tools as usual (if the user configured the coflux MCP in the host, the MCP tools still work;
-  you just have no "where am I" coordinates). If the user insists you are inside a coflux terminal,
-  this machine's daemon has not been upgraded: tell the user to run `cofluxd update && cofluxd restart`;
-  after reopening the terminal the variables and the local commands are there.
+- **Variables empty or absent**: there is no local terminal context. Use `coflux whoami` to check
+  account access and the account CLI to discover workspaces. Ask the user to log in when needed;
+  never fabricate COFLUX_* coordinates.
 
 ### Two workspaces to keep apart: owning and effective
 
@@ -66,11 +76,11 @@ conversation, no restart — and a coflux child workspace is a normal registered
 session whose terminal belongs to workspace A can end up working inside workspace B. From that
 moment, in B:
 
-- `cofluxd terminal new` opens the terminal **in B**, under B in the user's sidebar, running in B's
+- `coflux terminal new` opens the terminal **in B**, under B in the user's sidebar, running in B's
   directory, counting against B's terminal cap;
-- `cofluxd terminal list` lists B's terminals, and A's terminals answer `read` / `wait` / `send`
+- `coflux terminal list` lists B's terminals, and A's terminals answer `read` / `wait` / `send`
   with "not in this workspace or does not exist" (`cd` back to A to reach them again);
-- MCP calls need **B's** id as `workspaceId`;
+- Account CLI calls need **B's** id as `workspaceId`;
 - the terminal itself stays under A, and `progress`, `notify` and `ports` still belong to it,
   whatever your cwd is; `COFLUX_TASK_ID` and `COFLUX_SESSION_ID` never change.
 
@@ -93,8 +103,8 @@ lives. When Claude Code cleans up its own worktree on exit, that workspace's ter
 the project's main workspace and the record disappears by itself.
 
 So, after entering or leaving a worktree, owning **and** effective are both the new workspace: pass
-its id to MCP tools and everything local already acts on it. The plugin drops the new id next to the
-tool result, and `cofluxd workspace` always tells you. Two things stay behind on purpose:
+its id to account CLI commands and everything local already acts on it. The plugin drops the new id next to the
+tool result, and `coflux workspace` always tells you. Two things stay behind on purpose:
 
 - `COFLUX_WORKSPACE_ID` (and the id in the `<coflux-session>` block from earlier in this session)
   still names where the terminal was *opened*; it is frozen when the PTY starts and cannot be
@@ -109,15 +119,15 @@ a daemon that is down or too old — the session just carries on with the owners
 ### Ask where you are
 
 ```sh
-cofluxd workspace
+coflux workspace
 {"workspaceId":"ws-b","path":"/Users/me/.coflux/worktrees/ws-b","owningWorkspaceId":"ws-a","moved":true}
 ```
 
 One line of JSON: `workspaceId` (+ `path`) is the **effective** workspace, `owningWorkspaceId` is the
 workspace this terminal belongs to right now, and `moved` says whether they differ. With the plugin
 installed you also get a `<coflux-session-moved>` block at the start of every prompt while the two
-differ — but that block only arrives with the **next** user prompt. **About to call an MCP tool right
-after a `cd`? Run `cofluxd workspace` first** and use the `workspaceId` it prints; do not reuse
+differ — but that block only arrives with the **next** user prompt. **About to call an account command right
+after a `cd`? Run `coflux workspace` first** and use the `workspaceId` it prints; do not reuse
 `COFLUX_WORKSPACE_ID`.
 
 ## When to open a terminal
@@ -143,8 +153,8 @@ own tools are faster, and a pile of one-second terminals is just noise to the us
 There are two kinds, told apart by one single thing: **whether you pass a command**.
 
 ```sh
-cofluxd terminal new --title="Run unit tests" --cmd="pnpm -C tests test"   # job terminal
-cofluxd terminal new --title="Debug shell"                                 # session terminal
+coflux terminal new --title="Run unit tests" --cmd="pnpm -C tests test"   # job terminal
+coflux terminal new --title="Debug shell"                                 # session terminal
 ```
 
 `--title` is the name the user sees in the sidebar; **name it properly**: "Run unit tests",
@@ -173,14 +183,14 @@ from what is on screen, and `wait` is only meaningful after you have sent `exit`
 
 Driving a session terminal:
 
-1. `cofluxd terminal new --title="Debug shell"` → prints a taskId.
-2. `cofluxd terminal read <taskId>` until you see the shell prompt. The shell needs a moment to
+1. `coflux terminal new --title="Debug shell"` → prints a taskId.
+2. `coflux terminal read <taskId>` until you see the shell prompt. The shell needs a moment to
    start and the first read can come back empty — **never `send` before you have seen a prompt**.
-3. `cofluxd terminal send <taskId> --text="pnpm build" --enter`, then `read` again to see what
+3. `coflux terminal send <taskId> --text="pnpm build" --enter`, then `read` again to see what
    happened. One send per command; nothing signals you when a command finished, so read until the
    prompt is back. To make that unambiguous, end the command with a marker of your own
    (`pnpm build; echo DONE-$?`) and read until the marker shows up.
-4. `cofluxd terminal send <taskId> --text="exit" --enter` when you are done; the terminal then
+4. `coflux terminal send <taskId> --text="exit" --enter` when you are done; the terminal then
    becomes `exited` with the shell's exit code.
 
 The new terminal has the same `COFLUX_*` variables (pointing at its own task/session ids, same
@@ -189,9 +199,9 @@ workspace as you).
 ### See how far it got
 
 ```sh
-cofluxd terminal list                      # every terminal in the workspace your cwd is in: id, state, exit code, title
-cofluxd terminal read <taskId>             # a terminal's content (plain text, last 200 lines by default)
-cofluxd terminal read <taskId> --lines 50
+coflux terminal list                      # every terminal in the workspace your cwd is in: id, state, exit code, title
+coflux terminal read <taskId>             # a terminal's content (plain text, last 200 lines by default)
+coflux terminal read <taskId> --lines 50
 ```
 
 `list` states are `running` / `exited` / `idle`; `exited` carries `exit=<code>`.
@@ -203,8 +213,8 @@ history, and empty for the first moments after opening. Both are immediate.
 ### Wait for a command to finish
 
 ```sh
-cofluxd terminal wait <taskId>               # block until that terminal exits and print the exit code (default cap 30 minutes)
-cofluxd terminal wait <taskId> --timeout 300 # custom timeout in seconds; a timeout fails loudly with a non-zero exit
+coflux terminal wait <taskId>               # block until that terminal exits and print the exit code (default cap 30 minutes)
+coflux terminal wait <taskId> --timeout 300 # custom timeout in seconds; a timeout fails loudly with a non-zero exit
 ```
 
 To wait for a command use `wait`; **do not write your own polling loop**. One command blocks
@@ -223,10 +233,10 @@ not any command's: check what a command did by reading the screen.
 **Keep working, and be woken up when it finishes.** `wait` blocks, so run it as a backgrounded Bash
 call of your own:
 
-1. `cofluxd terminal new --title="Run the test suite" --cmd="pnpm -C tests test"` → prints a taskId.
-2. Run `cofluxd terminal wait <taskId>` as a backgrounded Bash call, then go do something else.
+1. `coflux terminal new --title="Run the test suite" --cmd="pnpm -C tests test"` → prints a taskId.
+2. Run `coflux terminal wait <taskId>` as a backgrounded Bash call, then go do something else.
 3. The host wakes you when that call exits. Check its output for `# exited exit=<code>`, then
-   `cofluxd terminal read <taskId>` to see what actually happened.
+   `coflux terminal read <taskId>` to see what actually happened.
 
 That gets you both halves at once: the user watches (and can take over) a real terminal, and you are
 still told the moment it is over, instead of blocking or polling for it.
@@ -234,8 +244,8 @@ still told the moment it is over, instead of blocking or polling for it.
 ### Type into a terminal
 
 ```sh
-cofluxd terminal send <taskId> --text "y" --enter    # type a line and press Enter
-cofluxd terminal send <taskId> --enter               # just press Enter
+coflux terminal send <taskId> --text "y" --enter    # type a line and press Enter
+coflux terminal send <taskId> --enter               # just press Enter
 ```
 
 For interactive confirmations (y/N, menus), or to add a command in the same shell after the
@@ -252,7 +262,7 @@ previous one finished. Discipline:
 ### Report progress
 
 ```sh
-cofluxd progress "Reproduced; narrowing down the relay reconnect timing"
+coflux progress "Reproduced; narrowing down the relay reconnect timing"
 ```
 
 One sentence telling the user how far you are, shown on the workspace card and replaced by the
@@ -267,7 +277,7 @@ If unsure: when the user does not have to do anything, use `progress`.
 ### Call the user
 
 ```sh
-cofluxd notify "Both approaches work; I need you to pick one"
+coflux notify "Both approaches work; I need you to pick one"
 ```
 
 The user's sidebar switches this workspace to "waiting for interaction" and shows this sentence;
@@ -281,7 +291,7 @@ extra notify. This is for "what you have to say cannot be guessed from the statu
 ### Hand the user a clickable preview
 
 ```sh
-cofluxd ports
+coflux ports
 ```
 
 Lists every listening port in this workspace with its public preview URL. After starting a dev
@@ -292,79 +302,55 @@ server, use it to get the URL and tell the user directly; they click it and nobo
 Errors are one readable sentence; do what they say: "not inside a coflux terminal" = you are not
 in a coflux session; "terminal is not in this workspace or does not exist" = check the id with
 `list`, and if you moved into another workspace that is exactly what a terminal of the other one
-looks like (`cofluxd workspace` to confirm, `cd` back to reach it); "predates the daemon upgrade" =
+looks like (`coflux workspace` to confirm, `cd` back to reach it); "predates the daemon upgrade" =
 that terminal was opened before the daemon upgrade, open a new one; a `new` without `--cmd` refused for a missing command = this machine's daemon is older
 than session terminals, tell the user to run `cofluxd update && cofluxd restart` (or pass a command
 and use a job terminal); "daemon is not connected to the center" only appears on
 `new`/`list`/`ports`, retry once it reconnects.
 
-## Center MCP: leaving this workspace
-
-Local commands only see the workspace your cwd is in. Use the MCP server named `coflux` in the
-host **only** for these:
-
-- **Open an isolated child workspace to work in parallel**: `create_workspace` (project id from
-  `$COFLUX_PROJECT_ID`) really runs `git worktree add` on the device; then `create_terminal` runs
-  commands there. The same two kinds apply: `create_terminal` with a `command` opens a
-  job terminal, without one it opens a session terminal.
-- **Look at or operate terminals in other workspaces or on other devices**: `list_*` →
-  `read_terminal` / `send_terminal_input`.
-- **Join everything under the account when you are not inside a coflux terminal** (for example
-  Claude Code the user started on their own machine).
-- **Deleting a workspace**: `remove_workspace` (it closes that workspace's terminals first, then
-  removes the worktree and the record). Inside a coflux project the plugin blocks
-  `git worktree remove|move` run by hand, because that leaves an orphan workspace record in the user's
-  sidebar. Creating a worktree is *not* blocked — coflux follows you into it (see above) — and Claude
-  Code's own worktrees need no cleanup from you at all.
+## Account CLI: across workspaces and devices
 
-Do not detour through MCP for work inside the workspace you are in — including one you moved into
-with `cd` or EnterWorktree, where the local commands follow you: that is an extra round trip to the
-center, while a local command does it in one step.
-
-### When MCP is not configured
-
-Run `claude mcp list` (Codex: `codex mcp list`) to see whether `coflux` is there. If not, give
-the user the one-line setup, with the URL from `$COFLUX_MCP_URL` (it is the center's public URL
-+ `/mcp`):
+The bundled CLI can use the desktop app's login without receiving its token. For a standalone CLI,
+use `coflux login --username <account> --password-stdin`; the user supplies the password safely,
+never as a command argument. Account commands return JSON. A workspace ID identifies its device.
 
 ```sh
-claude mcp add --transport http coflux "$COFLUX_MCP_URL"     # Claude Code
-codex mcp add coflux --url "$COFLUX_MCP_URL"                 # Codex
+coflux device list
+coflux project list --device <deviceId>
+coflux workspace list --device <deviceId>
+coflux workspace new --project <projectId> --branch <branch>
+coflux terminal new --workspace <workspaceId> --title <title> [--cmd <command>]
+coflux terminal list --workspace <workspaceId>
+coflux terminal read <terminalId> --remote
+coflux terminal send <terminalId> --remote --text <text> [--enter]
+coflux terminal wait <terminalId> --remote --timeout 30
+coflux terminal stop <terminalId> --remote
+coflux terminal remove <terminalId> --remote
+coflux workspace rename <workspaceId> --name <name>
+coflux workspace remove <workspaceId>
+coflux ports --remote --device <deviceId>
 ```
 
-The host then guides the user through a one-time OAuth authorization in the browser (`/mcp` in
-Claude Code). Authorization is the user's job; you only hand over the URL and the command. Until
-it is set up, keep doing the work inside this workspace with local commands.
-
-### Using the tools
-
-The tool list and each tool's contract (parameters, limits, what an error means) come from the
-MCP server itself: read the tool descriptions in the host, they are the source of truth and this
-file does not repeat them. Take ids from the `COFLUX_*` variables first — except the workspace id
-after you moved, which comes from `cofluxd workspace` (or the `<coflux-session-moved>` block); for
-anything outside the workspace you are in, find ids with the `list_*` tools.
-
-The local-command disciplines apply to MCP just the same: `read_terminal` before
-`send_terminal_input`, stop when refused because the user is taking over (communicate with
-`cofluxd notify` instead of retrying), `wait_terminal` instead of a polling loop around
-`read_terminal`, and stop on "needs upgrade" (tell the user to run
-`cofluxd update && cofluxd restart` on that device; do not retry or work around it).
+`--remote` selects account access, including other workspaces on this machine. Read before sending;
+stop immediately when the user takes over. If a write times out, inspect the result before retrying.
+Exiting the CLI does not stop its terminals. Delete workspaces through `coflux workspace remove`
+so the filesystem and workspace records stay consistent.
 
 ## Boundaries
 
 - You can open, read, wait and type, but **typing is a restricted write with humans first**: you
   cannot write into a terminal the user is taking over (you are refused explicitly), and the user
   taking over at any time displaces you. Do not fight a human for a terminal.
-- Local commands only see **the workspace your cwd is in** (`cofluxd workspace` says which one);
-  other workspaces and other machines go through MCP and are limited to the same account.
+- Local commands only see **the workspace your cwd is in** (`coflux workspace` says which one);
+  use the account CLI for other workspaces and machines in the same account.
 - A workspace has a cap on concurrently live terminals (default 8, including the user's own).
   On hitting the cap, `list` first: usually some finished terminals were never collected. If the
   user really filled it up, `notify` them instead of forcing it.
-- `new`/`list`/`ports` and every MCP tool need the daemon connected to the center; "letting the
+- `new`/`list`/`ports` and account commands need the daemon connected to the center; "letting the
   user see" is their whole point. `send`/`read`/`wait`/`notify`/`progress` do not depend on the
   center. When disconnected they fail loudly rather than degrade silently.
 - `COFLUX_*` variables exist only in PTYs opened by coflux; exporting or changing them yourself
   has no effect, the center only trusts the ids it issued. `COFLUX_WORKSPACE_ID` always means the
   workspace this terminal was **opened** in and goes stale the moment coflux follows you into a
   worktree; both "where does this terminal belong now" and "where am I acting" come from
-  `cofluxd workspace`.
+  `coflux workspace`.