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 → Install Shell Integration… and follow the prompts. The installer copies a self-contained 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

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 mirror the in-terminal worktree verbs (dev list, dev create, …) but require the system-wide CLI to know the workspace it's targeting. The default is the active repo 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 remove <path> [force]`	Remove a worktree
`dev open <path>`	Activate a worktree in its window
`dev status <path>`	Full status payload for a worktree

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>      (required) Initial prompt to send to the agent
--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 to fork from. Default: current HEAD
--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

Examples:

bash

dev agent create --prompt "fix the failing test in foo_test.go"
dev agent create --repo ~/code/myrepo --agent claude --prompt "add a /health endpoint"
dev agent create --name feat/login --label "Auth" --prompt "implement OAuth"

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

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.13, then points ~/.agentastic/bin/dev at that immutable copy. When the name is unused, it also links ~/.local/bin/dev to the private entry point so common Linux login profiles continue to select it. It never replaces an existing user shim or a separate /usr/local/bin/dev installation on the server.

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]`	Show a banner notification
`dev notify --clear`	Clear the current terminal notification
`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	Direct (no fallback)	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 helpers, 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#

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#

`dev agent task` flags#

`dev agent rename`#

Differences vs the internal `dev`#