> ## Documentation Index
> Fetch the complete documentation index at: https://ai-development-environment.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/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
All definitions and the durable run history.
Change a saved definition without disturbing past runs.