AICodingLab
Claude Code лайфхаки · Урок 3 из 35

Bash — запуск команд в терминале

🎯 Цель урока: Научиться запускать команды в терминале с помощью Bash инструмента Claude Code, понимать таймауты, работу в фоновом режиме (run_in_background) и ограничения, связанные с sandbox режимом.

📖 Теория

Bash инструмент в Claude Code — это мощный механизм для выполнения shell команд непосредственно из сессии Claude. Он предоставляет интерфейс для взаимодействия с операционной системой, позволяя запускать команды, писать скрипты и автоматизировать задачи. В отличие от обычного терминала, Bash в Claude Code имеет специфические особенности: таймауты, фоновый режим и sandbox изоляцию.

Архитектура Bash инструмента

Claude Agent
    ↓
Bash Tool Call
    ↓
[Permission Check] → User approval (если требуется)
    ↓
[Sandbox Mode Check] → Изоляция (по умолчанию)
    ↓
Shell Execution (bash -c "command")
    ↓
[Timeout Monitor] → Kill после max_time
    ↓
Output → Claude context

Основные параметры Bash инструмента

  • command: Shell команда для выполнения (string)
  • timeout: Максимальное время выполнения в миллисекундах (default: 120000ms = 2min, max: 600000ms = 10min)
  • run_in_background: Запуск в фоновом режиме (boolean). Команда продолжает работу между turns.
  • dangerouslyDisableSandbox: Отключение sandbox изоляции (требует явного user approval)
  • description: Человекочитаемое описание команды (показывается пользователю)

Sandbox режим

По умолчанию все Bash команды выполняются в sandbox окружении для безопасности:

Aspect Sandboxed (default) Non-sandboxed
File Access Ограничен project directory Полный доступ к filesystem
Network Ограничен (whitelist) Полный доступ
Process Spawning Контролируется Без ограничений
System Calls Фильтруются Прямой доступ
User Approval Автоматически для безопасных команд Требуется явное подтверждение

Фоновый режим (run_in_background)

Команды в фоновом режиме:

  • Продолжают работу после завершения turn
  • Не блокируют следующие запросы Claude
  • Автоматически re-invoke Claude при завершении
  • Идеальны для: long-running builds, tests, monitoring, deploys
  • НЕ подходят для: interactive commands, quick operations

🛠 Практика

Базовые операции

Шаг 1. Простая команда:

Bash({
  command: "echo 'Hello, World!'",
  description: "Print greeting message"
})

# Вывод: Hello, World!

Шаг 2. Команда с таймаутом:

Bash({
  command: "sleep 5 && echo 'Done!'",
  timeout: 10000,  // 10 секунд
  description: "Wait 5 seconds and print"
})

# Успешно завершится через 5 секунд

Bash({
  command: "sleep 20",
  timeout: 5000,  // 5 секунд
  description: "This will timeout"
})

# Ошибка: Command timed out after 5000ms

Шаг 3. Фоновый режим:

Bash({
  command: "npm test",
  run_in_background: true,
  description: "Run test suite in background"
})

# Claude продолжает работу не дожидаясь завершения
# Когда тесты завершатся - Claude получит notification

Продвинутые сценарии

Сценарий 1: Long-running build

# Плохо: блокирует сессию на 10 минут
Bash({
  command: "npm run build",
  timeout: 600000  // 10 минут
})

# Хорошо: работает в фоне
Bash({
  command: "npm run build > build.log 2>&1",
  run_in_background: true,
  description: "Build application in background"
})

# Claude может продолжать отвечать на вопросы
# Когда build завершится - Claude сообщит результат

Сценарий 2: Monitoring с auto-restart

# Мониторинг логов в фоне
Bash({
  command: `
    tail -f /var/log/app.log | while read line; do
      if echo "$line" | grep -q "ERROR"; then
        echo "ERROR detected: $line"
      fi
    done
  `,
  run_in_background: true,
  description: "Monitor logs for errors"
})

# Мониторинг продолжается пока не будет остановлен
# При ERROR - Claude получает notification

Сценарий 3: Parallel execution

# Запустить несколько задач параллельно
# Все в фоне, не блокируют друг друга

Bash({
  command: "npm run lint > lint.log 2>&1",
  run_in_background: true,
  description: "Run linter"
})

Bash({
  command: "npm run test:unit > unit.log 2>&1",
  run_in_background: true,
  description: "Run unit tests"
})

Bash({
  command: "npm run test:integration > integration.log 2>&1",
  run_in_background: true,
  description: "Run integration tests"
})

# Все три задачи работают одновременно
# Claude получит 3 notification когда каждая завершится

