Bash — запуск команд в терминале
📖 Теория
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"
})
📝 Домашнее задание
- Базовые команды: Выполните 5 базовых shell команд (ls, pwd, whoami, date, echo) через Bash инструмент.
- Timeout: Создайте команду которая timeout'ится через 5 секунд. Затем увеличьте timeout до 15 секунд.
- Background mode: Запустите npm test в фоновом режиме. Продолжайте работать с Claude пока тесты выполняются.
- Parallel tasks: Запустите 3 задачи параллельно в background mode: lint, test, build. Дождитесь завершения всех.
- Error handling: Реализуйте bash скрипт с retry логикой (3 попытки с 5-сек задержкой).
- Safe execution: Используйте BashExecutor класс для выполнения команд с validation опасных паттернов.
- 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 — запуск команд в терминале» — наставник ответит, опираясь на его содержание. Он помогает понять, но не делает домашку за вас.