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 → Commands → Custom commands |
| Prompt templates | Instructions used by built-in actions such as Commit, Create PR/MR, Fix CI, and Review | Settings → Commands → Prompt templates |
| Action routing | Provider, model, click behavior, and background dispatch for built-in agent actions | Settings → Agents → Routing and the selected provider’s model settings |
| Project scripts | Setup, development servers, watchers, and cleanup tied to a repository | Project settings or .superconductor/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.
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 → Agents, choose the scope, and find Routing. The app groups agent-backed actions by workload:
- Fast: Inline commit message, Create review request, Commit & push, and Commit.
- Thorough: Fix CI, Fix blocked merge, Fix comments, Fix changes, Resolve conflicts, and Review.
Choose a provider for each group. Then open that provider’s model settings and select its Fast and Thorough models. Choose a quick, economical model for Fast and a stronger reasoning model for Thorough when your provider offers both.
For example, set the Project scope’s Fast route to Codex and choose a fast Codex model. Commit and Create PR/MR then use that route in the project, while Review can remain on the Thorough provider and model. The model picker lists enabled models and accepts a custom model ID; confirm that the provider CLI supports any custom value.
Pin one action to a specific provider or model
Section titled “Pin one action to a specific provider or model”Use an override when one action should differ from its group:
- Expand Fast or Thorough under Routing and pin the action’s provider.
- Expand Advanced — per-action model pins under that provider’s model settings.
- Select the model beside the action.
An action-level pin wins over its Fast or Thorough model. A project pin wins over a workspace or global pin. Clear the pin to return to the group model.
Launch behavior is independent of model routing. In the expanded routing table, set normal click and ⌘-click to reuse a tab, open a new tab, prepare a prompt, submit it, or run in the background.
Customize a Git action’s instructions
Section titled “Customize a Git action’s instructions”Open Settings → Commands → Prompt templates, select the same scope, and edit the action’s Instructions and User message. 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.
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 → Commands 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 |
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, 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 provider and model, not the Fast Git-action group. To give a project’s custom commands a fast model:
- Open Settings → Agents and select the Project scope.
- Set Session default to the intended provider.
- In that provider’s model settings, set the Session model to the fast model.
- Leave the custom command’s Provider set to Default.
This changes the Session default for the scope, including normal new sessions that inherit it. Selecting a provider on the command bypasses Session default provider routing and uses that provider’s default or runtime model preference.
The current Settings UI does not expose a model picker on an individual custom command. Use per-action model pins for built-in Git actions. For an isolated user-defined command, review the selected model in the new tab before submitting, or dedicate a narrower project scope’s Session default to that workflow.
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.