DocsAutomation
View as Markdown

Programmatic Control

Drive Agentastic from scripts, schedulers, dashboards, and phone bots — start agents, check status, submit work, and control browser and repo context.

Overview#

Agentastic exposes a local control plane through the dev CLI. You can control it from inside the app with the internal CLI, or from outside the app with the system-wide CLI.

Use this guide when you want to automate Agentastic from:

  • An AI agent running in an Agentastic terminal
  • Terminal.app or another editor
  • Cron, launchd, or a scheduled task
  • A local dashboard
  • OpenClaw or another orchestration layer
  • A Telegram, Slack, or phone-based bot that calls into a trusted local bridge

Control surfaces#

SurfaceCommandBest for
Agentastic terminaldev ...Agents controlling their own panes, browser, notifications, and worktrees
Any local terminal/usr/local/bin/dev ...Users and scripts controlling a running Agentastic instance
JSON modedev --json ...Automation with jq, dashboards, and bots
Direct socketJSON-RPC over AGENTASTIC_SOCKET_PATHAdvanced integrations running under the same local user

Most integrations should call the CLI instead of speaking JSON-RPC directly. The CLI handles instance discovery, parameter formatting, and human-readable output.

Start an agent from a script#

Create a new worktree and terminal-backed agent:

bash
dev agent create \ --repo ~/src/my-app \ --agent codex \ --name fix-checkout-tests \ --prompt "Fix the failing checkout tests and run the focused suite."

Useful flags:

FlagPurpose
--repo <path>Target an open repository
--agent <command>Choose the agent CLI, such as claude or codex
--name <name>Set the worktree/agent name
--from <branch>Choose the base branch
--label <name>Apply an Agentastic worktree label
--mode <mode>worktree, local, or container
--run-mode <mode>agent, agentAutoApprove, or plan

Check agent status#

List agent terminals:

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

List worktrees with diff and PR state:

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

Tail terminal output:

bash
dev tail <terminal_id> 80

Use --instance <pid> when multiple Agentastic instances are running:

bash
dev instances dev --instance 12345 --json agents

Submit work to the Agent sidebar#

Start a new terminal-backed chat session in the resolved worktree without opening a terminal UI:

bash
dev agent task --agent codex "Fix the failing checkout tests."

The result includes a stable session_id. Use it to continue the same chat; omit it to run another task in a parallel sidebar tab:

bash
SESSION_ID="$(dev --json agent task 'Inspect the failure' | jq -r .session_id)" dev agent submit --session "$SESSION_ID" "Apply the smallest fix and rerun it."

Supplying an unknown session UUID creates a tab with that ID, so clients can choose IDs before submitting. The response is a queued acknowledgement: accepted confirms enqueueing, while created reports whether this request reserved a new tab. Agent launch or provider/model errors appear in the chat.

Provider/model flags mirror the Agent Home prompt controls. Run dev agent task --help for the complete option list.

Set an agent display name#

Give an existing agent a user-facing name without changing its Git identity:

bash
dev agent rename --worktree /path/to/worktree "Checkout reviewer" dev agent rename --terminal <terminal_id> "Release planner" dev agent rename --workspace <workspace_id> --worktree /path/to/worktree "Checkout reviewer" dev agent rename --clear --worktree /path/to/worktree

From inside an agent's own terminal, omit the selector:

bash
dev agent rename "Checkout reviewer"

This is also the happy path for Remote SSH agents on remote server v0.8.13 or later. New remote PTYs use a daemon-managed dev and relay the rename to their owning Mac workspace. The daemon copies its exact running executable to an immutable versioned path under ~/.agentastic/bin and points ~/.agentastic/bin/dev at that copy. It also claims ~/.local/bin/dev when that path is unused and no full desktop CLI is installed, which keeps common Linux login profiles from selecting an older global CLI. On macOS, remote server v0.9.11 and later remove their own user-level link when the full desktop CLI is present, so the restricted rename helper cannot shadow commands such as dev ping. It never overwrites an existing user or desktop dev. If the daemon has just been upgraded, open a new remote terminal so it receives the new CLI environment. On remote server v0.8.15 and later, success means the owning Mac app validated and saved the display name; validation, persistence, and acknowledgment-timeout errors are printed by the remote CLI.

An explicit --worktree or --terminal selector overrides the calling terminal's workspace, so it can address an agent in another open window. Add --workspace <workspace_id> when the selector is ambiguous across windows.

The agent rename command only changes display_name. It does not rename the worktree directory, branch, terminal, or running agent. In contrast, dev agent create --name still chooses the new agent's technical worktree/branch name.

Communicate with an agent#

Send text to a running terminal-backed agent:

bash
dev send <terminal_id> "Run the focused tests again and summarize only failures."

dev send writes to the terminal and appends the message to the worktree inbox:

text
<worktree>/.agentastic/inbox/<terminal_id>.md

That gives interactive agents and file-based tooling a shared message trail.

Control browser and repo context#

From inside an Agentastic terminal:

bash
dev browser navigate "http://localhost:3000" dev browser wait load dev browser snapshot dev browser console errors

From outside the app, the system-wide CLI can forward browser commands to the resolved instance:

bash
dev browser list dev browser navigate url=http://localhost:3000

Pack repository context:

bash
dev repomix style=markdown max_tokens=128000

Inside Agentastic terminals, dev repomix also supports the full flag parser:

bash
dev repomix --include "CodeEdit/Features/IPC/**" --editor

Schedule and trigger work#

From inside Agentastic:

bash
dev task create \ --name "Daily smoke tests" \ --command "npm test" \ --schedule daily \ --hour 9 \ --minute 0

From outside Agentastic, trigger or inspect existing tasks:

bash
dev task list dev task run task_id=<task-id> dev task history task_id=<task-id>

Scheduled tasks are useful for recurring agent checkups, nightly test runs, cleanup jobs, and status reports.

Tasks scheduled for a repository on a Remote SSH host run on that host's agentastic-dev-server, so they fire even while your Mac is asleep or Agentastic is closed. Review, edit, run or delete them from Remote Sessions → Scheduled Tasks.

OpenClaw, phone, and web bot pattern#

Remote control should use a trusted bridge on your Mac:

text
Telegram / web UI / OpenClaw -> authenticated local service -> /usr/local/bin/dev --json ... -> Agentastic instance

For example, an OpenClaw action or Telegram bot command can map a small allowlisted command set to dev:

bash
case "$COMMAND" in agents) dev --json agents ;; worktrees) dev --json list ;; tail) dev tail "$TERMINAL_ID" 80 ;; send) dev send "$TERMINAL_ID" "$MESSAGE" ;; launch) dev agent create --repo "$REPO" --agent codex --name "$NAME" --prompt "$PROMPT" ;; esac

This lets you check agents from your phone, ask OpenClaw to poll agent status, or build a web dashboard around running Agentastic sessions.

Safety checklist#

  • Keep the JSON-RPC socket local to your user account.
  • Do not expose an unauthenticated shell endpoint to the internet.
  • Prefer an allowlist of bot actions instead of passing arbitrary text to sh -c.
  • Use --json for integrations and parse with jq.
  • Use --instance when multiple app instances are running.
  • Use absolute repo paths in unattended scripts.
  • Log the command, target instance, and result for remote controllers.