Terminal & Shell Integration

Running commands — installs, builds, tests, git — is half of what makes the agent useful, so it pays to know exactly how execute_command works: where commands run, how output gets captured, and which knobs to turn when a shell misbehaves. This page covers the two execution paths, output capture and spillover, the full Settings → Terminal tour, and fixes for the classic failure modes.

Two ways commands run

Nexgile Code has two execution paths, switched by a single setting:

• Inline Terminal (default, and the recommended setting) — commands run in a robust background process runner, with output streamed straight into the chat. This path bypasses shell profiles, prompts, and plugins entirely, which makes it fast and immune to the many ways a customized shell can confuse output capture.
• VS Code terminal with shell integration — commands run in a real VS Code terminal using your shell profile, with VS Code’s shell integration used to detect command boundaries and exit codes. You get your aliases, your PATH tweaks, your prompt — and, occasionally, their side effects. The terminal is shown while the command runs.

The toggle is Settings → Terminal → Use Inline Terminal (recommended). Leave it on unless a command genuinely depends on your shell profile. All the “Advanced” terminal settings below only apply when it’s off.

Anatomy of a command run

When the agent wants to run something, the chat shows the exact command line with Run (approve) and reject controls — subject to your allow/deny lists and auto-approve settings. The tool call carries up to three parameters:

• command — the command line itself
• cwd (optional) — working directory, relative or absolute; validated to exist before running
• timeout (optional, seconds) — an agent-side timeout: when it expires the command keeps running in the background and the agent proceeds with the output collected so far. The model sets this for dev servers, watchers, and anything that never exits on its own.

Separately, your own commandExecutionTimeout setting (default 0 = no limit, max 600s) is a kill timeout — when it fires, the command is terminated, not backgrounded. See Command Guardrails & Limits.

While a command runs, output streams live into the chat, and two buttons appear: Continue While Running (let the agent move on while the command keeps going in the background — right choice for npm run dev) and Kill Command (abort it). Exit codes are reported to the agent when the process ends.

Output capture: previews and spillover

Command output can be enormous — a full test run or a verbose build can produce megabytes. Nexgile Code handles this with a preview-plus-archive model:

• The agent directly sees a preview of the output. Its size is Settings → Terminal → Command output preview size: Small (5KB), Medium (10KB, default), or Large (20KB).
• The full output is always saved to disk (outside your workspace, in task storage). When output exceeds the preview, the agent’s result includes an artifact id and a truncation notice.
• The agent retrieves more via the read_command_output tool: fetch by artifact id, optionally with a search pattern (grep-style line filtering), and offset/limit for paginating through large logs in chunks.

In practice this means nothing is ever lost: the agent skims the preview, and digs into the archive only when it needs to (“search the full build log for error TS”).

Tip

Small preview + read_command_output is the token-efficient combination for long-running verbose commands; Large is better when the critical information (a failing test name, a compile error) tends to appear early and you want it in context immediately.

Settings tour (Settings → Terminal)

Basic

Setting	Default	Notes
Command output preview size	Medium (10KB)	Small 5KB / Medium 10KB / Large 20KB, as above

Advanced — applies only when Use Inline Terminal is off; affects the VS Code terminal path and may require a window reload:

Setting	Default	When to touch it
Use Inline Terminal (recommended)	On	Turn off only if commands need your shell profile
Inherit environment variables	On	Mirrors VS Code’s terminal.integrated.inheritEnv; controls whether terminals inherit the parent process environment
Terminal shell integration timeout	5s (1–60s)	Raise if your shell starts slowly or you see “Shell Integration Unavailable” errors
Terminal command delay	0ms (0–1000ms)	Adds a small pause after each command so the terminal can flush output; use only if tail output goes missing
Enable PowerShell counter workaround	Off	Turn on if PowerShell output is missing or duplicated
Clear ZSH EOL mark	On	Omits zsh’s end-of-line % marker that can garble parsing
Enable Oh My Zsh integration	Off	For Oh My Zsh themes/plugins that expect shell integration
Enable Powerlevel10k integration	Off	For Powerlevel10k prompt users
Enable ZDOTDIR handling	Off	If zsh shell integration conflicts with your dotfiles

Long-running and interactive commands

• Long-running (servers, watchers): let the agent pass a timeout so the process backgrounds automatically, or click Continue While Running yourself. The process keeps running; the agent continues with the captured output.
• Interactive (commands that prompt for input): the Inline Terminal runs processes headless — there’s nowhere to type an answer, so a command waiting on stdin will just sit there. Prefer non-interactive flags (--yes, --no-input, CI=true), run the interactive step yourself in a normal terminal, or temporarily disable Inline Terminal so commands run in a visible VS Code terminal you can type into. Kill Command rescues a stuck run.

Terminal context-menu actions

The integration goes both directions — select text in any VS Code terminal, right-click, and the Nexgile Code submenu offers:

• Add Terminal Content to Context — attach the selected output to your next message
• Fix This Command — start a task to repair the failing command
• Explain This Command — get a plain-English explanation

You can also pull recent terminal output into any request with the @terminal mention.

Troubleshooting

Symptom	Fix
Commands hang or never report completion (VS Code terminal path)	Raise Terminal shell integration timeout; if it persists, switch Use Inline Terminal back on
“Shell Integration Unavailable” errors	Same as above — slow-starting shells need a longer timeout, or use the Inline Terminal
Output looks truncated to the agent	It is — by design. The agent can fetch the rest via read_command_output; raise Command output preview size if you want more in context up front
Tail of output missing (VS Code terminal path)	Set a small Terminal command delay (e.g. 50ms)
PowerShell output missing or duplicated	Enable the PowerShell counter workaround
Stray % characters / weird zsh parsing	Keep Clear ZSH EOL mark enabled
Command killed with a timeout message	Your commandExecutionTimeout fired — raise it, or exempt the command via the timeout allowlist (Command Guardrails)

Related

• Command Guardrails & Limits — allow/deny lists, kill timeouts, cost caps
• Auto-Approving Actions — auto-approving command execution safely
• Context Mentions — @terminal and friends
• Tool Reference — execute_command and read_command_output in detail