Сценарий 4: Conditional execution

# Выполнить команду только если условие выполнено
Bash({
  command: `
    if [ -f package-lock.json ]; then
      npm ci
    elif [ -f yarn.lock ]; then
      yarn install --frozen-lockfile
    else
      echo "No lockfile found"
      exit 1
    fi
  `,
  description: "Install dependencies using lockfile"
})

# Автоматически выбирает правильный package manager

Сценарий 5: Error handling и retry

# Retry логика в shell
Bash({
  command: `
    MAX_RETRIES=3
    RETRY_COUNT=0

    until npm run build || [ $RETRY_COUNT -eq $MAX_RETRIES ]; do
      RETRY_COUNT=$((RETRY_COUNT+1))
      echo "Build failed, retry $RETRY_COUNT/$MAX_RETRIES"
      sleep 5
    done

    if [ $RETRY_COUNT -eq $MAX_RETRIES ]; then
      echo "Build failed after $MAX_RETRIES retries"
      exit 1
    fi
  `,
  timeout: 300000,  // 5 минут
  description: "Build with retry logic"
})

Production-Ready Bash Wrapper

#!/usr/bin/env python3
"""
Claude Bash Wrapper - безопасное выполнение команд через Claude Code
"""
import subprocess
import time
import json
from pathlib import Path
from typing import Optional, Dict, List

class BashExecutor:
    def __init__(self, project_root: str = "."):
        self.project_root = Path(project_root).resolve()
        self.log_file = self.project_root / ".claude" / "bash-history.log"
        self.log_file.parent.mkdir(parents=True, exist_ok=True)

    def execute(
        self,
        command: str,
        description: str = "",
        timeout: int = 120000,
        run_in_background: bool = False,
        working_dir: Optional[str] = None,
        env: Optional[Dict[str, str]] = None,
        check: bool = True
    ) -> Dict:
        """
        Выполнить Bash команду с логированием и error handling
        """
        start_time = time.time()

        # Логирование
        log_entry = {
            "timestamp": start_time,
            "command": command,
            "description": description,
            "timeout": timeout,
            "background": run_in_background
        }

        try:
            # Подготовка окружения
            exec_env = os.environ.copy()
            if env:
                exec_env.update(env)

            # Рабочая директория
            cwd = working_dir or str(self.project_root)

            if run_in_background:
                # Фоновое выполнение
                process = subprocess.Popen(
                    command,
                    shell=True,
                    cwd=cwd,
                    env=exec_env,
                    stdout=subprocess.PIPE,
                    stderr=subprocess.PIPE,
                    text=True
                )

                result = {
                    "success": True,
                    "pid": process.pid,
                    "message": f"Started in background (PID: {process.pid})"
                }
            else:
                # Синхронное выполнение
                process = subprocess.run(
                    command,
                    shell=True,
                    cwd=cwd,
                    env=exec_env,
                    capture_output=True,
                    text=True,
                    timeout=timeout / 1000,  # Convert ms to seconds
                    check=check
                )

                result = {
                    "success": process.returncode == 0,
                    "returncode": process.returncode,
                    "stdout": process.stdout,
                    "stderr": process.stderr,
                    "duration": time.time() - start_time
                }

        except subprocess.TimeoutExpired as e:
            result = {
                "success": False,
                "error": "Timeout",
                "message": f"Command timed out after {timeout}ms",
                "stdout": e.stdout,
                "stderr": e.stderr
            }

        except subprocess.CalledProcessError as e:
            result = {
                "success": False,
                "error": "CommandFailed",
                "returncode": e.returncode,
                "stdout": e.stdout,
                "stderr": e.stderr
            }

        except Exception as e:
            result = {
                "success": False,
                "error": type(e).__name__,
                "message": str(e)
            }

        # Логирование результата
        log_entry["result"] = result
        self._log(log_entry)

        return result

    def execute_safe(self, command: str, **kwargs) -> Dict:
        """
        Безопасное выполнение с validation
        """
        # Проверка на опасные паттерны
        dangerous_patterns = [
            r"rm\s+-rf\s+/",
            r"dd\s+if=",
            r"mkfs\.",
            r":\(\)\{.*:&",  # fork bomb
            r">\s*/dev/sda"
        ]

        import re
        for pattern in dangerous_patterns:
            if re.search(pattern, command):
                return {
                    "success": False,
                    "error": "DangerousCommand",
                    "message": f"Command blocked: matches dangerous pattern {pattern}"
                }

        return self.execute(command, **kwargs)

    def execute_with_retry(
        self,
        command: str,
        max_retries: int = 3,
        retry_delay: int = 5,
        **kwargs
    ) -> Dict:
        """
        Выполнить с автоматическими retry
        """
        for attempt in range(max_retries):
            result = self.execute(command, **kwargs)

            if result["success"]:
                return result

            if attempt < max_retries - 1:
                print(f"Attempt {attempt + 1} failed, retrying in {retry_delay}s...")
                time.sleep(retry_delay)

        return result

    def _log(self, entry: Dict):
        """Логировать выполнение"""
        with open(self.log_file, 'a') as f:
            f.write(json.dumps(entry) + '\n')

    def get_history(self, limit: int = 10) -> List[Dict]:
        """Получить историю команд"""
        if not self.log_file.exists():
            return []

        history = []
        with open(self.log_file) as f:
            for line in f:
                history.append(json.loads(line))

        return history[-limit:]

