DocsAutomation
View as Markdown

Programmatic Control

Control Agentastic from agents, scripts, schedulers, web dashboards, and phone bots

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, which keeps common Linux login profiles from selecting an older global CLI. It never overwrites an existing user or system-wide 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.

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.