System-wide dev CLI
Drive Agentastic.dev from any terminal, cron job, or CI runner — installation, instance discovery, the command reference, and JSON output.
On this page
- Overview
- Installation
- Via the app menu (recommended)
- Manual
- Uninstall
- Instance discovery
- Command reference
- Discovery
- Workspaces & repos
- Worktrees
- Creating tasks and grouping agents
- Labels
- Agents & terminals
- Checking and messaging agents
- Notifications, tasks, browser, repomix
- Manager Agents: manager, memory, mail
- Artifacts: artifact
- Spaces: space
- JSON output mode
- Recipes
- Cron: nightly snapshot worktree
- Raycast: focus a worktree by branch name
- CI runner: import a freshly cloned repo and kick off a task
- Broadcast a message to every running agent
- OpenClaw or phone bot: check agent status
- Differences vs the internal dev
- Troubleshooting
- Terminal targets and background creation
- Focus is opt-in
Overview#
For 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 theAGENTASTIC_TERMINAL_IDandAGENTASTIC_SOCKET_PATHenvironment 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):
/usr/local/bin/dev/opt/homebrew/bin/dev~/.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:
cp "/Applications/Agentastic.dev.app/Contents/Resources/dev-system.bash" /usr/local/bin/dev
chmod +x /usr/local/bin/devUninstall#
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>.jsonThe 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:
- If
--instance <pid>is given, that instance is used (or an error if it isn't responding toping). - Else, if
AGENTASTIC_SOCKET_PATHis set and responding, that socket is used. This keeps calls made from Agentastic terminals pinned to their owning app instance. - Else, if exactly one instance is responding, it is used.
- Else, if
primary.jsonpoints at one of the responding instances, it is used. - 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:
dev instancesCommand 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:
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.
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.
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-1Agents & 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 selectionCreation 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:
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 resultaccepted 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:
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:
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:
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:
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 namedev 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).
# 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#
dev remote sessions
dev remote sessions --orphans
dev remote kill <session_id>
dev remote sessions close --orphansThe 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:
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:
dev tail <terminal_id> 80Send instructions to a running agent:
dev send <terminal_id> "Run the focused test again and summarize the failure."dev send types into the terminal and appends the message to:
<worktree>/.agentastic/inbox/<terminal_id>.mdThat 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= |
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,
Browser CLI Reference, and
Device CLI Reference
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:
dev task run task_id=<task-id>
dev browser navigate url=http://localhost:3000
dev repomix style=markdown max_tokens=128000The 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 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 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 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 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
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 |
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 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:
## 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:
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#
0 3 * * * /usr/local/bin/dev create "nightly-$(date +\%Y\%m\%d)"Raycast: focus a worktree by branch name#
#!/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#
git clone "$REPO" "$WORKDIR"
dev import "$WORKDIR"
dev task run "$TASK_ID"Broadcast a message to every running agent#
dev --json agents \
| jq -r '.agents[].terminal_id' \
| while read -r id; do dev send "$id" "Heads up: deploy in 5 minutes"; doneOpenClaw 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:
case "$COMMAND" in
agents)
dev --json agents
;;
worktrees)
dev --json list
;;
tail)
dev tail "$TERMINAL_ID" 80
;;
send)
dev send "$TERMINAL_ID" "$MESSAGE"
;;
esacThe recommended shape is:
phone / bot / web UI / OpenClaw
-> authenticated local bridge
-> /usr/local/bin/dev
-> Agentastic JSON-RPC socketDo 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 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 forAgentasticSocketManagerlogs.error: multiple Agentastic.dev instances running; pass --instance <pid>— rundev instancesto 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
pingfails. - Sandboxed Debug builds — when running a sandboxed Debug build of the
app, file-system writes from
dev importmay 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.
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:
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:
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 --focusThe 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.