# Использование
if __name__ == "__main__":
    executor = BashExecutor()

    # Простая команда
    result = executor.execute("echo 'Hello'", description="Test echo")
    print(result)

    # С retry
    result = executor.execute_with_retry(
        "npm install",
        max_retries=3,
        description="Install dependencies"
    )

    # Безопасное выполнение
    result = executor.execute_safe(
        "rm file.txt",  # Безопасно
        description="Remove file"
    )

    # История
    history = executor.get_history(limit=5)
    for entry in history:
        print(f"{entry['description']}: {entry['result']['success']}")

⚠️ Troubleshooting

Проблема 1: Command timed out

Решение:

# Увеличить timeout (max 600000ms = 10min)
Bash({ command: "...", timeout: 600000 })

# Или использовать background mode
Bash({ command: "...", run_in_background: true })

Проблема 2: Command не запускается в sandbox

Решение:

# Отключить sandbox (требует user approval)
Bash({
  command: "...",
  dangerouslyDisableSandbox: true
})

Проблема 3: Background task не уведомляет

Решение:

# Убедитесь что команда пишет в stdout/stderr
Bash({
  command: "npm test 2>&1",  # Redirect stderr to stdout
  run_in_background: true
})

# Проверить что команда завершается
# Бесконечные loops не отправят notification

Проблема 4: Working directory неправильный

Решение:

# Явно указать working directory
Bash({
  command: "cd /path/to/project && npm test"
})

# Или использовать absolute paths
Bash({
  command: "npm --prefix /path/to/project test"
})

Проблема 5: Environment variables не доступны

Решение:

# Загрузить .env файл
Bash({
  command: "source .env && npm start"
})

# Или передать явно
Bash({
  command: "API_KEY=secret npm start"
})

📝 Домашнее задание

  1. Базовые команды: Выполните 5 базовых shell команд (ls, pwd, whoami, date, echo) через Bash инструмент.
  2. Timeout: Создайте команду которая timeout'ится через 5 секунд. Затем увеличьте timeout до 15 секунд.
  3. Background mode: Запустите npm test в фоновом режиме. Продолжайте работать с Claude пока тесты выполняются.
  4. Parallel tasks: Запустите 3 задачи параллельно в background mode: lint, test, build. Дождитесь завершения всех.
  5. Error handling: Реализуйте bash скрипт с retry логикой (3 попытки с 5-сек задержкой).
  6. Safe execution: Используйте BashExecutor класс для выполнения команд с validation опасных паттернов.
  7. Monitoring: Создайте background мониторинг который следит за log файлом и алертит при ERROR.

🎓 После урока вы умеете

  • Запускать команды через Bash инструмент Claude Code
  • Использовать timeout для ограничения времени выполнения
  • Запускать long-running задачи в фоновом режиме (run_in_background)
  • Понимать разницу между sandbox и non-sandbox режимами
  • Выполнять parallel tasks через background mode
  • Реализовывать retry логику и error handling в bash
  • Создавать production-ready bash wrappers с логированием
  • Диагностировать и решать типичные проблемы с Bash инструментом
  • Безопасно выполнять команды с validation опасных паттернов
  • Мониторить и управлять background processes

🔗 Дополнительные ресурсы

Рекомендуемые курсы

Продолжите обучение по смежным темам

ИИ-наставник по этому уроку

Задайте вопрос по теме урока «Bash — запуск команд в терминале» — наставник ответит, опираясь на его содержание. Он помогает понять, но не делает домашку за вас.

Привет! Я наставник по этому уроку. Спросите что угодно по теме — объясню простыми словами. 🙂
Ответы генерирует ИИ и может ошибаться — сверяйтесь с уроком.
ИИ-консультант
Помогу выбрать курс