DocsAutomation

System-wide dev CLI

Drive Agentastic.dev from any terminal, cron, or CI runner

Overview#

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#

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:

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:

code

~/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:

If --instance <pid> is given, that instance is used (or an error if it isn't responding to ping).
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.
Else, if exactly one instance is responding, it is used.
Else, if primary.json points at one of the responding instances, it is used.
Otherwise the CLI exits with an error and tells you to pass --instance.

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]`	Create a new worktree
`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.

Agents & terminals#

Command	Purpose
`dev agents`	List agent terminals (icon, waiting state, last command)
`dev agent create [flags]`	Create a new agent (worktree + terminal), matching the Agent Home form
`dev agent task <prompt> [flags]`	Submit a task to a new sidebar agent chat (`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]`	Open a new terminal tab in the focused workspace
`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

`dev agent create` flags#

code

--prompt <text>      Initial task (choose this or --prompt-file)
--prompt-file <path> Read the initial task from a UTF-8 file
--repo <path>        Path to an open repo. Default: focused workspace's active repo
--agent <command>    Agent CLI command (claude, codex, ...). Default:
                       last-used per-repo, else first auto-discovered available
--name <name>        Agent/worktree name. Default: random city name + number
--branch <name>      Alias for --name
--from <branch>      Base branch name, not a commit SHA. Default: repo/worktree settings
--label <name>       Apply a worktree label by display name (case-insensitive)
--mode <m>           worktree | local | container. Default: worktree
                       (or local if non-git)
--run-mode <m>       agent | agentAutoApprove | plan. Default: agent
--timeout <seconds>  Wait for a launch response, 1..3600 seconds. Default: 120

Creation uses an already-running instance and adds worker terminals to its existing workspace. It does not open a new application instance or workspace window. Inside Agentastic the inherited socket selects the parent app. Outside Agentastic, use dev instances and pass --instance <pid> before agent create when choosing among running builds. Help works even when the app is closed.

Choose the worker's permissions explicitly. agent is interactive and may pause for command approvals. agentAutoApprove applies the provider's auto-approve mode; for Codex this disables its sandbox and command approvals. Use it for a worker authorized to run unattended. Login, trust, and task questions may still require input. plan selects planning mode with the provider's permissions. The child does not inherit the parent agent's approval policy. Other agent and model selections follow repository defaults unless --agent selects a provider explicitly.

For an authorized unattended worker:

bash

dev --instance 12345 --json agent create \
  --repo ~/code/myrepo --agent codex --name fix-tests --mode worktree \
  --run-mode agentAutoApprove --prompt-file task.md > launch.json &&

terminal_id=$(python3 -c 'import json; print(json.load(open("launch.json"))["terminal_id"])') &&
dev --instance 12345 tail "$terminal_id" 80

Only use launch.json if creation exits successfully. The JSON contains instance_pid, workspace_id, terminal_id, worktree_path, branch, run_mode, status: "launched", and launches, an array of all created worker targets. The top-level terminal and path refer to the first worker for compatibility. This response acknowledges launch, not task completion. Persist the returned identifiers rather than selecting the first row from dev agents: that list can include an automatic naming helper as well as the implementation worker.

Use dev tail <terminal_id> 80 to inspect progress and approval/login prompts; dev agents lists workers, and dev send <terminal_id> <text> sends input to the specified terminal. Sending input does not change its configured permission policy. To continue a sidebar chat, use dev agent task --session <uuid> instead.

Timeouts, closed connections, malformed replies, and server errors exit nonzero. On timeout or connection loss the launch may still be running: inspect dev agents and dev tail before retrying, as another create can launch a duplicate. --timeout controls how long the client waits; it does not cancel the server's work or set a time limit on the worker's task.

`agent.create` JSON-RPC API#

Send agent.create to the selected instance's Unix socket. The required prompt is a nonempty string. Optional parameters are workspace_id, repo, agent, name (branch alias), from_branch, label, mode, and run_mode. mode accepts worktree, local, or container; run_mode accepts agent (the stable default), agentAutoApprove, or plan. prompt_file and timeout are client options: the CLI reads the file and sends prompt, and manages its own deadline.

json

{
  "id": "launch-fix-tests",
  "method": "agent.create",
  "params": {
    "repo": "/Users/me/code/myrepo",
    "name": "fix-tests",
    "agent": "codex",
    "mode": "worktree",
    "run_mode": "agentAutoApprove",
    "prompt": "Fix the failing tests and report the checks you ran."
  }
}

Read one newline-terminated response and verify the matching request id, the boolean ok, and the result or error object. Give creation more than the normal five-second discovery timeout: it includes worktree setup and provider startup. A successful result always identifies an actual worker terminal. Launch failures may leave a worktree or terminal to inspect; errors include available target paths. Requests are not idempotent: repeating an RPC request ID does not deduplicate a launch.

`dev agent task` flags#

dev agent task targets the worktree containing the caller's current directory, or the workspace's active worktree when no more specific context is available. Omit --session to create a parallel sidebar chat tab. Passing an open session UUID continues that chat; passing an unknown UUID creates a tab with that ID. The immediate response only acknowledges queueing. created says whether the request reserved a new tab, not whether agent launch has completed.

code

--session <uuid>     Continue an open chat, or create one with this UUID
--agent <id>         Agent definition/provider (for example claude-code or codex)
--provider <id>      Alias for --agent
--model <id>         Model option ID from the selected agent's catalog
--thinking <id>      Thinking-level option ID
--run-mode <mode>    agent | agentAutoApprove | plan
--cwd <path>         Resolve the owning workspace from this directory
--worktree <path>    Pin the task to this open worktree
--prompt <text>      Flag form of the positional prompt

Examples:

bash

dev agent task "Fix the failing checkout test"
dev agent task --agent codex --model o3 "Review the current worktree"
dev agent submit --session <uuid> "Run the focused test again"

`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.

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.

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 repomix [...]`	Pack the active workspace via repomix

See Task CLI Reference and Browser CLI Reference for the full in-app subcommand surface. 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

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 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.

System-wide dev CLI

Overview#

Installation#

Via the app menu (recommended)#

Manual#

Uninstall#

Instance discovery#

Command reference#

Discovery#

Workspaces & repos#

Worktrees#

Agents & terminals#

dev agent create flags#

agent.create JSON-RPC API#

dev agent task flags#

dev agent rename#

Remote SSH sessions#

Checking and messaging agents#

Notifications, tasks, browser, repomix#

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#

`dev agent create` flags#

`agent.create` JSON-RPC API#

`dev agent task` flags#

`dev agent rename`#

Differences vs the internal `dev`#