Actions
Configure built-in Actions and create agent tasks available in every repository
Overview#
Actions are reusable, agent-powered tasks. Agentastic includes Actions for worktree naming, source-control operations, code review, and pull-request repair. You can also create your own Actions for prompts you use repeatedly.
Open Settings > Tasks to configure them. The grid shows each Action's Task, Tier, Model, Run In target, and Prompt. Changes apply anywhere the Action is used, including toolbar buttons, source-control menus, the pull-request panel, and the Tasks picker.
Creating a task#
Click Add Task in Settings > Tasks, then configure its name, optional description, prompt, tier, model, and execution target. A custom Action is stored in your global Agentastic settings and immediately appears in the Tasks picker for every existing or new repository and worktree. It is not copied into each repository's .agentastic/settings.json file.
Use the row's ellipsis menu to Edit Task…, Duplicate, or Delete a custom Action. Use Edit… in the Prompt column when you only need to change its prompt or browse the placeholder reference.
Model defaults#
Actions start in one of two tiers:
| Tier | Intended use | Examples |
|---|---|---|
| Fast | Short, latency-sensitive work | Worktree naming, commit messages, commits, and pull requests |
| Thorough | Deeper analysis or tasks that can modify the repository | Diff review, CI repair, review feedback, and conflict resolution |
Choose a Fast Model and Thorough Model at the top of Tasks settings. An action set to Default inherits the model for its tier. Automatic asks Agentastic to choose an available compatible agent.
You can select a different model for one action without changing the other actions in its tier. A per-action model is an override, not a second agent: it is used for an automatic captured task, a newly started terminal or chat, or the Utility Chat fallback for Primary Agent.
The model menus list the underlying agent providers that can perform an action. Agentastic itself is not offered as a model because it is the app's routing CLI, not a model provider; selecting it would route the action back into Agentastic instead of choosing the agent that does the work.
When a provider supports explicit model selection, you can choose its provider default or a specific model. For example, Claude Code supports the Haiku, Sonnet, and Opus aliases. A provider that does not expose model selection uses the model configured by that provider.
When Run In is Primary Agent, Agentastic continues the canonical live agent for the target worktree. That session keeps its current provider and model. The Action's configured model is used only if Agentastic must fall back to Utility Chat.
Editing a prompt#
Click Edit… in an Action's Prompt cell to open its prompt editor. The editor shows the complete template and the shared placeholder dictionary.
- Type a placeholder exactly as displayed, including its braces, such as
{diff}. - Placeholders are case-sensitive.
- All 15 documented placeholders are available to every built-in and custom Action.
- Agentastic supplies generic repository and worktree values when possible. Starting an Action from a pull-request surface can supply richer PR, CI, and review context; cached PR status is used when available.
- If a known placeholder has no value in the current invocation, it becomes
Not available in this task context. - Unknown placeholders are left unchanged in the rendered prompt.
- You can omit a placeholder when your custom prompt does not need that value.
- Use Use Built-in Prompt to replace an edited template with the current built-in prompt, then click Save.
Repository content inserted into a prompt can include untrusted text. Keep instructions that distinguish task directions from diffs, logs, comments, and other repository data when customizing a built-in prompt.
Run In#
Interactive repository actions support five execution targets:
| Target | Behavior |
|---|---|
| Primary Agent | Continues the canonical live agent for the exact target worktree. A user-designated Primary Agent is tried first; if that designation is stale, Agentastic can use another live agent in the same worktree. If no eligible live agent can accept the prompt, Agentastic starts a Utility Chat using the Action's configured model or tier default. It never sends the prompt to a bare shell, another worktree, or another workspace. |
| Editor Terminal | Starts a separate agent in a new editor terminal, using the Action's configured model or tier default. |
| Utility Chat | Starts a separate terminal-backed agent chat in the Utility Area. This is the default for new custom Actions. |
| Sidebar Chat | Starts a separate terminal-backed agent chat in the Agent sidebar. |
| Utility Terminal | Starts a separate agent in a raw Utility Area terminal. The target worktree must be active because the Utility Area belongs to the active worktree. |
Worktree Display Name and Inline Commit Message offer two compatible targets because Agentastic consumes their structured result instead of sending it to a coding agent:
- Headless (default) uses the selected agent's preferred interface without revealing the Utility Area, switching worktrees, or changing the current session selection. A local terminal-first Codex or Claude agent runs in its real terminal interface; Agentastic captures the result from a provider-native semantic record or durable transcript, then closes the hidden terminal or Chat session after a valid result. Failed sessions remain available for inspection.
- Utility Chat explicitly uses the Chat interface, activates the target worktree, and reveals the new structured chat while it runs.
These actions remain automatic-only and do not appear in the generic Tasks picker.
For a new terminal or chat, Agentastic first uses the Action's model override, then its Fast or Thorough tier default. Without an override, it can inherit the canonical agent's provider for the target worktree before choosing an automatically available provider. For Primary Agent, this selection applies only to its Utility Chat fallback.
Remote worktrees#
Primary Agent delivery, its Utility Chat fallback, and all four explicit new-agent surfaces support remote worktrees through Agentastic's remote terminal and session connection. Prompts remain scoped to the selected remote worktree. The chosen provider's command must be installed and usable on the remote host.
For a remote Utility Terminal, activate the target worktree first. A headless captured task can remain attached to a background remote worktree without activating it. Terminal transcript capture is local-only, so a terminal-first agent uses its Chat interface for captured tasks in remote or container-backed worktrees.
Built-in actions#
| Action | Default tier | Used from | Default Run In |
|---|---|---|---|
| Worktree Display Name | Fast | Agent Home, automatically after a new worktree is created | Headless |
| Inline Commit Message | Fast | Generate-message button in Source Control | Headless |
| Create Pull Request | Fast | Tasks, Source Control, and Diff Viewer | Primary Agent → Utility Chat |
| Commit | Fast | Tasks and Source Control | Primary Agent → Utility Chat |
| Commit & Push | Fast | Tasks and Source Control | Primary Agent → Utility Chat |
| Review Diff | Thorough | Tasks, Code Review, and Diff Viewer | Primary Agent → Utility Chat |
| Fix CI | Thorough | Tasks and pull-request panel | Primary Agent → Utility Chat |
| Fix Blocked Merge | Thorough | Tasks and pull-request panel | Primary Agent → Utility Chat |
| Fix Review Comments | Thorough | Tasks and pull-request panel | Primary Agent → Utility Chat |
| Fix Changes | Thorough | Tasks and pull-request panel | Primary Agent → Utility Chat |
| Resolve Conflicts | Thorough | Tasks and pull-request panel | Primary Agent → Utility Chat |
| Review Replies | Thorough | Tasks and pull-request panel | Primary Agent → Utility Chat |
Every interactive built-in Action appears in the Tasks picker. Worktree Display Name and Inline Commit Message remain automatic-only because Agentastic must consume their captured results. Running a PR-oriented Action from its pull-request surface supplies the richest context; when run from Tasks, it uses repository and cached PR context where available.
Placeholder reference#
The same dictionary is available in every built-in and custom Action prompt:
| Placeholder | Supplied value |
|---|---|
{userPrompt} | The original task submitted for the worktree, or a generic Action description when no original prompt is available |
{diff} | The relevant Git diff for the selected repository and worktree |
{branchName} | The current worktree branch or pull-request head branch |
{baseBranch} | The pull request's base branch or the repository's detected main branch |
{currentBranch} | The current worktree branch |
{targetBranch} | The branch used as the comparison target |
{commitHistory} | Relevant recent commits or commits between the target and current branches |
{pullRequest} | The selected or cached pull request reference and available details |
{ciFailures} | Failing-check details from the selected pull request, or a cached CI summary |
{ciLogs} | Available failure-log context or instructions for retrieving logs when they are not loaded |
{mergeStatus} | The available pull-request state or condition preventing a merge |
{reviewComments} | Actionable review comments gathered from the selected pull request |
{requestedChanges} | Change requests gathered from the selected pull request |
{conflicts} | The available merge or rebase conflict context |
{reviewReplies} | Follow-up review discussion from the selected pull request |
Known placeholders that cannot be supplied in the current invocation render as Not available in this task context. For example, review comments are normally available when an Action starts from a selected pull request, but may be unavailable when the same Action starts from the generic Tasks picker. Context is captured from the repository, worktree, diff, or pull request where you start the Action. Switching the active worktree after starting it does not retarget the prompt.
Resetting configuration#
For a built-in Action, use Use Built-in Prompt in the prompt editor to discard only the customized template. Open the row's ellipsis menu and choose Reset Task to restore its built-in tier, model inheritance, prompt, and execution target. Using the built-in prompt means future built-in prompt improvements can apply automatically.