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

Surface	Command	Best for
Agentastic terminal	`dev ...`	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 mode	`dev --json ...`	Automation with `jq`, dashboards, and bots
Direct socket	JSON-RPC over `AGENTASTIC_SOCKET_PATH`	Advanced 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:

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:

Flag	Purpose
`--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:

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

List worktrees with diff and PR state:

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

Tail terminal output:

dev tail <terminal_id> 80

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

dev instances
dev --instance 12345 --json agents

Communicate with an agent

Send text to a running terminal-backed agent:

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:

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

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:

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

Pack repository context:

dev repomix style=markdown max_tokens=128000

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

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

Schedule and trigger work

From inside Agentastic:

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

From outside Agentastic, trigger or inspect existing tasks:

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:

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:

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.