Internal dev CLI

Overview#

Attach the Slack plugin to use dev slack status, dev slack send, and dev slack reply. dev slack upload --channel CHANNEL_ID --file PATH [--thread TIMESTAMP] [comment] attaches an image or file from the agent's own filesystem, up to 50 MiB. It requires the bot scope files:write. Use --title and --alt-text for a display title and accessible image description. dev slack user --user USER_ID returns a member's profile. The CLI executes the target-local plugin before any Mac/daemon socket lookup. For containers, or an older remote CLI, use "$AGENTASTIC_SLACK_CLI" send --channel CHANNEL_ID "message"; Node 18+ is required. Replies use explicit --channel and --thread coordinates. The bot token is deployed to the selected execution environment, while the optional app-level token for incoming requests stays on the Mac.

dev slack tasks and dev slack listener inspect incoming requests on the main Mac app. They are not outbound Slack API operations. App notifications (dev notify, where supported) do not automatically become Slack messages.

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.

Tasks whose repository is on a connected Remote SSH host appear in the same list. They are stored and scheduled by the host's agentastic-dev-server, so they keep running while your Mac is asleep.

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 → Command Line 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.

Both support dev agent create through the same bundled client. Run dev agent create --help for the complete launch and monitoring workflow. To start a worker authorized to run unattended in the current app:

The inherited socket keeps the launch in the existing app. Save the returned terminal_id, inspect it with dev tail <terminal_id> 80, and use dev send <terminal_id> <text> for terminal input. The default run mode is interactive agent; the child's permissions do not inherit from the calling agent. For Codex, agentAutoApprove disables its sandbox and command approvals. On a timeout, inspect existing workers before retrying: the request may still be running. See creation flags and the API contract.

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.

Terminal targets and background creation#

Terminal commands default to the originating terminal's workspace and worktree, including when another worktree is selected in the app. Agent processes without a terminal use their injected worktree context. External shells resolve an open worktree from their current directory or the global --cwd option. Ambiguous or stale targets produce an error instead of using the focused window.

--worktree accepts the worktree_id returned by dev list. IDs are scoped to an open workspace and remain stable when its saved layout is unloaded; query them again after reopening the workspace. --worktree-path accepts an absolute path or a full remote URI. Add --workspace <workspace_id> to disambiguate an explicit target. Explicit worktree and session targets override the caller's inherited context; conflicting selectors are rejected.

Creation starts the shell and optional command immediately, without switching worktrees or taking keyboard focus. Use --focus to reveal the result. Remote and cloud targets create a fresh PTY on the target host; an existing agent's PTY is not reused. The remote server must support terminal/control, and its owning app must be connected.

dev, the it2 compatibility shim, and the server-managed remote CLI share the same app-side routing and creation service. The orchestration interface remains available:

The split response identifies the terminal the app actually created. Run, close, resume, and explicit focus commands address sessions in inactive worktrees too. A session split is removed when its child exits, including while its worktree is in the background.

Focus is opt-in#

CLI operations preserve the user's current workspace, selected tabs, and keyboard focus by default. This applies to terminal creation and splits, agent creation/submission, browser automation, and editor output. Background browser popups remain in their originating worktree instead of opening a foreground window.

Use --focus to permit presentation changes for the current command:

The system CLI also accepts --focus before the command; the internal browser helper accepts it before the browser verb. Equivalent it2 and remote terminal commands carry the same permission.

Commands explicitly named focus, including browser element/webview/tab focus, require --focus. Importing a workspace or opening a worktree without the flag prepares it in the background. An existing workspace owned by another app instance is reported without opening a window there.

Closing a selected terminal/browser or deleting the active worktree without --focus returns an error. Select another view first, or pass --focus to authorize the visible change. Closing background targets preserves the current selection. Completed visible split panes retain their output until dismissed; inactive-worktree panes can still be cleaned up automatically.

dev repomix --editor (internal) and dev repomix editor=true (system-wide) add output to the originating worktree without selecting it. Agent and scheduled launches no longer bring up Agent Home as a side effect. Scheduled runs remain background operations; focus permission is not stored for future scheduled executions.

Browser commands preserve focus even through delayed WebKit callbacks. DOM focus/blur/select requests and script-driven window focus are suppressed during background automation; explicit --focus and native user interactions enable them. Notifications still post normally and only reveal their target when the user activates the notification.

Agent orchestration#

New agents default to the main editor. --surface sidebar|utility selects a panel, while --focus controls whether the app selects it. The agent helper uses the system CLI implementation, including native-chat monitoring and interruption.

Run dev help agent for complete launch/recovery examples, or dev help agent create for creation flags. Use the returned session_id with dev agent status, tail, interrupt, queue, reveal, and move. See the agent command reference.