System-wide dev CLI

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

Via the app menu (recommended)

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):

1. /usr/local/bin/dev
2. /opt/homebrew/bin/dev
3. ~/.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:

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

Uninstall

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

Instance discovery

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

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

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

Resolution rules:

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

You can always inspect the registry with:

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

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

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"

Remote SSH sessions

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:

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

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

Tail a running agent terminal:

dev tail <terminal_id> 80

Send 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>.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> [body]	Show a banner 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:

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:

dev --json workspaces | jq '.workspaces[] | select(.focused) | .id'
dev --json list | jq '.worktrees[] | {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"; 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:

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:

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.