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.

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 exactly one instance is responding, it is used.
3. Else, if primary.json points at one of the responding instances, it is used.
4. 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 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"

Notifications, tasks, browser, repomix

These delegate to the same JSON-RPC methods the in-terminal CLI uses:

Command	Purpose
dev notify <title> [subtitle] [body]	Show a banner via terminal.notify
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 dev-task.md and dev-browser.md for the full subcommand surface — those references apply unchanged.

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

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)

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.