Actions are configurable buttons that appear in the session UI, allowing you to trigger agent prompts or terminal commands with a single click. Each action is defined per-project and can operate in one of two modes: agent (sends a prompt to the active agent) or terminal (executes a command in the session terminal).
Actions are configured in the Project Settings section of the Settings panel (gear icon in the top-right corner). The Actions sub-section is collapsible and lists all available action types.
Each action type supports multiple named actions. For example, under the Run type you might create a "Dev" action and a "Debug" action, each with its own mode and prompt.
To add an action:
When multiple actions exist for a type, you can reorder them using the up/down arrow buttons. The first action in the list is the default and is marked with a "default" badge. You can also rename an action by clicking the edit icon next to its name.
To remove an action, click the delete icon (×). A confirmation prompt ("Delete? Yes / No") appears inline before the action is removed.
| Action Type | Location | Description |
|---|---|---|
| Commit | Diff report header, session context menu | Commits the current changes |
| Merge | Session context menu | Merges session branch into base branch |
| Pull Request | Prompt input toolbar, session context menu | Creates a pull request from the session branch |
| Run | Prompt input toolbar | Runs the application |
| Build | Prompt input toolbar | Builds the application |
| Test | Prompt input toolbar | Runs the test suite |
| Browse | Prompt input toolbar | Opens the application in a web browser |
Action buttons only appear in the UI when at least one action of that type has been configured. Commit, Merge, and Pull Request actions that are not configured show a disabled placeholder in the session context menu.
When you define multiple actions for the same type, the UI displays a split button instead of a simple button:
If only a single action is defined for a type, a regular button is shown.
The Pull Request, Run, Build, Test, and Browse actions appear as icon buttons in the prompt input toolbar, between the terminal toggle and the config options bar. Each button displays a distinctive icon:
Hovering over a button shows a tooltip with the action name and its mode (e.g., "Run" or "Test (agent)"). When a type has multiple actions, hovering over the split button chevron opens the dropdown after a short delay.
Commit actions appear in the header of the diff report card, which is displayed when the agent reports file changes.
Commit, Merge, and Pull Request actions appear in the session context menu (kebab menu on each session item in the sidebar). The menu is structured as:
Commit, merge, and pull-request buttons start disabled when the menu opens and only enable once the worktree status has been fetched and confirms the action is relevant. If no actions are configured for a type, a disabled placeholder (e.g., "Commit (not configured)" or "Pull Request (not configured)") is shown.
Action prompts support variable substitution. The following variables are replaced at runtime with values from the session context:
| Variable | Replaced With | Example Value |
|---|---|---|
$SRC | The session's worktree branch name | acp-session/20260411-143458-abc123 |
$DEST | The session's base branch | main |
$LABEL | The session's label | add-support-for-pull-requests |
These variables work in all action types and in both terminal and agent mode prompts. They are especially useful for merge and pull-request actions where you need to reference branches and session context.
| Action | Mode | Prompt |
|---|---|---|
| Merge | Terminal | git checkout $DEST && git merge --no-ff $SRC |
| Merge | Agent | Merge branch $SRC into $DEST and resolve any conflicts |
| Pull Request | Terminal | gh pr create --head $SRC --base $DEST --title "$LABEL" --fill |
| Pull Request | Agent | Create a pull request from $SRC into $DEST titled "$LABEL". Write a detailed description summarizing the changes. |
| Commit | Agent | Commit all changes on $SRC with a descriptive message |
When an action is set to terminal mode, its behavior depends on where it is triggered from:
From the prompt input toolbar (Pull Request, Run, Build, Test, Browse):
From the session context menu (Commit, Merge, Pull Request):
This is useful for commands like npm run dev, npm test, open http://localhost:3000, or git checkout $DEST && git merge --no-ff $SRC.
When an action is set to agent mode, clicking its button sends the prompt text to the active agent as if you had typed it into the prompt input. The agent processes the prompt and responds accordingly.
Agent-mode actions support user command expansion. If the prompt text contains /command-name references (matching user-defined commands from the Commands section of Settings), they are resolved and expanded before being sent to the agent. For example, if you have a user command named commit with detailed commit instructions, setting the Commit action prompt to /commit will expand to the full command text.
Action configurations are stored in the project's settings.json file alongside other project preferences:
~/.braide/projects/<project-id>/settings.json
Each action is stored as an object with the following fields:
| Field | Type | Description |
|---|---|---|
id | string | The action type identifier (commit, merge, pull-request, run, build, test, browse) |
name | string (optional) | A custom display name for the action (e.g., "Dev", "Debug") |
mode | string | Either "agent" or "terminal" |
prompt | string | The prompt text or terminal command |
Multiple actions can share the same id — this is how you define multiple actions per type. The first action in the array for a given id is treated as the default.
| Action Type | Name | Command |
|---|---|---|
| Run | Dev | npm run dev |
| Run | Debug | npm run dev -- --inspect |
| Build | npm run build | |
| Test | npm test | |
| Browse | open http://localhost:3000 |
| Action Type | Name | Prompt |
|---|---|---|
| Commit | Commit | /commit |
| Commit | Commit & Close | /commit then close the attached GitHub issue |
| Merge | Merge | Merge branch $SRC into $DEST and resolve any conflicts |
| Pull Request | Create PR | Create a pull request from $SRC into $DEST titled "$LABEL". Write a detailed description summarizing the changes. |
| Test | Run the test suite and fix any failures |
| Action Type | Name | Command |
|---|---|---|
| Pull Request | Create PR | gh pr create --head $SRC --base $DEST --title "$LABEL" --fill |
| Pull Request | Draft PR | gh pr create --head $SRC --base $DEST --title "$LABEL" --fill --draft |
| Pull Request | PR to Upstream | gh pr create --head $SRC --base $DEST --title "$LABEL" --fill --repo upstream-owner/repo |
Pull-request actions work well with the gh CLI, which natively understands fork workflows and can create cross-repository pull requests. The --fill flag auto-populates the PR body from commit messages.
| Action Type | Name | Command |
|---|---|---|
| Merge | Fast-forward | git checkout $DEST && git merge --ff-only $SRC |
| Merge | Merge | git checkout $DEST && git merge --no-ff $SRC |
| Merge | Squash | git checkout $DEST && git merge --squash $SRC && git commit -m "Squash merge $SRC" |
After a terminal-mode merge action completes, the session's worktree branch ($SRC) is automatically checked out again so the worktree remains on the correct branch.
In these examples, the Run type has two named actions ("Dev" and "Debug"), which appear as a split button in the toolbar. The Commit type also has two actions — "Commit" as the default and "Commit & Close" as an alternative in the dropdown. The Merge type shows three strategies as separate actions in the session context menu. The Pull Request type demonstrates different PR creation strategies, including draft PRs and cross-repository PRs for fork workflows.