Terminal and commands

The agent runs commands to build, test, inspect and verify. Two modes decide how.

Background exec (default)

Commands run as a managed process and their output is read directly.

This is the default because it does not depend on shell integration — it works the same in an unusual shell, with a custom prompt, over SSH, and in a container.

VS Code terminal

Commands run in a visible VS Code terminal, and output is read through VS Code's shell integration API.

Choose this when you want to watch commands run in a terminal you can also type into.

Settings → Terminal → Execution mode.

When a command appears to hang

Nearly always shell integration in VS Code terminal mode. The command finished; the integration never reported it, so the agent waits out its timeout.

In order:

1. Switch to background exec. It removes the dependency entirely and is why it is now the default.
2. Raise the shell integration timeout. A shell with a heavy startup — a large .zshrc, a version manager — may need more than the default 4 seconds.
3. Try a simpler shell profile. toolsxpo.terminal.defaultProfile selects which one to use; a plain bash or zsh profile often works where a heavily customised one does not.

Approving commands

By default the agent asks before running anything. Auto-approve, in the menu above the prompt box, can grant standing permission per category — read-only commands are the safe thing to auto-approve; anything writing or executing is worth keeping as a decision.

For a hard boundary rather than a preference, use a hook: a rule asks the model not to run something, a hook makes it impossible.

Long output

Output beyond a few hundred lines is written to a log file and the agent is given the first error lines plus a pointer. A build log is mostly noise, and putting all of it into context crowds out the code being worked on.

See also

• Hooks
• Settings reference