Internal dev CLI

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, browser tabs, scheduled tasks, and repository packing. Worktree commands use the same JSON-RPC implementation as the system-wide CLI.

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:

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

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.

Remote SSH session commands are forwarded to the system-wide dev shim from inside Agentastic terminals. They list server-side Remote SSH PTYs and can kill individual sessions or orphaned sessions that no longer have matching local app state.

Notifications#

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

For simple messages, dev notify "Need approval" "The migration changes two existing columns." is also accepted.

Notifications are tied to the terminal/worktree context, retained in the durable inbox, and shown with a pane attention ring until the terminal actually receives focus or the item is marked read. dev notify returns only after its inbox mutation is durably committed.

Agent display names#

Set the sidebar name for the current agent directly from its terminal:

You can also target another open agent with --worktree <path> or --terminal <id>. An explicit selector takes precedence over the current terminal's workspace, including when the target is in another open workspace. If the selector exists in more than one workspace window, add --workspace <workspace_id> to disambiguate it. This is a display-only setting: the Git branch, worktree directory, terminal, and underlying agent process are never renamed.

Worktrees#

Worktree commands are handled by Agentastic over JSON-RPC, using the same bundled client and command syntax as the system-wide CLI:

The app owns branch and worktree creation, status, activation, and removal. The old terminal-only git backend and its .agentastic/ metadata commands have been removed, so commands such as dev matrix, dev archive, dev snapshot, and dev link are no longer part of this CLI.

dev rename is a backward-compatible alias for canonical dev agent rename. It updates the persisted agent display name only; it does not move the worktree directory or rename the branch. Use dev rename --clear to restore the directory-based name.

dev cd <worktree-name> remains a shell-local convenience because an external process cannot change its parent shell's working directory.

Browser automation#

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

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:

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:

Create tasks from the terminal:

See Task CLI Reference for schedule formats.

Sidebar agent tasks#

Submit work directly to the Agent sidebar without opening a terminal UI:

The injected workspace and worktree identifiers keep the new chat attached to the caller's active worktree. Each generated session ID creates a parallel tab. An explicit UUID continues an open tab or creates a tab with that ID when it is unknown:

The response acknowledges that the task was queued. Its created field means the request reserved a new tab; provider/model validation and agent launch complete asynchronously and surface errors inside that chat.

Use dev agent task --help for provider, model, thinking-level, run-mode, and working-directory options.

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.
• A worktree path is not found - use dev list to get the absolute path known to the active Agentastic workspace, then pass that path to dev status, dev open, or dev remove.