New command

Save a reusable shell command with a target, concurrency mode, restart policy, and notifications.

The new command page at /commands/new creates a reusable command definition — a named script, a rule for where it may run, and a policy for what happens when it exits.

Command

Field	Notes
Name	How the command appears in lists, quick actions, and run history
Description	Optional context shown alongside the name
Shell script	The script to execute

The script runs through the agent user’s non-interactive login shell.

Interactive input and PTY applications are not supported. A script that waits on a prompt, opens an editor, or expects a terminal will hang until the job times out.

Target scope

The target decides which agents and worktrees the command may run in, and whether you are asked to choose one at launch time.

Scope	Runs in	Chosen at launch
Any agent home	The home directory of any enrolled agent	You pick the agent
Specific agent home	One named agent’s home directory	Fixed
Any worktree	Any tracked worktree on any agent	You pick the worktree
Worktree in a repository	Any worktree belonging to one repository	You pick the worktree

Prefer the narrowest scope that still fits. A Specific agent home command cannot be launched against the wrong machine by accident, and a repository-scoped worktree command cannot wander into an unrelated checkout.

Concurrency

Concurrency decides whether command runs may share the same target. A target is one worktree for worktree commands or one agent home for agent-home commands.

Mode	Behavior
Requires exclusive	Runs alone. It waits for every participating run holding or queued ahead for the target, and later participating runs wait for it.
Non-exclusive	Shares the target with other non-exclusive runs. It waits for an exclusive holder or an exclusive run queued ahead of it.
Excluded	Ignores the command queue. It never waits for another command run and never makes one wait.

The default is Non-exclusive. Queue order prevents an exclusive run from being starved by a steady stream of new non-exclusive work.

A worktree command can still wait while Git or worktree work holds its codebase. It retries when the codebase becomes available instead of failing with a busy-codebase error.

Git and worktree operations

Enable Block Git operations while this command runs when the script can change repository or worktree state. While a worktree command with this setting is active, Git and worktree operations on the same codebase wait. Leave it off for scripts that only read files or run unrelated tools.

Exclusive commands always block Git and worktree operations, so the setting is enabled and locked when Requires exclusive is selected. Agent-home commands have no worktree codebase to block.

Restart policy

Policy	Restarts when
Never	The command runs once, whatever happens
On failure	The attempt exited non-zero or was killed by a signal
Always	Every exit, clean or not — useful for long-lived processes

Failed restart limit caps consecutive restarts. Leave it unset for Unlimited restarts.

The limit counts a burst of quick failures, not restarts over all time. An attempt that stayed up for at least a minute resets the counter before its exit is evaluated, so a process that runs for hours and then dies still gets a full budget of retries.

A manual Terminate never triggers a restart, regardless of policy.

Notifications

Notify when this command finishes is on by default. Turn it off for commands that run constantly or that you do not need to hear about. Which channels those notifications use — sidebar, browser, Web Push — is configured on the Notifications page.

Quick action

Show this command as a quick action puts the command on the pages of the things it targets: agent-home commands on agent pages, worktree commands on worktree pages.

Pick an Icon and a Button style — Default, Outline, Secondary, or Destructive. Use Destructive for anything that removes data, so it reads as dangerous at a glance.

Related pages

Commands

All definitions and the durable run history.

Edit command

Change a saved definition without disturbing past runs.