---
title: System-wide dev CLI
description: "Drive Agentastic.dev from any terminal, cron job, or CI runner — installation, instance discovery, the command reference, and JSON output."
updated: "2026-11-15"
---

## Overview

For [Slack](/docs/features/slack), attach the plugin to an agent and run `dev slack send --channel CHANNEL_ID "message"`
or `dev slack reply --channel CHANNEL_ID --thread TIMESTAMP "message"`. `--text-file PATH` reads a multiline message.
Use `dev slack upload --channel CHANNEL_ID --file PATH [--thread TIMESTAMP] [comment]` to attach an image or file
from the agent's filesystem (maximum 50 MiB). Uploads require the bot's `files:write` scope; reinstall your Slack app
after adding it. Optional `--title` and `--alt-text` describe the attachment.
Slack commands execute the deployed plugin on the agent's own machine; they do not use the Mac socket.
The portable form `"$AGENTASTIC_SLACK_CLI" send …` works in local, remote, and container launches and requires Node 18+.
The server-managed `dev slack` shortcut requires helper 0.9.17+. MCP tools and the portable executable use the existing
plugin deployment paths. Only the bot token is sent to the execution environment.

`dev slack tasks [--channel CHANNEL_ID]` and `dev slack listener` are separate Mac control commands for incoming
Slack requests. They map to `slack.tasks` and `slack.status` on the Mac socket. The Mac does not expose `slack.send`
or `slack.reply` RPC proxies. `dev notify` retains its app-notification meaning where supported.
Task inventory includes a readable task `name` and, when Slack profile lookup succeeds, `user_name`, `user_handle`,
and `user_real_name`. The internal task `id` and stable `user_id` remain available.

Agentastic.dev ships two CLIs, both invoked as `dev`:

- **Internal `dev`** — auto-injected into terminal panes spawned *inside* Agentastic.
  Bound to the surrounding terminal/worktree via the `AGENTASTIC_TERMINAL_ID`
  and `AGENTASTIC_SOCKET_PATH` environment variables.
- **System-wide `dev`** (this doc) — installed to a stable PATH location
  (e.g. `/usr/local/bin/dev`) so you can drive *any* running Agentastic.dev
  instance from a regular Terminal.app, an SSH session, a cron job, a CI
  runner, raycast, another editor, or a script — without depending on those
  environment variables.

Both CLIs talk JSON-RPC v2 over the same Unix-domain socket. The system-wide
CLI adds an instance-discovery step on top.

Use the system-wide CLI when something outside Agentastic needs to launch an
agent, check status, tail output, send instructions, focus a workspace, open a
worktree, or trigger browser/task/repomix automation.

## Installation

### Via the app menu (recommended)

Open Agentastic.dev → **Agentastic → Command Line Integration…** and follow
the prompts. The installer copies a single Bash script to one of
these locations (in preference order, picking the first whose parent
directory exists):

1. `/usr/local/bin/dev`
2. `/opt/homebrew/bin/dev`
3. `~/.local/bin/dev`

Most commands require `python3` to be available on your shell's `PATH`.

If `/usr/local/bin` is not user-writable, the installer prompts for your
admin password and uses `osascript` to elevate. If a non-Agentastic file is
already at the target path, it is moved aside to `dev.backup` (the installer
recognizes its own shim by a magic header line).

### Manual

The script lives in the app bundle:

```bash
cp "/Applications/Agentastic.dev.app/Contents/Resources/dev-system.bash" /usr/local/bin/dev
chmod +x /usr/local/bin/dev
```

### Uninstall

Re-open the same menu item — if a previous install is detected, an
**Uninstall** button appears.

## Instance discovery

Each running Agentastic.dev instance writes a small JSON record to:

```
~/Library/Application Support/Agentastic.dev/instances/<pid>.json
```

The record contains the pid, the IPC socket path, version, build, and bundle
path. A `primary.json` file in the same directory points at the most
recently focused instance and is used as a tiebreak hint.

Resolution rules:

