terminal-execution

Terminal Execution Skill

Guide for using the execute tool to run shell commands safely and efficiently.

When to Use Terminal

✅ USE when:

• Build/compile code (uv run, npm run build)
• Run tests (pytest, npm run test:unit)
• Check system status (docker ps, systemctl status)
• Install dependencies (pip install, npm install, apt-get)
• Quick file/folder checks (ls, find, grep, cat)
• Git operations (git status, git diff, git log)
• Docker operations (docker compose up, docker build)
• Migration scripts, seed data

❌ DO NOT use when:

• Reading/writing files → use filesystem tools (read_text_file, write_file)
• GitHub API operations → use github tools
• Long interactive sessions → out of scope

Execute Tool Syntax

The execute tool (built-in from ShellRuntime) takes a single parameter:

execute(command="<shell command>")

Key characteristics:

• Runs in the workspace directory (not home dir)
• 90s timeout — process killed if no output for 90s
• Watchdog: warns every 30s if no output
• Output auto-truncated if too long (prevents token overflow)
• Returns exit code at end: process exit code was 0
• Each call is a separate shell session — env vars and cd don't persist
• No shell prefix needed: correct "ls -la", wrong "bash -c ls -la"

Efficient Patterns

Chain Commands

cd repo && npm install && npm test        # Sequential (stops on error)
echo "=== Tests ===" ; pytest ; echo "=== Lint ===" ; ruff check .  # Run all

Check Before Acting

docker info > /dev/null 2>&1 && echo "Docker OK" || echo "Docker NOT running"
lsof -ti:8000 && echo "Port 8000 in use" || echo "Port 8000 available"

Filter Long Output

docker logs container_name 2>&1 | tail -20      # Last 20 lines
grep -r "ERROR" logs/ | head -10                 # Find errors
find . -name "*.py" | wc -l                      # Count files

Build & Test

cd backend && uv run pytest --tb=short -q 2>&1 | tail -20
cd frontend && npm run test:unit 2>&1 | tail -20
docker compose -f docker-compose.yaml build --no-cache 2>&1 | tail -30