Internal dev CLI

Terminal-local Agentastic automation commands for agents and in-app shells

Overview

The internal dev CLI is injected into terminals opened inside Agentastic. It gives agents and users terminal-local control over the app: notifications, panes, sessions, worktrees, browser tabs, scheduled tasks, and repository packing.

This CLI is not installed globally. Agentastic creates a temporary shim directory, prepends it to PATH, and injects context for the current terminal.

Injected context

Agentastic terminals receive environment variables like:

Variable	Purpose
`AGENTASTIC_TERMINAL_ID`	The owning terminal session ID
`AGENTASTIC_SOCKET_PATH`	Local Unix socket for JSON-RPC requests
`AGENTASTIC_BROWSER_ID`	Current browser tab ID, when a browser tab is active
`AGENTASTIC_APP_INSTANCE_ID`	Running app instance ID
`AGENTASTIC_APP_BUNDLE_PATH`	App bundle path for URL-scheme fallbacks
`AGENTASTIC_SHIM_DIR`	Temporary directory containing the injected shims

The internal CLI uses this context to route commands to the right window, worktree, terminal, and browser tab.

Terminal control

Use terminal commands to create tabs, split panes, and address sessions:

dev newtab
dev split
dev vsplit
dev hsplit
dev resume
dev ls

For scripts that need an addressable pane, create a session split:

dev session split output --vertical
dev session run --session <session_id> "npm test"
dev session focus <session_id>
dev session close --session <session_id>

dev split creates a pane near the current terminal. dev session split output also prints the new session ID so a script or agent can run commands in it later.

Notifications

Agents can use dev notify to surface state through Agentastic's notification system:

dev notify --title "Need approval" \
  --subtitle "auth-codex" \
  --body "The migration changes two existing columns."

dev notify --clear

Notifications are tied to the terminal/worktree context, so they can bring attention back to the right agent session.

Worktrees

The internal CLI includes git worktree helpers for multi-agent workflows:

dev info
dev create checkout-flow --agents claude,codex
dev create docs-refresh --from main
dev create compare-all --group all
dev list
dev status checkout-flow
dev diff checkout-flow claude codex
dev matrix
dev open checkout-flow

Common cleanup commands:

dev remove checkout-flow-codex
dev remove checkout-flow --all --force
dev archive checkout-flow --keep-branches
dev prune --dry-run
dev stale --days 14

Agent lifecycle and handoff commands:

dev stop checkout-flow-codex
dev start checkout-flow-codex
dev exec checkout-flow-codex "npm test"
dev message checkout-flow-codex "Use the simpler reducer."
dev transcript checkout-flow-codex --tail 80
dev snapshot checkout-flow-codex --name before-refactor
dev fork checkout-flow-codex checkout-flow-cleanup
dev clone checkout-flow-codex checkout-flow-review
dev events --limit 20

Worktree relationship commands:

dev link create checkout-flow-api checkout-flow-ui --type dependency
dev link list checkout-flow-api
dev link remove checkout-flow-api checkout-flow-ui

The worktree helpers store metadata under .agentastic/ in the repository and use git for branch/worktree operations.

Browser automation

dev browser controls Agentastic's built-in browser over the local socket:

dev browser list
dev browser navigate "http://localhost:3000"
dev browser wait load
dev browser snapshot
dev browser click "@e5"
dev browser fill "input[name=email]" "user@example.com"
dev browser console errors
dev browser screenshot -o ./screenshot.png

Use this when an agent needs to verify UI behavior, inspect console errors, test forms, or capture screenshots without leaving the terminal.

See Browser CLI Reference for the full command surface.

Repomix

dev repomix packs repository context for AI consumption:

dev repomix
dev repomix --style markdown --editor
dev repomix --include "CodeEdit/Features/IPC/**,CodeEdit/ShellIntegration/**"
dev repomix --ignore "Tests/**" --max-tokens 128000 --copy
dev repomix --stdout

It can write to a file, print to stdout, copy to the clipboard, or open the output in an editor tab.

Scheduled tasks

dev task manages Agentastic scheduled tasks:

dev task list
dev task history
dev task run <task-id>
dev task pause <task-id>
dev task resume <task-id>
dev task delete <task-id>

Create tasks from the terminal:

dev task create \
  --name "Nightly tests" \
  --command "npm test" \
  --schedule daily \
  --hour 2 \
  --minute 0

See Task CLI Reference for schedule formats.

Internal vs system-wide

	Internal `dev`	System-wide `dev`
Where it runs	Agentastic terminals	Any terminal or local process
Targeting	Current terminal/worktree/browser context	Discovered app instance, or `--instance`
Setup	Automatic shell integration	Install from Agentastic -> Install Shell Integration
Best for	Agents controlling their own workspace	Users, scripts, schedulers, bots, and external controllers
Extra context	`AGENTASTIC_TERMINAL_ID`, `AGENTASTIC_BROWSER_ID`, current worktree	Instance registry and JSON output

Use the internal CLI when an agent is operating from inside Agentastic. Use the system-wide dev CLI when something outside the app needs to launch, inspect, or message agents.

Troubleshooting

dev: browser script not found or dev: repomix script not found - restart the Agentastic terminal so the shim directory is recreated.
AGENTASTIC_SOCKET_PATH is not set - the command is not running in an Agentastic-injected terminal. Use the system-wide CLI or open a new Agentastic terminal.
Browser commands target the wrong tab - pass --browser-id <id> or run dev browser list to inspect tabs.
Worktree commands fail outside git - run them from a git repository or use the system-wide dev agent create --mode local flow for non-git workspaces.