Shell & Terminal

Bash Tool

The bash tool executes shell commands in your project's working directory. It is one of the agent's most versatile tools -- used for running tests, installing packages, executing build scripts, interacting with git, and any other terminal operation.

How It Works

• The command runs in the project root directory.
• The shell environment is initialized from your user profile (bash or zsh).
• stdout and stderr are captured and returned to the agent.
• The exit code is included so the agent knows if the command succeeded or failed.
• The working directory does not persist between calls -- each command starts from the project root.

# Run tests
bash command="npm test" description="Run the test suite"

# Install a package
bash command="npm install zod" description="Install zod for validation"

# Check git status
bash command="git status" description="Show working tree status"

# Run a long build with extended timeout
bash command="npm run build" timeout=300000 description="Build the project"

Timeouts

Every bash command has a timeout to prevent runaway processes from blocking the agent. The default timeout is 120 seconds (2 minutes), and the maximum is 600 seconds (10 minutes).

If a command exceeds its timeout, the process is terminated and the agent receives a timeout error. The agent will either retry with a longer timeout, break the command into smaller steps, or ask you for guidance.

Sandbox Mode

Sandbox mode adds OS-level isolation to bash commands, restricting what the command can access on your filesystem and network. It uses platform-specific sandboxing mechanisms.

What Sandbox Restricts

• File access is limited to the project directory and system paths (e.g., /usr, /tmp).
• Network access can be restricted or fully blocked.
• Process creation is monitored and can be limited.
• Access to sensitive system paths (e.g., ~/.ssh, ~/.aws) is blocked.

Sandbox mode is controlled by the tool permission configuration. When sandbox is enabled, commands that try to access restricted resources will fail with a permission error rather than silently succeeding.

PTY Terminal

The PTY (pseudo-terminal) system provides a full terminal emulator for interactive command execution. Unlike the basic bash tool, the PTY terminal supports interactive programs, real-time output, and terminal control sequences.

When PTY Is Used

• Commands that require interactive input (e.g., prompts, confirmations).
• Long-running processes that produce streaming output (e.g., dev servers, watch mode).
• Programs that use terminal colors, cursor movement, or other control sequences.
• Commands that need a real TTY to function correctly (e.g., some CLI tools that detect terminal capabilities).

When the agent runs a command through PTY, you see a terminal card in the chat timeline that shows the real-time output. You can interact with the terminal directly if the running process requires input.

Git Secret Scanner

The git secret scanner automatically detects leaked secrets, API keys, tokens, and credentials in staged git changes. It runs as a pre-commit check to prevent accidental exposure of sensitive data.

What It Detects

• API keys and tokens (AWS, Google Cloud, Azure, Stripe, etc.).
• Private keys (RSA, EC, SSH).
• Database connection strings with embedded passwords.
• JWT tokens and session secrets.
• OAuth client secrets.
• Generic high-entropy strings that look like secrets.

When the scanner detects a potential secret, it blocks the commit and reports the finding to the agent. The agent will then help you remove the secret from the staged changes and suggest using environment variables or a secrets manager instead.

Common Use Cases

Running Tests

# Run all tests
bash command="npm test"

# Run a specific test file
bash command="npx vitest run src/utils/format.test.ts"

# Run tests with coverage
bash command="npm run test:coverage" timeout=300000

Package Management

# Install dependencies
bash command="npm install"

# Add a new package
bash command="npm install @tanstack/react-query"

# Check for outdated packages
bash command="npm outdated"

Git Operations

# Check status and recent history
bash command="git status && git log --oneline -10"

# Create a branch and commit
bash command="git checkout -b feature/add-auth && git add -A && git commit -m 'Add OAuth2 authentication'"

# View a diff
bash command="git diff HEAD~1"

Build and Compile

# TypeScript compilation
bash command="npx tsc --noEmit" description="Type check the project"

# Production build
bash command="npm run build" timeout=300000 description="Build for production"

Safety Considerations

• The bash tool defaults to 'ask' permission. You approve each command before it runs.
• Destructive commands (rm -rf, git reset --hard) are flagged in the permission card.
• The agent avoids running commands with side effects unless specifically asked.
• Network-accessing commands can be blocked by sandbox mode.
• The agent never runs commands as root or with sudo unless explicitly instructed.