Custom commands and action routing
Commands let you save repeatable agent instructions or shell operations. Action routing decides which provider, model, tab, and submission behavior a built-in Git action uses. Configure both by scope so personal defaults, team conventions, and repository rules stay separate.
Custom commands and Git-action prompts are different
Section titled “Custom commands and Git-action prompts are different”| Setting | Use it for | Where to configure it |
|---|---|---|
| Custom commands | Your own named actions, such as “Update dependencies” or “Run release checks” | Settings → Prompts → Custom commands |
| Prompt templates | Instructions used by built-in actions such as Commit, Create PR/MR, Fix CI, and Review | Settings → Prompts → Prompt templates |
| Action routing | Provider, model, click behavior, and background dispatch for built-in agent actions | Settings → Routing |
| Project scripts | Setup, development servers, watchers, and cleanup tied to a repository | Project settings or .super.engineering/config.json |
Push, Update, Ready, Merge, and Delete worktree are direct Git or forge operations. Provider, model, and prompt settings do not turn them into agent commands.
Choose a scope
Section titled “Choose a scope”Settings offers Global, Workspace, and Project scopes. Global custom commands appear everywhere. Workspace commands are added after global commands, and project commands are added after both. They accumulate; a project command does not replace a command with the same name at a broader scope.
Use Global for personal tools, Workspace for conventions shared by related projects, and Project for repository-specific commands. Removing a workspace or project command leaves inherited commands intact.
To share commands with everyone who uses a repository, add them to its repository config instead. They appear in a Shared group between Workspace and Project commands. See Shared custom commands.
Prompt templates and action-routing values follow normal precedence instead: Project overrides Workspace, which overrides Global. Reset or choose Inherit to resume using the parent scope.
Route built-in Git actions
Section titled “Route built-in Git actions”Open Settings → Routing and choose Global, Workspace, or Project. Start with Session default, then choose different settings for either action group when needed:
- Fast: Inline commit messages, prompt enhancement, Create review request, Commit & push, and Commit. Automatic naming follows Fast by default.
- Thorough: Fix CI, Fix blocked merge, Fix comments, Fix changes, Resolve conflicts, and Review.
Each searchable route picker combines provider, profile, model, and thinking level. Select a model to see its supported thinking choices. Fast and Thorough follow Session default until customized; the row shows the default it follows. Choose Inherit or reset the route to restore that relationship. Undo last routing change reverses the last routing edit.
For example, choose a fast Codex model for the Project scope’s Fast route and a more capable model for Thorough. Commits and review requests then use Fast, while reviews and repairs use Thorough.
Pin one action to a specific provider or model
Section titled “Pin one action to a specific provider or model”Under Git buttons or Other actions, customize the action’s route and select its provider, profile, model, and thinking level in the same picker. An action override replaces its inherited group choice. Project settings override Workspace, which overrides Global.
Inherit, Session default, and CLI default have different meanings: inheritance follows the displayed parent route or scope; Session default follows the new-session route; a model’s CLI default leaves model selection to the provider’s configuration. A named model pins that choice. See Models and reasoning.
Launch behavior is separate from model selection. Use the Click and ⌘Click controls below applicable routes to choose tab reuse, a new tab, prompt preparation, submission, or background dispatch.
Customize a Git action’s instructions
Section titled “Customize a Git action’s instructions”Open Settings → Prompts → Prompt templates, select the scope, expand the action, and edit Instructions and User message where available. At Workspace or Project scope, enable an override to edit inherited text. Put durable policy in Instructions and the immediate task in User message. The app supplies the current worktree, diff, branch, target, and forge context when the action runs.
Branch naming rules also live on Settings → Prompts → Branch naming. The naming provider and model belong in Routing.
Routing and prompt templates resolve separately. Changing a prompt does not change its provider or model; changing a model does not change its prompt.
Add a custom command
Section titled “Add a custom command”- Open Settings → Prompts and select Global, Workspace, or Project.
- Under Custom commands, choose Add command.
- Enter a short name and the instruction or shell text.
- Configure the options below, then save.
| Option | Behavior |
|---|---|
| Icon | Uses an automatic icon based on the name or prompt, or a custom icon or emoji |
| Auto-submit | Runs immediately; when off, leaves the text ready for review |
| Launch behavior | Uses the current chat or opens a new tab; holding ⌘ uses the alternate mode |
| Opens in | Follows the default surface or selects Terminal or Chat UI for a new tab |
| Provider | Follows Session default routing, selects a provider, or selects None for raw shell |
| Model | Overrides the model for an explicitly selected provider |
| Thinking level | Overrides reasoning effort when the selected provider and model support it |
In Chat UI, command text becomes hidden setup instructions. With Auto-submit on, the command name becomes the visible message. Terminal sessions show the command text.
Run a command from the worktree’s command action card or search for Commands › name in the Command Palette. The picker groups available commands by Global, Workspace, Shared, and Project scope.
Use a fast model for a custom command
Section titled “Use a fast model for a custom command”A custom command with Provider: Default follows the scoped Session default, rather than the Fast action group. To give only that command a different model:
- Open Settings → Prompts → Custom commands and choose the scope.
- Expand the command and select an explicit Provider.
- Select its Model and a supported thinking level.
- Save the command. Leave an override at Default to use the applicable provider defaults.
To change the default for new sessions and commands together, edit Session default in Settings → Routing.
Run a raw shell command
Section titled “Run a raw shell command”Set Provider to None to run the command as shell input in a new Terminal tab. Auto-submit executes it immediately; turn Auto-submit off when the command has arguments to review or can modify data. Raw shell commands ignore Chat UI, provider, model, and current-chat choices.
Use project scripts instead when a command manages setup, a long-running development process, or cleanup. Custom commands suit manual, reusable actions; project scripts own repository lifecycle behavior.