Skip to main content

Use Terminals, Setup Scripts, and Run Scripts

Agent Manager keeps terminals attached to the selected worktree. Commands run in that worktree, not in the main checkout.

Open a terminal​

ActionShortcut
New terminal tab in the main areaCtrl+Shift+T
New terminal tab in the side panel, when a side terminal has focusCtrl+T
Focus or hide the terminalCtrl+/
Previous or next terminalCtrl+Shift+[ / Ctrl+Shift+]

On macOS, use Cmd instead of Ctrl. You can also run the matching Agent Manager commands from the Command Palette.

The terminal button opens either an Agent Manager panel terminal or a VS Code terminal. Choose it from the button's dropdown; each panel remembers its choice.

Check the terminal's working directory before running a command. A command meant for another worktree can read or change the wrong checkout.

Prepare new worktrees with a setup script​

A setup script runs before the agent starts in a new worktree. Use it for project-local preparation, such as installing dependencies or generating files.

Agent Manager looks for the script in .aicockpit/ at the repository root:

  • setup-script or setup-script.sh on Linux and macOS;
  • setup-script.ps1, setup-script.cmd, or setup-script.bat on Windows.

To create or edit it, open the project settings in Agent Manager and use Worktree Setup Script. Keep the script safe to run more than once, and never put credentials in it.

The script runs inside the target worktree while it is Setting up worktree. Select Stop setup script to interrupt it. If it fails, the terminal shows the exit code: fix the script for future worktrees, and run the missing steps in the worktree's terminal.

Start the project with a run script​

A run script starts the project, for example a development server. It runs in the selected worktree, or in the repository root for the local checkout.

  1. Select Configure run script to create .aicockpit/run-script (or the .ps1, .cmd, or .bat variant on Windows) from a template.
  2. Replace the commented examples with the command that starts your project.
  3. Press Ctrl+E (Cmd+E on macOS), or select Run script, to start it.

The run script uses the same terminal destination as the terminal button.