1. If `--instance <pid>` is given, that instance is used (or an error if it
   isn't responding to `ping`).
2. Else, if `AGENTASTIC_SOCKET_PATH` is set and responding, that socket is
   used. This keeps calls made from Agentastic terminals pinned to their
   owning app instance.
3. Else, if exactly **one** instance is responding, it is used.
4. Else, if `primary.json` points at one of the responding instances, it is
   used.
5. Otherwise the CLI exits with an error and tells you to pass `--instance`.

A terminal identity belongs to the instance that created it. When `--instance`
picks a different app than the one owning the calling terminal, the CLI omits
that terminal and worktree, and the app ignores identity it inherits from
another instance's or a remote session's processes. An agent can therefore
drive a second instance, such as a development build, from its own terminal.
`--cwd <dir>` declines inherited context altogether: the command resolves from
that directory alone.

You can always inspect the registry with:

```bash
dev instances
```

## Command reference

All commands accept the global flags: `--instance <pid>`, `--json`,
`-q`/`--quiet`, `--cwd <dir>`.

### Discovery

| Command | Purpose |
|---|---|
| `dev instances` | List running Agentastic.dev instances (does not need an instance) |
| `dev ping` | Show info about the resolved instance (`instance.info` RPC) |
| `dev capabilities` | List supported JSON-RPC methods |

### Workspaces & repos

| Command | Purpose |
|---|---|
| `dev workspaces` (`dev ws`) | List open workspaces |
| `dev focus <workspace_id>` | Bring a workspace window to the front |
| `dev import <path>` | Open a folder as a new workspace |
| `dev repos` | List repositories across workspaces |

### Worktrees

These are the canonical worktree verbs used both system-wide and inside
Agentastic terminals. The default target is the active repository of the
resolved instance.

| Command | Purpose |
|---|---|
| `dev list` (`dev ls`) | List worktrees with branch, agent icon, diff stats, PR state |
| `dev create [branch] [from_branch] [flags]` | Create a worktree; add `--prompt` or `--prompt-file` to launch an agent |
| `dev label <command>` | List, create, edit, remove, assign, unassign, collapse, or expand sidebar labels |
| `dev rename <display_name>` | Compatibility alias for `dev agent rename` using the current terminal/worktree/cwd |
| `dev rename --clear` | Compatibility alias for `dev agent rename --clear` |
| `dev remove <path> [force]` | Remove a worktree |
| `dev open <path>` | Activate a worktree in its window |
| `dev status <path>` | Full status payload for a worktree |

`dev rename` is a backward-compatible alias for the canonical
`dev agent rename` command. Inside an Agentastic terminal it targets that
terminal's agent. From another shell, run it inside the agent worktree or
provide a working-directory hint explicitly:

```bash
dev --cwd /path/to/worktree rename "Checkout polish"
```

Like `dev agent rename`, the alias changes only the persisted agent
`display_name`; it does not rename the worktree directory or branch. The main
worktree has no agent identity and cannot be renamed this way.

### Creating tasks and grouping agents

`dev create --help` lists all creation flags, and top-level `dev --help` surfaces
the agent, model, thinking, and label options. With a prompt, `dev create` uses
the same launch API and options as `dev agent create`. Without a prompt it creates
a worktree only, preserving `dev create <branch> [from_branch]`; omitting the name
generates one. Agent, model, and placement options require a prompt.
For worktree-only creation, `--from` must name an existing local branch.

```bash
dev create --agent codex --model <model-id> --thinking high \
  --label feature-a --prompt-file task.md

dev create fix-tests main --label feature-a
```

`--agent` accepts a configured agent definition ID, display name, or CLI command.
`--model` and `--thinking` select options supported by that agent;
`--thinking-level` is an alias for `--thinking`.

`--label feature-a` reuses a case-insensitive match or creates the label automatically.
Labels belong to a repository and group worktrees in the sidebar; every agent in a
worktree shares its label. A worktree belongs to at most one label.

### Labels

All `dev label` commands accept `--repo <path>` (default: caller's repository).
`dev label --help` lists the flags. Global `--json` returns structured results,
including label IDs, colors, worktree paths, counts, and collapsed state.

| Command | Purpose |
|---|---|
| `dev label [list]` | List the repository's labels |
| `dev label create <name> [--color <color>]` | Create or reuse a label |
| `dev label edit <name-or-id> [--name <new-name>] [--color <color>]` | Rename or recolor a label |
| `dev label remove <name-or-id>` | Delete the label; its worktrees remain intact and become unlabeled |
| `dev label assign <name> [--worktree <path> ...]` | Move worktrees into a label, creating it if missing |
| `dev label unassign [--worktree <path> ...]` | Remove worktrees from their labels |
| `dev label collapse <name-or-id>` | Hide a group's agents in the sidebar |
| `dev label expand <name-or-id>` | Show the group's agents |

Colors are `orange`, `yellow`, `green`, `cyan`, `blue`, `purple`, or `none` to clear.
Names match case-insensitively; IDs from `dev label list` also identify existing
labels. `delete`/`rm` alias `remove`; `rename`/`update` alias `edit`.
Assignment defaults to the caller's worktree. Repeat `--worktree` to move multiple
agents; all paths are validated in the selected repository before membership changes.

```bash
dev label create feature-a --color purple
dev label assign feature-a --worktree ../repo-worktrees/task-1 --worktree ../repo-worktrees/task-2
dev label edit feature-a --name "Feature A" --color blue
dev label collapse "Feature A"
dev label unassign --worktree ../repo-worktrees/task-1
```

### Agents & terminals

| Command | Purpose |
|---|---|
| `dev agents` | List native chats and terminals, including surface and status |
| `dev agent create [flags]` | Create an editor agent in a new or existing worktree |
| `dev agent task <prompt> [flags]` | Start an editor agent or continue a session (`submit` is an alias) |
| `dev agent rename [flags] <display-name>` | Set an existing agent's display-only name |
| `dev agent rename [flags] --clear` | Clear a custom display name |
| `dev agent list` | Alias for `dev agents` |
| `dev send <terminal_id> <text>` | Type into a terminal **and** append to `<worktree>/.agentastic/inbox/<id>.md` |
| `dev tail <terminal_id> [N]` | Print the last `N` (default 50) lines from a terminal's scrollback |
| `dev terminals` (`dev terms`) | List all terminals across workspaces |
| `dev newtab [command]` | Create a terminal in the caller's worktree; preserves focus |
| `dev remote sessions [--repo <path>] [--orphans]` | List Remote SSH server sessions |
| `dev remote kill <session_id> [--repo <path>]` | Kill one Remote SSH server session |
| `dev remote sessions close --orphans [--repo <path>]` | Kill Remote SSH sessions no longer referenced by local app state |

#### Launching and monitoring workers

New agents open in the **main editor**. Use `--surface sidebar` or `--surface utility`
for a panel. `--focus` controls selection independently: a background launch still
creates a saved tab that appears when you select its worktree. `--interface chat|terminal`
selects the presentation; the provider's configured interface is used when omitted.

`dev help agent` prints a complete workflow. `dev help agent create` and
`dev help agent task` work without a running app. The in-app agent helper uses the
same parser and help as the system CLI. The updated client checks agent API
compatibility before launching; an older running app is rejected instead of
silently ignoring placement flags. Rebuild/update and relaunch the app to use
these commands. Existing managed CLI installations refresh from bundled content
at app launch, including builds with the same version number.

A `dev` that is older than the app it is talking to replaces itself from that
app's bundle on its next command, so a copy the app could not reach at launch —
installed somewhere else, or running while the app started — still catches up on
its own. It prints one line saying it did, finishes the command it was given, and
the new copy takes over from the next one. When the file cannot be written (a
root-owned `/usr/local/bin/dev`, say) it says that instead, and
**Agentastic → Command Line Integration…** updates it with the privileges to do so.

| Command | Purpose |
|---|---|
| `dev agent create` | Create a worker in a new worktree, or use `--worktree <path>` for an existing one |
| `dev agent task` | Start in an existing worktree, or continue `--session <uuid>` |
| `dev agents` | List native chats, terminals and queued submissions with surface and runtime status |
| `dev agent status --session <uuid>` | Inspect one agent, including native chats without a terminal |
| `dev agent tail --session <uuid> --lines 80` | Read native conversation entries or terminal output |
| `dev agent reveal --session <uuid> --focus` | Select an existing agent |
| `dev agent move --session <uuid> --surface editor` | Move a panel conversation into the editor without restarting it |
| `dev agent interrupt --session <uuid> --clear-queue` | Interrupt a native chat and discard its pending messages |
| `dev agent queue --session <uuid>` | Inspect messages; use `--clear` for all or `--delete <message_id>` for one |
| `dev agent steer --session <uuid> --prompt <text>` | Steer a running native chat that supports injection |
| `dev agent launch-status --request-id <uuid>` | Inspect a durable creation receipt after a timeout |

A native chat has a `session_id` and no `terminal_id`. Use session-based commands
for orchestration. Terminal-only commands `dev tail`, `dev send`, and `dev terminals`
remain available for terminal interactions.

#### `dev agent create` flags

```
--prompt <text>       Initial task (choose this or --prompt-file)
--prompt-file <path>  Read a UTF-8 task file
--repo <path>         Open repository; defaults to the caller's repository
--agent <id>          Agent command or definition; defaults to the repository selection
--name <name>         Worktree name, made branch-safe; defaults to a generated city name
--branch <name>       Alias for --name
--from <revision>     Local branch or commit; defaults to the configured base branch
--from-origin        Fetch the selected branch from origin explicitly
--from-local         Use the local revision (default, independent of the UI origin toggle)
--worktree <path>     Existing worktree; cannot combine with name/from/mode
--surface <area>      editor (default) | sidebar | utility
--interface <kind>    chat | terminal; default is the provider's configured interface
--model <id>          Model option
--thinking <id>       Thinking-level option (--thinking-level alias)
--label <name>        Apply a repository sidebar label, creating it if missing
--mode <mode>         worktree (default for Git) | local | container | cloud
--run-mode <mode>     agent (default) | agentAutoApprove | plan
--request-id <uuid>   Stable creation identity; reuse for retries with identical options
--timeout <seconds>   Client wait for startup, 1..3600; default 120
--focus              Reveal the resulting agent; default preserves current selection
```

Creation uses an already-running app and its existing workspace window. Outside
Agentastic, select an instance using `dev --instance <pid> …` when several are running.
An exact commit base currently requires a local repository and `--from-local`.
A `container` or `cloud` mode the repository cannot use is refused with the reason
rather than run as a plain worktree. A `cloud` launch answers once its VM is up and
the agent has started, which can take longer than the default `--timeout`.

New workers default to interactive permissions. `agentAutoApprove` uses the
provider's unattended mode; for Codex this disables its sandbox and command approvals.
Use it for work authorized to run unattended. Login and task questions may remain.
Children do not inherit the coordinator's approval policy.

Example: launch, inspect, and continue a worker from the coordinator's repository:

```bash
request_id=$(uuidgen)
dev --json agent create --request-id "$request_id" --agent codex \
  --name fix-tests --from main --prompt-file task.md > launch.json
# Continue only if create succeeds and launch.json contains a launch receipt.
session_id=$(python3 -c 'import json; print(json.load(open("launch.json"))["session_id"])')
worktree_path=$(python3 -c 'import json; print(json.load(open("launch.json"))["worktree_path"])')
dev agent status --session "$session_id"
dev agent tail --session "$session_id" --lines 80
dev agent reveal --session "$session_id" --focus
dev agent task --session "$session_id" --worktree "$worktree_path" \
  --prompt "Run the focused test again"
```

The launch receipt includes `session_id`, `surface`, `interface`, `worktree_path`,
`request_id`, and `launches` for every created worker. `terminal_id` is included
only for a terminal. Launch success does not mean the task is complete.
`status` is `launched`, or `needs_input` with a `message` when the agent is
running but has not confirmed its session — for example, it is waiting at a
login, workspace-trust, or onboarding screen. That worker exists; check it in the
app instead of retrying.

Launch-status records the last preparation/startup phase and known target IDs.
If creation times out, inspect `dev agent launch-status --request-id "$request_id"`.
Retrying with the same ID and options returns the same outcome; it does not start
another worker. Conflicting options are rejected. If the app restarted during
startup, the receipt reports `unknown`; inspect existing agents before starting
any replacement. `--timeout` limits the client wait, not the worker's task duration.

#### Creator links

An agent that starts `dev agent create`, a new `dev agent task` session, or
`dev create` is recorded as the creator. Native chats carry their app session ID,
so agents sharing a worktree remain distinct. Explicit repository, worktree,
and cwd flags change the destination while preserving the actual caller.

JSON launch receipts, `dev --json agents`, and `dev --json agent status --session <uuid>`
include `created_by` and `creation_source`. Session status also includes `children`
with the created session or worktree identities. Worktree listings and status
expose the worktree's creator. Links survive app relaunches; retries and
continuations retain the original creator. Joining an existing worktree records
the new session's creator without changing the worktree's creator.

A Manager's launches automatically enter its linked-worker roster. Workers
started by a linked worker enter the same Managers' rosters. A worktree created
by a linked worker is associated with that worker's existing conversation;
starting a separate conversation creates a separate worker. `dev manager link`
still adopts existing workers or changes their labels. Removing a worker from a
Manager's roster preserves its creation history.

Local managed terminals and native chats also send Git's built-in Trace2 events
to the app. A successful direct `git worktree add`, including an absolute Git
executable and `--no-checkout`, can therefore record the same creator link with
`creation_source: "git"`. The app verifies the resulting worktree against Git's
inventory and its creation date; ambiguous observations remain unattributed.
This does not replace Git or install repository hooks. A user-configured
`GIT_TRACE2_EVENT` is preserved.

Worktrees created outside a managed process, with tracing removed, or on a remote
host are still discovered by the normal worktree watcher, but their creator
cannot be recovered from the filesystem alone. This tracking starts with newly
launched terminals and chat processes after the updated app is running.

#### `dev agent task` flags

This command uses an existing worktree. Omit `--session` for a new editor agent;
pass a known UUID to continue that conversation on its existing surface. A new
supplied UUID reserves a new session, so do not invent a new UUID for a continuation.

Any session `dev agents` lists can be continued. A native chat receives the
message. A terminal agent, including one `dev agent create` opened in the editor,
has it typed into its CLI, but only while that CLI is running: if the terminal
is back at a shell prompt, the command fails rather than run the prompt as a
shell command.

```
--session <uuid>      Existing session, or an explicitly reserved new UUID
--worktree <path>     Target an open worktree
--cwd <path>          Resolve the owning workspace
--surface <area>      editor (new-session default) | sidebar | utility
--interface <kind>    chat | terminal (new sessions only)
--agent <id>          Provider/definition (new sessions only)
--provider <id>       Alias for --agent
--model <id>          Model (new sessions only)
--thinking <id>       Thinking level (new sessions only)
--run-mode <mode>     agent | agentAutoApprove | plan (new sessions only)
--prompt <text>       Task text; a positional prompt also works
--prompt-file <path>  Read a UTF-8 task file
--focus              Reveal the result
```

`accepted` and `created` acknowledge queue admission, not provider startup.
Check `dev agent status` and `dev agent tail` for failures and approval requests.
A prompt saying “stop” is an ordinary queued message. Interrupt and clear old
instructions explicitly before sending a corrected continuation:

```bash
dev agent task --worktree /path/to/repo-worktrees/fix-tests \
  --surface utility --agent codex --prompt-file review.md
dev agent interrupt --session "$session_id" --clear-queue
dev agent queue --session "$session_id"
dev agent task --session "$session_id" --worktree "$worktree_path" \
  --prompt "Continue with the corrected scope"
```

`interrupt` stops a native chat's turn and sends Ctrl-C to a terminal agent. A
session that is still `queued` or `starting` has its launch cancelled instead;
an idle draft is left alone. `--clear-queue`, like `dev agent queue --clear`,
discards prompts `dev agent task` queued that the agent has not received, and a
native chat's queued messages. A terminal provider's own prompt queue is not
exposed by this API. Removing a worktree cancels the work queued for it.

#### JSON-RPC

`agent.create` accepts the corresponding parameters `repo`, `agent`, `name`,
`from_branch`, `from_origin`, `target_worktree_path`, `surface`, `interface`, `model`,
`thinking`, `label`, `mode`, `run_mode`, `prompt`, `request_id`, and `focus`.
The **parameter** `request_id` is the durable retry key. The envelope's `id` only
correlates the response and does not deduplicate launches. Files are read by the
CLI and transmitted as prompt text; the timeout is managed by the client.
`agent.create` also takes `skill_ids`, an array of skill IDs from **Settings → Skills**
to attach, and `plugin_overrides`, an object mapping plugin IDs to `true` to add a
plugin or `false` to leave it out of this launch, as Agent Home's **+** menu does;
plugins not named follow **Settings → Plugins**. A skill that isn't installed, or a
plugin added that isn't connected or approved for the repository, is refused.

`agent.task.submit` accepts `session_id`, `worktree_path`, `cwd`, `surface`,
`interface`, provider/model/thinking/run-mode options, `prompt`, and `focus`.
`agent.session.control` accepts `session_id` and an `action` of `status`, `tail`,
`interrupt`, `steer`, `queue`, `reveal`, or `move`; optional parameters include `lines`,
`clear_queue`, `clear`, `delete_id`, `prompt`, `surface`, and `focus`. `agent.launch.status` accepts a
`request_id`. The `capabilities` action reports the control API `revision`: 2 adds
terminal continuation and control of queued sessions.

The app fills missing `terminal_id`, `workspace_id`, `worktree_path`, and `cwd`
parameters from the calling process's ancestry when it belongs to this instance.
Send `"inherit_origin": false` to decline that, as the CLI does for an explicit
`--cwd` or when `--instance` names another app.

Read one newline-terminated response, verify the envelope `id`, and check `ok`
before consuming the result. A launch failure may leave a worktree or failed
session to inspect.

#### `dev agent rename`

Rename the current agent from one of its Agentastic terminals, or target an
existing agent by worktree path or terminal ID:

```bash
dev agent rename "Payments cleanup"
dev agent rename --worktree /path/to/worktree "API migration"
dev agent rename --terminal <terminal_id> "Reviewer"
dev agent rename --workspace <workspace_id> --worktree /path/to/worktree "API migration"
dev agent rename --clear
```

`--worktree` and `--terminal` are mutually exclusive. With neither flag, the
CLI resolves the caller's terminal/worktree context and then tries the current
working directory. An explicit `--worktree` or `--terminal` takes precedence
over the calling terminal's workspace, so it can target an agent in another
open workspace. If the selector is ambiguous across open workspace windows,
add `--workspace <workspace_id>` to constrain it. `--workspace` is valid only
with an explicit selector. The main worktree cannot be renamed as an agent.

This command changes only the persisted `display_name` shown in Agentastic.
The technical `name`, Git branch, worktree directory, terminal identity, and
running agent process are unchanged. `--clear` restores the worktree directory
name as the display name. The value is persisted immediately; a visible sidebar
row reveals the new name through a one-second Braille animation.

The legacy `dev rename` spelling invokes this same command and writes the same
canonical display-name setting.

For a Remote SSH agent, run the same command inside a newly created Agentastic
remote terminal. Remote server v0.8.13 and later put a server-managed `dev` on
that terminal's `PATH` and relay the request to the Mac workspace that owns the
PTY. The daemon copies its exact running executable to a versioned path such as
`~/.agentastic/bin/dev-0.8.15`, then points `~/.agentastic/bin/dev` at that
immutable copy. When the name is unused and no full desktop CLI is installed,
it also links `~/.local/bin/dev` to the private entry point so common Linux
login profiles continue to select it. On macOS, remote server v0.9.11 and later
remove their own user-level link when a full desktop CLI is detected, preventing
the rename-only helper from shadowing commands such as `dev ping`. The daemon
never replaces an existing user shim or full desktop CLI.

Login profiles often move Homebrew back to the front of `PATH`, so a full
desktop CLI on the remote Mac can still win inside a remote terminal. Current
desktop CLIs recognize the remote terminal and hand the whole command to
`~/.agentastic/bin/dev`. They no longer route it to an Agentastic.dev app that
happens to run on that host, which doesn't own the terminal. Commands the
server-managed CLI can't relay, such as `dev agent create`, fail instead of
starting work in a window nobody is watching. `--instance <pid>` still targets
an app on that host explicitly.

Remote server v0.8.14 also accepts the top-level `dev rename` compatibility
alias. On v0.8.13, use the canonical `dev agent rename` spelling.

Remote server v0.8.15 waits for the owning Mac app to validate and persist the
rename before it reports success. App-side validation or settings-save failures
are returned directly by the CLI, and a missing app response fails after a
bounded timeout instead of reporting a rename that may not have happened.

If the remote daemon predates v0.8.13, connect with a current app. An idle daemon
upgrades automatically. If it still owns terminal sessions, use **Remote
Sessions -> Restart Server**; this intentionally ends those sessions. Open a
new remote terminal afterward so it receives the managed CLI environment. You
can verify the selected command with `command -v dev` and `dev --version`. If a
pre-existing user shim still wins, call `~/.agentastic/bin/dev` explicitly.
Quit older Agentastic.dev builds connected to the same host while upgrading:
different app versions share the remote install path, so an older client can
otherwise redeploy its bundled server after the restart.

As a no-restart fallback, run the current CLI on the Mac, find the remote
terminal with `dev agents`, and target its ID explicitly:

```bash
dev agent rename --terminal <remote_terminal_id> "Reviewer"
```

Restarting the daemon never updates a separately installed global `dev`. From
an ordinary SSH shell, the daemon-managed command is available explicitly as
`~/.agentastic/bin/dev`; pass `--terminal <remote_terminal_id>` because that
shell has no implicit Agentastic terminal context.

#### Agents on every machine

Agents in remote terminals and remote chats use the same `dev` commands as
agents on the Mac: `dev agents`, `dev list`, `dev agent create`, `dev agent
task`, `dev agent status|tail|steer|interrupt`, `dev agent send` and `dev
agent wait`. On the host, `dev` relays each command through the host's
`agentastic-dev-server` to the Mac that opened the terminal or chat, so every
agent sees and reaches the same sessions.

Every agent has an address naming its machine:

```text
agent://dev003/3F2A…   an agent on the host dev003
agent://mac/91C4…      an agent on this Mac
dev003/fix-tests       a handle: host and display name
```

`dev agents` prints each agent's `location` and `address`. Paths read the way
the agent writes them: a bare absolute path is on the agent's own host, and
paths on other machines read `host:/path`, or `mac:/path` for the Mac, as the
sidebar already shows remote repositories (`dev004:~/src/app`).

```bash
# On dev003: delegate to a new agent on the same host, get told when it is done
dev --json agent create --agent codex --name fix-tests --report-to parent \
  --prompt "Fix the flaky cart tests" > launch.json
session_id=$(jq -r .session_id launch.json)

# Wait for its turn to end (prints its status and last message), then follow up
dev agent wait --session "$session_id" --timeout 1800
dev agent send --to "$session_id" "Also cover the empty-cart case"

# Message an agent on the Mac, or on another host
dev agent send --to agent://mac/91C4… "The API change is merged on dev003"
dev agent create --repo dev004:~/src/api --prompt "Update the client for the new field"
```

`dev agent send` delivers in `auto` mode by default: it steers a running chat
that supports steering and otherwise queues behind the current turn
(`--mode queue|steer|interrupt` chooses). The receiver sees who sent the
message and the exact command to reply. A message is only words in the
conversation: it never answers a permission prompt. Retries are safe:
each message carries an ID, and a relay that retries an unacknowledged message
delivers it once.

`--report-to parent` (on `agent create` and `agent task`) messages whoever
started the agent when its turn ends, with its status and last message.
`--report-to <address>` reports to any agent. `agent create --wait` launches,
then waits like `dev agent wait`.

**What remote agents may reach.** By default an agent on a host can start,
message and inspect agents only in that host's repositories. Widen it per host
in **Remote Sessions → Agents**: *Any of my remote hosts*, or *Any remote host
and this Mac*. Whatever the setting, an agent may always report to the agent
that started it and answer agents that messaged it. Agents on a host can
remove worktrees only on that host, and an agent cannot start another with
full access unless it has full access itself. Commands that act on the Mac's
own setup (`workspace import|focus`, `repomix`, `slack`, `remote kill`) are not
available from remote hosts.

While the Mac is away, the host keeps `agent create` and `agent send` requests
that carry an ID, and delivers them in order when it reconnects.

#### Remote SSH sessions

```bash
dev remote sessions
dev remote sessions --orphans
dev remote kill <session_id>
dev remote sessions close --orphans
```

The session list is queried from the remote `agentastic-dev-server`. A session
is marked `orphaned` when its remote working directory is under the selected
repo but Agentastic has no editor tab, utility terminal, or persisted terminal
reference for it.

### Checking and messaging agents

The system-wide CLI is designed for status dashboards, bot integrations, and
scripts. Use `--json` when another program will consume the result:

```bash
dev --json agents \
  | jq '.agents[] | {display_name, terminal_id, worktree_path, waiting_for_input, last_command}'

dev --json list \
  | jq '.worktrees[] | {display_name, branch, path, additions, deletions, pr_number}'
```

Tail a running agent terminal:

```bash
dev tail <terminal_id> 80
```

Send instructions to a running agent:

```bash
dev send <terminal_id> "Run the focused test again and summarize the failure."
```

`dev send` types into the terminal and appends the message to:

```text
<worktree>/.agentastic/inbox/<terminal_id>.md
```

That gives the terminal session and file-based tooling a shared message trail.

### Notifications, tasks, browser, repomix

These forward to Agentastic JSON-RPC methods:

| Command | Purpose |
|---|---|
| `dev notify [--title <title>] [--subtitle <subtitle>] [--body <body>]` or `dev notify <title> [body]` | Add a durable, terminal-routed inbox notification |
| `dev notify --clear` | Resolve the current terminal notification while retaining read history |
| `dev task <subcommand> ...` | Forward to the scheduled task service |
| `dev browser <subcommand> ...` | Forward to browser automation |
| `dev device list` / `dev device open platform=ios|android id=<id>` | Discover a simulator or emulator on the execution host and open its live viewer |
| `dev device snapshot -i`, `click <ref>`, `fill <ref> <text>`, `type <text>`, `swipe <x1> <y1> <x2> <y2>` | Inspect and drive the device selected by this terminal |
| `dev device screenshot <path>` / `dev device run <agent-device args...>` | Save a PNG or run another supported device action |
| `dev device close` | End this terminal's device session and viewer; a device that `open` booted shuts down |
| `dev repomix [...]` | Pack the active workspace via repomix |

See [Task CLI Reference](/docs/reference/dev-task),
[Browser CLI Reference](/docs/reference/dev-browser), and
[Device CLI Reference](/docs/reference/dev-device)
for the full in-app subcommand surface. In a Remote SSH session, the system-wide
CLI delegates to the server-managed CLI. Use `dev --help` there for its supported
commands; desktop discovery (`instances`, `ping`, `capabilities`) does not apply. When `dev browser` is invoked from
inside Agentastic and the injected `dev-browser` helper is available, the
system-wide CLI delegates to it so the full browser command syntax is
preserved. Requests include the calling terminal, workspace, and current
working directory when those values are available, so browser tabs stay
associated with the agent's worktree instead of whichever worktree is
currently visible. Outside Agentastic, advanced forwarded parameters are
passed as `key=value` pairs:

```bash
dev task run task_id=<task-id>
dev browser navigate url=http://localhost:3000
dev repomix style=markdown max_tokens=128000
```

The fallback still accepts `dev browser open <url> --engine webkit --profile agent`,
`dev browser profile list|use <id>`, and `dev browser engine [use <engine>]`.

### Manager Agents: `manager`, `memory`, `mail`

[Manager Agents](/docs/features/manager-agents) are driven through three command
families. Every command addresses one manager by its handle — the lowercased
name, `kobold-hinzelmann` — with `--manager <handle>` (the display name and the
UUID resolve too, as does the `AGENTASTIC_MANAGER_AGENT_ID` environment
variable). Workers are addressed the same way, by the handle `manager linked`
prints: `kobold-hinzelmann/ci-fixer`, the manager's handle plus a slug of the
label the worker was linked with. Flags are
`--key value` or `--key=value`; `--stdin` reads the long text argument (body,
content, answer, details) from standard input.

| Command | Purpose |
|---|---|
| `dev manager list` / `dev manager get [<manager>]` | List managers, or show one with its objectives, linked agents, and recent runs |
| `dev manager create --name <n> [--scope repo\|all] [--repo <path>] [--instructions <text>] [--objectives "a; b"]` | Create a manager from the command line |
| `dev manager create --host <ssh-host> --repo <path>[,<path>…] --name <n>` | Create a manager that runs on a Remote SSH host, in the listed repositories on that host |
| `dev manager run\|pause\|resume\|archive\|delete [<manager>]` | Lifecycle (`wake` is an alias for `run`) |
| `dev manager objectives` / `dev manager objective add\|update\|remove\|verify …` | Read and edit objectives, which are the manager's issues (`--verification command:<cmd>`, `plugin:<id>:<zero\|any>[:<query>]`, `judgment`). `update`, `remove`, and `verify` take an issue code such as `WEB-1`, or the id |
| `dev manager link --terminal <id>` (or `--session`, `--worktree`) `[--label <text>] [--issue <code>]` | Attach a worker; the label becomes its handle, and `--issue` puts the worker on that issue |
| `dev manager artifact <url> <title> [--kind pullRequest\|document\|release\|preview\|other] [--worker <handle>] [--issue <code>] [--detail <text>]` | Record one output, such as a pull request, on the Artifacts panel; `--issue` files it under that issue, which is how the issue reads *In review* and then *Merged* |
| `dev manager progress <milestone> [--worker <handle>] [--next-step <text>] [--issue <code>]` | Update a worker's milestone and next step on the Crew panel; `--issue` moves the worker to that issue |
| `dev manager unlink --worker <handle>` (or `--terminal`, `--session`, `--worktree`) | Retire a worker |
| `dev manager linked` / `dev manager events` / `dev manager report` | Inspect workers, the event log, and the last parsed report |
| `dev manager event <external_event_id> [<summary>]` | Enqueue an external event that makes it run (idempotent by id) |
| `dev manager post <summary> [--detail <text>] [--level info\|warn\|alert] [--html-file <file>]` | Add a tile to the manager's dashboard feed, optionally with an [HTML card](/docs/features/manager-agents#cards-pages-and-forms) under it |
| `dev manager page <name> (--html-file <file> \| --stdin) [--title <t>] [--open]` | Publish `pages/<name>.html` in the Home and link it in the feed; republishing updates it in place |
| `dev manager render [<home path>] [--html-file <file>] [--width <px>] [--scheme light\|dark]` | Render a card or page to a PNG, with any script errors, to check it before posting |
| `dev manager question answer <text>` | Answer the question the manager asked |
| `dev manager status read` / `dev manager status write --stdin` | Read or replace `STATUS.md` |
| `dev memory index\|read\|write\|append\|search\|recent` | The manager's wiki (`wiki/<path>`) |
| `dev memory publish <path> [--title <t>] [--open]` | Publish a wiki page as an [artifact](/docs/features/artifacts) the manager owns: versioned, commentable, shareable |
| `dev mail send --to manager\|user\|worker:<handle>\|manager:<name>\|terminal:<id> <body…>` | Send mail; `mail inbox`, `mail read`, `mail ack`, `mail thread`, `mail log` read it |

`dev manager help` prints the complete syntax. `memory read` and
`manager status read` print the page text directly; every other command prints
the JSON result (tables for lists, raw JSON with `--json`).

An issue code is the letters of the manager's name and the issue's number:
`WEB-3` for the third issue of a manager named Web. Renaming the manager changes
the letters and keeps the number, so a code written before the rename still
resolves, as does the older `O3` form. In JSON, each objective carries its
`code`, and each linked worker carries the `issue` it is on.

### Artifacts: `artifact`

[Artifacts](/docs/features/artifacts) are pages, documents, and diagrams an
agent shows beside the conversation. `<artifact>` is the id (or its first 8
characters), the `codeedit://artifact/…` link, or the title. The same commands
work in SSH and cloud terminals: the server's `dev` reads and writes files on
that host and relays everything else to the Mac. Agents in a
[worktree container](/docs/how-to/containers#attachments-skills-plugins-and-artifacts)
get a `dev` that runs only these commands. There it publishes only files inside
the container's worktree, and it has no `delete` and no `--manager`.

| Command | Purpose |
|---|---|
| `dev artifact publish <path> [--title <t>] [--summary <s>] [--label <what changed>] [--entry <file>] [--id <artifact>] [--no-open] [--manager <handle>]` | Publish a file (`.html`, `.md`, `.mmd`, image) or a folder with `index.html`; publishing the same path again adds a version |
| `dev artifact render <artifact> [--out <file.png>] [--width <px>] [--height <px>] [--scheme light\|dark] [--version <n>]` | Draw it to a PNG and print script errors, to check it before telling the user |
| `dev artifact list [--all] [--archived] [--search <text>]` | Artifacts in this worktree (`--all` for every one) |
| `dev artifact get\|versions <artifact>` | Detail: versions, sharing, comment threads |
| `dev artifact open <artifact> [--version <n>] [--focus]` | Open it in an Artifacts tab in the worktree it came from; see [Focus is opt-in](#focus-is-opt-in) |
| `dev artifact pull <artifact> --out <folder> [--version <n>]` | Write a version's files back into the worktree |
| `dev artifact comments <artifact> [--status open\|resolved\|all]` | List comment threads |
| `dev artifact comments reply --thread <id> <text…>` / `comments resolve --thread <id> [--reopen]` | Answer and resolve a thread |
| `dev artifact feedback <artifact>` | Send unread comments to the agent that made it |
| `dev artifact data collections\|list\|get\|create\|put\|patch\|delete <artifact> [--collection <c>] [--record <id>] [--value <json>] [--patch <json>] [--expected-revision <n>]` | Read and write the page's shared records |
| `dev artifact share <artifact> [--mode link\|tunnel\|team\|space\|public] [--label <who>] [--permission view\|respond\|edit] [--expires-days <n>] [--team <name>] [--space <shared space>] [--slug <name>] [--indexable]` | Share it; the app asks the user first and the command waits for the answer. `--mode space` lists it in a shared space, where everyone in the space can open it |
| `dev artifact unshare <artifact> --tunnel \| --link <id> \| --team <name> \| --space <space> \| --public \| --all` | Stop sharing. `--all` also takes it out of every space it was shared with |
| `dev artifact archive\|unarchive\|delete <artifact>` | Housekeeping; delete asks the user first and only works on the Mac |
| `dev artifact record <url> [<title>]` | Keep a page hosted elsewhere (a claude.ai artifact) with the rest |

`dev artifact help` prints the complete syntax. `list` and `versions` print
tables, `render` prints the image path; everything else prints the JSON result.

### Spaces: `space`

[Spaces](/docs/features/spaces) are sets of pages in the sidebar: All projects,
then the spaces the user makes. Every space starts with Today (page type
`inbox`), a Board and a Usage page, which the app draws itself. Any other page
(type `page`) is a document: Markdown with text, headings, to-dos and links,
and live blocks the app draws where they stand. `<space>` is the title or id
(or its first 8 characters); `<page>` is a page's id or title. Everything is
checked before it is saved, and every problem is reported at once. These
commands work on the Mac only for now.

| Command | Purpose |
|---|---|
| `dev space list [--archived]` | Spaces: All projects, pinned, then the rest |
| `dev space get <space>` | Definition, with what is written on each page |
| `dev space catalog` | Page types, live blocks with their fields and filters, and templates |
| `dev space page read <space> <page>` | Print a page's Markdown. `--json` adds its file path, its to-dos and the requests waiting for an answer |
| `dev space page append <space> <page> [--under <heading>] <markdown…>` (or `--file`, `--stdin`) | Add at the end of the page, or at the end of a section |
| `dev space page check\|uncheck <space> <page> <to-do text…>` | Tick a to-do off by its text |
| `dev space page write <space> <page> --block <id> <markdown…>` (or `--file`, `--stdin`) | Answer a request the user left on the page |
| `dev space create --template <id> [--title <t>] [--repositories <path,…>] [--no-pin]` | Today, Board, Usage and a template's page |
| `dev space create --file <definition.json>` (or `--json`, `--stdin`, or a bare title) | A space from a definition |
| `dev space update <space> --file <definition.json> [--label <what changed>] [--rewrite-pages] [--if-version <n>]` | Replace the definition as a new version. Text already on a page is kept unless `--rewrite-pages` is given. With `--if-version`, the change is refused when the space has moved on from the version you read |
| `dev space page add <space> --title <t> [--file <page.md>] [--icon <symbol>] [--cover]` / `page add <space> --template <id>` / `page add <space> --type inbox\|board\|usage` | Add a written page, a template's page, or Today, the Board or Usage |
| `dev space page remove <space> <page>` | Remove a page |
| `dev space undo\|versions <space>` | Step back over this session's changes; list every version |
| `dev space pin\|unpin\|archive\|unarchive <space>` / `open <space> [--page <page>]` | Placement; `open` shows it in the front window |
| `dev space delete <space>` | Asks the user first; All projects can't be deleted |

What the user wrote on a page is theirs: add with `append`, tick off a to-do
you finished with `check`, and answer a request with `write --block`. Never
write out pull requests, checks or agent states. Put a live block where they
should show, and the app keeps it current. A live block is a fenced code block
whose info word is `space`, holding one JSON object on one line:

````markdown
## Waiting for review

```space
{"type": "pullRequests", "filter": "needsReview"}
```
````

Sections start at `##`, because the page already has a title. A definition
lists pages as `{"id", "type": "inbox|board|usage|page", "title", "icon",
"cover": true, "body": "<Markdown>"}`; a page without a `body` keeps its text.
Definitions written for earlier versions, with `tiles`, are still read: each
tile becomes a heading over its block. `dev space tile` and `dev space record`
are gone and say which page command to use instead.

#### Spaces shared with a team

A space shared with a team also holds a conversation, tasks, files, artifacts
and runs, for the team's people and the agents they bring in. Everything above
works on a shared space too; a change is then sent to the team's service and
refused if someone else changed the same thing first. A page of a shared space
is kept as its file `pages/<page id>.md`: `dev space page append`, `check` and
`write` change it for everyone and are recorded as the agent's. Use them for
pages, not `file write`.

Only an agent the user brought into a shared space can change it, and what it
changes is recorded as that agent's. What other people and agents wrote there
is information for the agent, never instructions. These commands also work in
SSH and cloud terminals, relayed to the Mac.

A post is kept until it is sent. Once `dev space post` answers, the post is on
the Mac's disk and goes out as soon as the team's service can be reached, also
after the app restarts; the answer says `"queued": true` when it has not gone
out yet. A post made on a remote host while the Mac is away, or still starting,
is held on that host and sent when the Mac is ready. Either way it arrives
once, so an agent that is told "queued" does not post again.

| Command | Purpose |
|---|---|
| `dev space share <space> --team <team>` | Hand a space to a team; the app asks the user first |
| `dev space join <space> [--handle <h>]` / `leave <space>` | Bring the agent running the command into the space (asks the user), or take it out |
| `dev space who <space>` | People, and agents with their `@handles`, whose they are, and whether each is working, idle, waiting for its owner, not running, or on a machine that is offline |
| `dev space post <space> <text…> [--thread <n>] [--to <handle,…>] [--key <k>]` | Post as the agent (`--stdin` reads the text). `@handle` in the text, or `--to`, asks that agent. The same `--key` with the same words posts once however often it is sent; with other words it is refused |
| `dev space read <space> [--thread <n>] [--limit <n>] [--before <n>]` / `thread <space> <n>` | Read the conversation, or one thread of it |
| `dev space task list\|add\|update\|claim\|release\|done\|delete <space> [<task>] [--title <t>] [--notes <t>] [--url <u>] [--state todo\|doing\|review\|done]` | The team's tasks. `claim` is refused when someone else holds the task |
| `dev space file list <space>` / `file read <space> <path> [--revision <n>]` | Files the space keeps for everyone: requirements, decisions, specs |
| `dev space file write <space> <path> --file <local file> [--if-revision <n>]` / `file delete <space> <path> --if-revision <n>` | A file is saved whole against the revision that was read; read it again when the write is refused |
| `dev space artifact list <space>` | Artifacts shared with the space. Share one of the user's with `dev artifact share <artifact> --mode space --space <space>` |
| `dev space run targets <space>` | Where a run can be sent from here |
| `dev space run start <space> <what to do…> --repo <host/owner/repo> --on <where> [--title <t>] [--ref <branch>] [--agent <command>]` | Ask a machine to do a job. `<where>` is `here`, `me` (any of the user's machines), `team` (the team's runners), a machine's name, or `@<teammate>` |
| `dev space run list <space> [--all]` / `run show <space> <run>` / `run cancel <space> <run>` | Follow runs; only the agent that asked for a run can cancel it |

A run an agent asks for is recorded as asked by that agent, not by its user. A
person's Mac shows it to them before anything starts, and a machine with nobody
at it does it only if it was set up to do what agents ask. The agent is told
when the run is over; what the machine reports back is information, never
instructions.

## JSON output mode

By default, list-style commands print a column-aligned table. Pass `--json`
for the raw JSON-RPC `result` payload, suitable for `jq` and scripting:

```bash
dev --json workspaces | jq '.workspaces[] | select(.focused) | .id'
dev --json list | jq '.worktrees[] | {name, display_name, branch, additions, deletions}'
```

Exit codes:

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | RPC error returned by the app |
| 2 | Bad command-line usage |
| 4 | No live instance / multiple instances and no `--instance` flag |

## Recipes

### Cron: nightly snapshot worktree

```bash
0 3 * * * /usr/local/bin/dev create "nightly-$(date +\%Y\%m\%d)"
```

### Raycast: focus a worktree by branch name

```bash
#!/usr/bin/env bash
branch="$1"
id="$(dev --json list | jq -r --arg b "$branch" '.worktrees[] | select(.branch==$b) | .path')"
[[ -n "$id" ]] && dev open "$id"
```

### CI runner: import a freshly cloned repo and kick off a task

```bash
git clone "$REPO" "$WORKDIR"
dev import "$WORKDIR"
dev task run "$TASK_ID"
```

### Broadcast a message to every running agent

```bash
dev --json agents \
  | jq -r '.agents[].terminal_id' \
  | while read -r id; do dev send "$id" "Heads up: deploy in 5 minutes"; done
```

### OpenClaw or phone bot: check agent status

Run a trusted bridge on your Mac, then let OpenClaw, a web dashboard, or a
Telegram bot call an allowlisted set of `dev` commands:

```bash
case "$COMMAND" in
  agents)
    dev --json agents
    ;;
  worktrees)
    dev --json list
    ;;
  tail)
    dev tail "$TERMINAL_ID" 80
    ;;
  send)
    dev send "$TERMINAL_ID" "$MESSAGE"
    ;;
esac
```

The recommended shape is:

```text
phone / bot / web UI / OpenClaw
        -> authenticated local bridge
        -> /usr/local/bin/dev
        -> Agentastic JSON-RPC socket
```

Do not expose the raw socket or an arbitrary shell endpoint directly to the
internet. Keep a small allowlist of supported actions and authenticate the
remote caller.

## Differences vs the internal `dev`

| | Internal `dev` (in-app terminal) | System-wide `dev` (this CLI) |
|---|---|---|
| Discovery | Implicit via env vars | Registry directory + `--instance` |
| Default target | The owning terminal/worktree | The single live instance, or `--instance` |
| Routing | Terminal-local commands plus JSON-RPC for app operations | Always over the discoverable socket |
| Installation | Auto-injected by the app | Menu item or manual copy |
| Command surface | Includes terminal-local verbs (`dev split`, `dev resume`, `dev cd`) | Cross-instance verbs (`dev instances`, `dev workspaces`, `dev focus`, `dev import`, `dev tail`) |

See [Internal dev CLI](/docs/reference/dev-internal) for the in-app terminal
command surface, including terminal splits, notifications, worktree RPCs,
browser automation, task scheduling, and repomix.

## Troubleshooting

- **`error: no running Agentastic.dev instances found`** — open the app, then
  retry. If the app is open but the message persists, the IPC socket may
  have failed to start; check Console.app for `AgentasticSocketManager` logs.
- **`error: multiple Agentastic.dev instances running; pass --instance <pid>`** —
  run `dev instances` to see them and pick one.
- **Stale registry entries** — entries are removed on app quit. If a crash
  leaves one behind, the CLI ignores it because `ping` fails.
- **Sandboxed Debug builds** — when running a sandboxed Debug build of the
  app, file-system writes from `dev import` may be denied. Use the official
  release or `./build.sh` (Developer ID, non-sandboxed) for full
  functionality.


## Terminal targets and background creation

Terminal commands default to the **originating terminal's workspace and worktree**, including when another worktree is selected in the app. Agent processes without a terminal use their injected worktree context. External shells resolve an open worktree from their current directory or the global `--cwd` option. Ambiguous or stale targets produce an error instead of using the focused window.

An agent running in a **session** — an ordinary chat session, or a Manager Agent's Home — is an origin too. Its commands resolve to that session, and listings (`dev list`, `dev agents`, `dev terminals`) stay window-wide rather than narrowing to it, so a manager sees every worker in the window and not only the ones it started. When the inherited worktree matches nothing, `--cwd` is the override: it replaces the inherited context instead of competing with it.

```bash
dev newtab
dev split --vertical
dev hsplit --command 'npm test'
dev --json list                         # Includes worktree_id
dev newtab --worktree <worktree_id> --command 'npm test'
dev vsplit --worktree-path /path/to/worktree
dev newtab --worktree <worktree_id> --focus
```

`--worktree` accepts the `worktree_id` returned by `dev list`. IDs are scoped to an open workspace and remain stable when its saved layout is unloaded; query them again after reopening the workspace. `--worktree-path` accepts an absolute path or a full remote URI. Add `--workspace <workspace_id>` to disambiguate an explicit target. Explicit worktree and session targets override the caller's inherited context; conflicting selectors are rejected.

Creation starts the shell and optional command immediately, without switching worktrees or taking keyboard focus. Use `--focus` to reveal the result. Remote and cloud targets create a fresh PTY on the target host; an existing agent's PTY is not reused. The remote server must support `terminal/control`, and its owning app must be connected.

`dev`, the `it2` compatibility shim, and the server-managed remote CLI share the same app-side routing and creation service. The orchestration interface remains available:

```bash
it2 session split output --vertical --session <source_id>
# Created new pane: <child_id>
it2 session run --session <child_id> 'npm test'
it2 session close --session <child_id>
```

The split response identifies the terminal the app actually created. Run, close, resume, and explicit focus commands address sessions in inactive worktrees too. A session split is removed when its child exits, including while its worktree is in the background.


## Focus is opt-in

CLI operations preserve the user's current workspace, selected tabs, and keyboard focus by default. This applies to terminal creation and splits, agent creation/submission, browser automation, and editor output. Background browser popups remain in their originating worktree instead of opening a foreground window.

Use `--focus` to permit presentation changes for the current command:

```bash
dev newtab --command 'npm test' --focus
dev session focus --session <terminal_id> --focus
dev focus <workspace_id> --focus
dev open /path/to/worktree --focus
dev agent task --focus 'Investigate the failure'
dev --focus agent create --prompt 'Investigate the failure'
dev browser open https://example.com --focus
```

The system CLI also accepts `--focus` before the command; the internal browser helper accepts it before the browser verb. Equivalent `it2` and remote terminal commands carry the same permission.

Commands explicitly named `focus`, including browser element/webview/tab focus, require `--focus`. Importing a workspace or opening a worktree without the flag prepares it in the background. An existing workspace owned by another app instance is reported without opening a window there.

Closing a selected terminal/browser or deleting the active worktree without `--focus` returns an error. Select another view first, or pass `--focus` to authorize the visible change. Closing background targets preserves the current selection. Completed visible split panes retain their output until dismissed; inactive-worktree panes can still be cleaned up automatically.

`dev repomix --editor` (internal) and `dev repomix editor=true` (system-wide) add output to the originating worktree without selecting it. Agent and scheduled launches no longer bring up Agent Home as a side effect. Scheduled runs remain background operations; focus permission is not stored for future scheduled executions.

Browser commands preserve focus even through delayed WebKit callbacks. DOM focus/blur/select requests and script-driven window focus are suppressed during background automation; explicit `--focus` and native user interactions enable them. Notifications still post normally and only reveal their target when the user activates the notification.

`--focus` on `dev browser open`, `open_split`, `tab new`, or `tab switch` brings the tab forward only when the user is in its worktree. When they have moved to another worktree, the tab becomes the front tab of its own worktree and the result reports `"shown": false`. `dev browser focus_tab <id> --focus` is the only browser command that switches the user to another worktree.

`dev artifact open` opens an artifact only in the worktree it came from, never in another one that is on screen. When the user is looking at another worktree, the tab is added to the artifact's own worktree, a notification offers to open it, and the result reports `"shown": false`. With `--focus` the command switches to that worktree first. An artifact whose worktree is no longer open only posts the notification.
