---
title: Internal dev CLI
description: "Terminal-local dev commands for agents and in-app shells — terminal control, notifications, worktrees, browser automation, and repomix."
updated: "2026-11-07"
---

## Overview

Attach the [Slack plugin](/docs/features/slack) 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:

```bash
dev newtab
dev split
dev vsplit
dev hsplit
dev resume
dev ls
dev remote sessions
dev remote kill <session_id>
dev remote sessions close --orphans
```

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

```bash
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.

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:

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

dev notify --clear
```

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:

```bash
dev agent rename "Checkout reviewer"
dev agent rename --clear
# Backward-compatible aliases:
dev rename "Checkout reviewer"
dev rename --clear
```

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:

```bash
dev list
dev create checkout-flow main
dev status /absolute/path/to/checkout-flow
dev open /absolute/path/to/checkout-flow
dev remove /absolute/path/to/checkout-flow false
```

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:

```bash
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](/docs/reference/dev-browser) for the full command surface.

## Mobile devices

`dev device` uses the same mobile testing commands locally and over Remote SSH:

```bash
dev device list
dev device open platform=ios id=<id-from-list>
dev device apps
dev device app-open <app-id> --foreground
dev device snapshot -i
dev device screenshot /absolute/path/evidence.png
dev device close
```

The simulator or emulator runs on the agent's execution host. A remote Mac
supports iOS and Android; a Linux host supports Android. The live viewer appears
in the connected Mac app over SSH. Cloud/container device viewers and routing a
Linux agent to a separate Mac simulator are not supported.

Enable the Devices plugin to deliver the `device-use` skill, or attach the skill
directly. See the [Device CLI Reference](/docs/reference/dev-device) for prerequisites,
commands, and troubleshooting.

## Repomix

`dev repomix` packs repository context for AI consumption:

```bash
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.

## Feedback

`dev feedback` opens Agentastic's feedback form with the report already filled in — useful for a human, and useful for an agent that just hit a wall:

```bash
dev feedback "The terminal cursor blinks too fast"
dev feedback --type bug --area terminal "Cursor disappears after split"
dev feedback --title "Slow diff" --type performance --area git --email me@example.com "Large diffs take 10s"
```

| Flag | Values |
|---|---|
| `-t, --title <text>` | Brief summary |
| `-e, --email <email>` | Email for follow-up |
| `--type <type>` | `bug`, `feature`, `crash`, `performance`, `general` |
| `--area <area>` | `editor`, `navigator`, `terminal`, `git`, `extensions`, `settings`, `other` |

The same form is at **Help → Send Feedback**. It opens prefilled and nothing leaves your Mac until you press
**Submit**; you can attach up to 10 images first, or paste a screenshot with <kbd>Cmd</kbd>+<kbd>V</kbd>.

## Scheduled tasks

`dev task` manages Agentastic scheduled tasks:

```bash
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>
dev task memory.read task_id=<task-id>
dev task memory.append task_id=<task-id> content=<markdown>
dev task trigger.event task_id=<task-id> trigger_id=<id> external_event_id=<id>
```

Create tasks from the terminal:

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

See [Task CLI Reference](/docs/reference/dev-task) 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:

```bash
dev agent task "Fix the failing checkout test"
dev agent task --agent codex --model o3 "Review this worktree"
```

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:

```bash
dev agent submit --session <uuid> "Run the focused test again"
```

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](/docs/reference/dev-system) when something outside the app needs to launch, inspect, or message agents.

The Remote SSH CLI is a separate server-managed client. Its command surface is
smaller than the desktop CLI: use `dev --help` on that host. Desktop discovery
commands such as `instances`, `ping`, and `capabilities` are not remote readiness
checks. Device commands follow the shared workflow above; devices and evidence
paths belong to the execution host.

Both desktop forms support `dev create --prompt` and `dev agent create` through the
same bundled client. Run `dev create --help` for all launch flags, including
`--agent`, `--model`, `--thinking` (alias `--thinking-level`), and `--label`.
`--label` creates missing repository sidebar labels automatically. Use
`dev label --help` to list, create, edit, remove, assign, unassign, collapse, or
expand labels. Without a prompt, `dev create [branch] [from_branch]` creates a
worktree only. See [label commands](/docs/reference/dev-system#labels). To
start a worker authorized to run unattended in the current app:

```bash
dev agent create --repo /path/to/repo --agent codex --name fix-tests \
  --mode worktree --run-mode agentAutoApprove --prompt-file task.md
```

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](/docs/reference/dev-system#dev-agent-create-flags).

## 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.

```bash
dev newtab
dev split --vertical
dev hsplit --command 'npm test'
dev --json list                         # Includes worktree_id
dev newtab --worktree <worktree_id> --command 'npm test'
dev vsplit --worktree-path /path/to/worktree
dev newtab --worktree <worktree_id> --focus
```

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

```bash
it2 session split output --vertical --session <source_id>
# Created new pane: <child_id>
it2 session run --session <child_id> 'npm test'
it2 session close --session <child_id>
```

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:

```bash
dev newtab --command 'npm test' --focus
dev session focus --session <terminal_id> --focus
dev focus <workspace_id> --focus
dev open /path/to/worktree --focus
dev agent task --focus 'Investigate the failure'
dev --focus agent create --prompt 'Investigate the failure'
dev browser open https://example.com --focus
```

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.

`--focus` on `dev browser open`, `open_split`, `tab new`, or `tab switch` brings the tab forward only when the user is in its worktree. When they have moved to another worktree, the tab becomes the front tab of its own worktree and the result reports `"shown": false`. `dev browser focus_tab <id> --focus` is the only browser command that switches the user to another worktree.

### 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](/docs/reference/dev-system#launching-and-monitoring-workers).
