Run Commands

Define custom command buttons on your projects and run them inside any session with a single click. Each command runs in its own dedicated terminal, separate from the shell and agent.

Overview

Projects often need recurring commands — running tests, starting dev servers, building artifacts, linting code. Instead of typing these into the shell every time, you can define them as command buttons on your project. They appear in the Run tab of every session attached to that project.

Defining Commands

Each command has three properties:

  • Label — the button text shown in the UI (e.g., "Run Tests", "Dev Server")
  • Icon — a visual icon selected from 28 dev-oriented options (terminal, play, bug, rocket, etc.)
  • Command — the shell command to execute (e.g., npm test, make build)

Commands are configured at the project level via project settings. Every session for that project will see the same set of buttons.

Icon Picker

The icon picker offers 28 developer-oriented icons so you can visually distinguish your commands at a glance. Icons include terminal, play, stop, bug, rocket, code, database, globe, and more.

Runner Terminal

When you click a command button, it does not run in the shell or agent terminal. Instead, it spawns in a dedicated runner terminal — a separate PTY that keeps command output isolated.

Key behaviors:

  • The runner terminal is shown inline in the Run tab
  • Output streams in real time via WebSocket, just like the shell and agent terminals
  • A Stop button sends SIGINT to the running process group, letting you cancel long-running commands cleanly
  • Scrollback buffer is preserved — you can reconnect or switch tabs without losing output

Session-Level Overrides

Sometimes a session needs different commands than the project defaults. For example, you might want to run a specific test file related to the branch you are working on.

Abbado supports session-level command overrides: you can customize the command list for an individual session without affecting the project or other sessions. This is configured via the session settings or the API:

PUT /api/sessions/:id/commands
Content-Type: application/json

{
  "commands": [
    { "label": "Unit Tests", "icon": "flask", "command": "go test ./pkg/..." },
    { "label": "Lint", "icon": "eye", "command": "golangci-lint run" }
  ]
}

Agent Awareness

Agents automatically receive the list of available commands in their instructions. This means your AI agent knows which commands are available and can reference them in conversation — for example, suggesting you run tests after making changes.

The command definitions are injected into the agent's system instructions when the session starts, so the agent always has an up-to-date picture of the project's tooling.