1. Hooks란 무엇인가?

1. What are Hooks?

Orbitron Hooks는 AI 도구 실행 전후에 자동으로 커스텀 스크립트를 실행할 수 있는 강력한 자동화 시스템입니다. Git의 hooks와 유사한 개념으로, AI와 함께 작업하는 워크플로우를 자동화하고 제어할 수 있습니다.

Orbitron Hooks is a powerful automation system that allows you to automatically execute custom scripts before and after AI tool execution. Similar to Git hooks, it enables you to automate and control your AI-assisted workflows.

💡 왜 Hooks가 필요한가요?
"AI에게 파일을 수정하라고 했는데, 포맷이 깨졌어요."
"Bash 명령어를 실행하기 전에 안전 검사를 하고 싶어요."
"도구 실행이 완료되면 팀에게 자동으로 알림을 보내고 싶어요."

이 모든 것을 Hooks로 해결할 수 있습니다!

💡 Why do you need Hooks?
"AI modified a file but the formatting broke."
"I want to run safety checks before executing Bash commands."
"I want to automatically notify my team when tool execution completes."

All of these can be solved with Hooks!

2. 핵심 개념

2. Core Concepts

2.1 Hook 이벤트 타입

2.1 Hook Event Types

2.2 Matcher 패턴

2.2 Matcher Patterns

Matcher는 어떤 도구에 hook을 적용할지 결정합니다:

Matcher determines which tools the hook applies to:

• * - 모든 도구에 적용
• Bash - Bash 도구에만 적용
• Write - Write 도구에만 적용
• Edit - Edit 도구에만 적용
• 기타 모든 도구 이름 사용 가능

• * - Apply to all tools
• Bash - Apply only to Bash tool
• Write - Apply only to Write tool
• Edit - Apply only to Edit tool
• Any other tool name can be used

2.3 주요 옵션

2.3 Key Options

3. Hook 설정 방법

3. Setting Up Hooks

3.1 TUI에서 Hook 추가

3.1 Adding Hooks in TUI

1. Orbitron 실행 후 /hooks 명령어로 Hooks 관리 화면 진입
2. a 키를 눌러 "Add Hook" 대화상자 열기
3. 필드 입력:
   • Event: preToolUse 또는 postMessageUse
   • Matcher: 도구 이름 (예: Bash, *)
   • Command: 실행할 스크립트 경로
   • Args: 명령어 인자 (선택)
   • Description: Hook 설명 (선택)
4. 옵션 체크박스 설정 (Space로 토글):
   • ☑ Blocking
   • ☑ Enabled
   • ☑ InterpretOutput
   • ☑ UseShell
5. Enter로 저장

1. Launch Orbitron and use /hooks command to enter Hooks management
2. Press a to open "Add Hook" dialog
3. Fill in fields:
   • Event: preToolUse or postMessageUse
   • Matcher: Tool name (e.g., Bash, *)
   • Command: Script path to execute
   • Args: Command arguments (optional)
   • Description: Hook description (optional)
4. Set option checkboxes (toggle with Space):
   • ☑ Blocking
   • ☑ Enabled
   • ☑ InterpretOutput
   • ☑ UseShell
5. Save with Enter

3.2 직접 설정 파일 편집

3.2 Manual Configuration File Editing

Hook 설정 파일을 직접 편집할 수 있습니다. 설정 파일 위치는 Orbitron 실행 위치에 따라 다릅니다:

You can directly edit the hook configuration file. The file location depends on where Orbitron is executed:

• 홈 디렉토리에서 실행: ~/.orbitron/hooks.json
• 프로젝트 디렉토리에서 실행: <project>/.orbitron/hooks.json

• Executed from home directory: ~/.orbitron/hooks.json
• Executed from project directory: <project>/.orbitron/hooks.json

{
  "preToolUse": [
    {
      "matcher": "bash",
      "hooks": [
        {
          "command": "./scripts/check-git-status.sh",
          "blocking": true,
          "enabled": true,
          "interpretOutput": false,
          "useShell": false
        }
      ]
    }
  ],
  "postMessageUse": [
    {
      "matcher": "*",
      "hooks": [
        {
          "command": "./scripts/slack-notify.sh",
          "blocking": false,
          "enabled": true,
          "interpretOutput": false,
          "useShell": false
        }
      ]
    }
  ]
}

3.3 스크립트 실행 권한 설정

3.3 Setting Script Execution Permissions

모든 hook 스크립트에 실행 권한을 부여해야 합니다:

All hook scripts must have execute permissions:

chmod +x your-hook-script.sh

4. 실전 예시 8가지

4. 8 Practical Examples

아래 코드 블록에서 스크립트를 복사하여 바로 사용할 수 있습니다. 필요에 맞게 수정하여 사용하세요.

You can copy the scripts from the code blocks below and use them directly. Modify them to fit your needs.

#!/bin/bash
# check-git-status.sh

echo "=== Checking Git Status ==="
echo "Tool: $ORBITRON_TOOL_NAME"

if ! git rev-parse --git-dir > /dev/null 2>&1; then
    echo "⚠️  Not a Git repository."
    exit 0
fi

if ! git diff-index --quiet HEAD -- 2>/dev/null; then
    echo "❌ Uncommitted changes detected!"
    git status --short
    echo "💡 Please commit your changes before proceeding."
    exit 1  # Block tool execution if Blocking=true
fi

echo "✅ Git working directory is clean."
exit 0

#!/bin/bash
# log-bash.sh

LOG_FILE=".orbitron/bash-commands.log"
mkdir -p "$(dirname "$LOG_FILE")"

if [ "$ORBITRON_TOOL_NAME" = "bash" ]; then
    echo "=== Bash Command Execution Log ==="

    COMMAND=$(echo "$ORBITRON_TOOL_INPUT" | grep -o '"command":"[^"]*"' | cut -d'"' -f4)

    if [ -n "$COMMAND" ]; then
        {
            echo "Time: $(date '+%Y-%m-%d %H:%M:%S')"
            echo "Session: $ORBITRON_SESSION_ID"
            echo "Command: $COMMAND"
            echo ""
        } >> "$LOG_FILE"

        echo "✅ Log saved: $LOG_FILE"
    fi
fi

exit 0  # Always success (Non-blocking)

#!/bin/bash
# validate-input.sh

echo "=== Tool Input Validation ==="

if [ "$ORBITRON_TOOL_NAME" != "bash" ]; then
    exit 0
fi

COMMAND=$(echo "$ORBITRON_TOOL_INPUT" | grep -o '"command":"[^"]*"' | sed 's/"command":"\([^"]*\)"/\1/')

DANGEROUS_PATTERNS=(
    "rm -rf /"
    "mkfs"
    "dd if="
    "> /dev/sda"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
    if echo "$COMMAND" | grep -q "$pattern"; then
        echo "❌ Dangerous command pattern detected!"
        echo "   Pattern: $pattern"
        exit 1  # Block tool execution
    fi
done

echo "✅ Validation passed"
exit 0

#!/bin/bash
# Environment variable usage example

echo "Tool name: $ORBITRON_TOOL_NAME"
echo "Session ID: $ORBITRON_SESSION_ID"

# JSON parsing example (for bash tool)
if [ "$ORBITRON_TOOL_NAME" = "bash" ]; then
    COMMAND=$(echo "$ORBITRON_TOOL_INPUT" | grep -o '"command":"[^"]*"' | cut -d'"' -f4)
    echo "Command to execute: $COMMAND"
fi

# For write tool
if [ "$ORBITRON_TOOL_NAME" = "write" ]; then
    FILE_PATH=$(echo "$ORBITRON_TOOL_INPUT" | grep -o '"file_path":"[^"]*"' | cut -d'"' -f4)
    echo "File to write: $FILE_PATH"
fi

#!/bin/bash
# run-tests.sh

if [ -f "go.mod" ]; then
    echo "Running Go tests..."

    TEST_OUTPUT=$(go test ./... 2>&1)
    TEST_EXIT_CODE=$?

    # Output in JSON format for easy AI parsing
    cat <<EOF
{
  "test_framework": "go test",
  "exit_code": $TEST_EXIT_CODE,
  "status": "$([ $TEST_EXIT_CODE -eq 0 ] && echo "PASS" || echo "FAIL")",
  "timestamp": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
  "summary": {
    "total_packages": $(echo "$TEST_OUTPUT" | grep -c "^ok\|^FAIL" || echo 0),
    "passed": $(echo "$TEST_OUTPUT" | grep -c "^ok" || echo 0),
    "failed": $(echo "$TEST_OUTPUT" | grep -c "^FAIL" || echo 0)
  }
}
EOF
fi

exit 0

#!/bin/bash
# env-check.sh  [required|optional]

ENV_VAR_NAME=$1
REQUIREMENT=${2:-"optional"}

if [ -z "$ENV_VAR_NAME" ]; then
    echo "❌ Usage: env-check.sh  [required|optional]"
    exit 1
fi

ENV_VAR_VALUE=$(printenv "$ENV_VAR_NAME")

if [ -z "$ENV_VAR_VALUE" ]; then
    if [ "$REQUIREMENT" = "required" ]; then
        echo "❌ Required environment variable '$ENV_VAR_NAME' is not set!"
        exit 1  # Blocking
    else
        echo "⚠️  Optional environment variable '$ENV_VAR_NAME' is not set."
    fi
else
    echo "✅ $ENV_VAR_NAME = ${ENV_VAR_VALUE:0:4}****"
fi

exit 0

#!/bin/bash
# format-code.sh - Auto-format based on file extension

FILE_PATH=$(echo "$ORBITRON_TOOL_INPUT" | grep -o '"file_path":"[^"]*"' | cut -d'"' -f4)

case "$FILE_PATH" in
    *.go)
        # Using pipe: save gofmt results to log file
        gofmt -w "$FILE_PATH" 2>&1 | tee /tmp/format.log
        echo "✅ Go code formatting complete"
        ;;
    *.js|*.ts)
        # Using pipe chain
        prettier --write "$FILE_PATH" 2>&1 | grep -v "Checking" | tee -a /tmp/format.log
        echo "✅ JavaScript/TypeScript formatting complete"
        ;;
    *.py)
        black "$FILE_PATH" 2>&1 | grep -E "(reformatted|unchanged)" | tee -a /tmp/format.log
        echo "✅ Python formatting complete"
        ;;
esac

# Output log summary (using pipe)
tail -5 /tmp/format.log | sed 's/^/  /'

exit 0

#!/bin/bash
# slack-notify.sh

SLACK_WEBHOOK_URL="${SLACK_WEBHOOK_URL:-}"

if [ -z "$SLACK_WEBHOOK_URL" ]; then
    echo "⚠️  SLACK_WEBHOOK_URL environment variable is not set."
    exit 0
fi

TOOL_NAME="$ORBITRON_TOOL_NAME"
RESULT_SUMMARY=$(echo "$ORBITRON_TOOL_RESULT" | head -c 100)

MESSAGE=$(cat <<EOF
{
  "text": "Orbitron Tool Execution Complete",
  "blocks": [
    {
      "type": "header",
      "text": {"type": "plain_text", "text": "🤖 Orbitron Tool Execution Complete"}
    },
    {
      "type": "section",
      "fields": [
        {"type": "mrkdwn", "text": "*Tool:*\n\`$TOOL_NAME\`"},
        {"type": "mrkdwn", "text": "*Time:*\n$(date '+%H:%M:%S')"}
      ]
    }
  ]
}
EOF
)

HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -X POST -H "Content-Type: application/json" \
  -d "$MESSAGE" "$SLACK_WEBHOOK_URL")

if [ "$HTTP_STATUS" = "200" ]; then
    echo "✅ Slack notification sent successfully"
else
    echo "❌ Slack notification failed (HTTP $HTTP_STATUS)"
fi

exit 0

export SLACK_WEBHOOK_URL='https://hooks.slack.com/services/YOUR/WEBHOOK/URL'

5. 환경 변수 활용

5. Using Environment Variables

모든 hook 스크립트는 Orbitron이 자동으로 설정하는 환경 변수를 사용할 수 있습니다. 이를 통해 실행 컨텍스트를 파악하고 동적으로 동작을 변경할 수 있습니다.

All hook scripts can use environment variables automatically set by Orbitron. This allows you to understand execution context and dynamically change behavior.

5.1 환경 변수 레퍼런스

5.1 Environment Variables Reference

5.2 환경 변수 사용 예시

5.2 Environment Variable Usage Examples

도구 이름으로 분기 처리

Branching by Tool Name

#!/bin/bash

case "$ORBITRON_TOOL_NAME" in
    "bash")
        echo "Bash command will be executed."
        ;;
    "write"|"edit")
        echo "File write/edit will be executed."
        ;;
    *)
        echo "Other tool: $ORBITRON_TOOL_NAME"
        ;;
esac

JSON 파라미터 파싱

Parsing JSON Parameters

#!/bin/bash

# Extract command from bash tool
if [ "$ORBITRON_TOOL_NAME" = "bash" ]; then
    COMMAND=$(echo "$ORBITRON_TOOL_INPUT" | grep -o '"command":"[^"]*"' | cut -d'"' -f4)
    echo "Command to execute: $COMMAND"
fi

# Extract file_path from write tool
if [ "$ORBITRON_TOOL_NAME" = "write" ]; then
    FILE_PATH=$(echo "$ORBITRON_TOOL_INPUT" | grep -o '"file_path":"[^"]*"' | cut -d'"' -f4)
    echo "File to write: $FILE_PATH"
fi

# Parsing with jq (more accurate)
if command -v jq &> /dev/null; then
    COMMAND=$(echo "$ORBITRON_TOOL_INPUT" | jq -r '.command // empty')
    FILE_PATH=$(echo "$ORBITRON_TOOL_INPUT" | jq -r '.file_path // empty')
fi

세션/메시지 ID로 로깅

Logging with Session/Message IDs

#!/bin/bash

LOG_FILE=".orbitron/hook.log"

{
    echo "==================================="
    echo "Timestamp: $(date -u +"%Y-%m-%dT%H:%M:%SZ")"
    echo "Session: $ORBITRON_SESSION_ID"
    echo "Message: $ORBITRON_MESSAGE_ID"
    echo "Tool: $ORBITRON_TOOL_NAME"
    echo "==================================="
} >> "$LOG_FILE"

6. Hook 옵션 상세 가이드

6. Detailed Hook Options Guide

6.1 Blocking

6.1 Blocking

Blocking=true로 설정하면, hook 스크립트가 0이 아닌 종료 코드로 종료했을 때 도구 실행을 차단합니다. preToolUse 이벤트에서만 의미가 있습니다.

When set to Blocking=true, tool execution is blocked if the hook script exits with a non-zero exit code. Only meaningful for preToolUse events.

❌ PreToolUse hook blocked execution: {hook 출력 내용}

또는

❌ PreToolUse hook blocked tool execution

❌ PreToolUse hook blocked execution: {hook output}

or

❌ PreToolUse hook blocked tool execution

❌ PreToolUse hook blocked execution: ❌ Uncommitted 변경사항이 있습니다!

변경된 파일 목록:
 M internal/config/config.go
 M internal/llm/agent/agent.go

💡 변경사항을 커밋한 후 다시 시도하세요.

❌ PreToolUse hook blocked execution: ❌ Uncommitted changes detected!

Changed files:
 M internal/config/config.go
 M internal/llm/agent/agent.go

💡 Please commit your changes before proceeding.

커밋되지 않은 변경사항이 있습니다.
다음 파일들이 수정되었습니다:
- internal/config/config.go
- internal/llm/agent/agent.go

변경사항을 커밋한 후 다시 시도해주세요.

There are uncommitted changes.
The following files have been modified:
- internal/config/config.go
- internal/llm/agent/agent.go

Please commit your changes before trying again.

6.2 InterpretOutput

6.2 InterpretOutput

InterpretOutput=true로 설정하면, hook 출력을 AI가 읽고 해석하여 사용자에게 요약된 형태로 제공합니다. 복잡한 로그나 테스트 결과를 분석할 때 유용합니다.

When set to InterpretOutput=true, AI reads and interprets hook output and provides a summarized version to the user. Useful for analyzing complex logs or test results.

6.3 Args

6.3 Args

Args 필드에 공백으로 구분된 인자를 입력하면, 스크립트 실행 시 $1, $2 등으로 접근할 수 있습니다.

Enter space-separated arguments in the Args field, and they can be accessed as $1, $2, etc. during script execution.

# Hook configuration
Command: ./check-env.sh
Args: API_KEY required

# In check-env.sh script
ENV_NAME=$1      # "API_KEY"
REQUIREMENT=$2   # "required"

6.4 UseShell

6.4 UseShell

UseShell=true로 설정하면 sh -c "command args..." 형태로 실행되어 셸 기능(파이프, 리다이렉션 등)을 사용할 수 있습니다.

When set to UseShell=true, executes as sh -c "command args..." enabling shell features (pipes, redirections, etc.).

UseShell 사용 예시

UseShell Usage Examples

# ✅ Basic usage - No Args (shell execution for backward compatibility)
Command: ./scripts/check-git-status.sh
UseShell: false  # Automatically uses sh -c

# ✅ Relative path with Args (direct execution mode)
Command: ./scripts/env-check.sh
Args: API_KEY required
UseShell: false  # Relative path works based on working directory ✅

# ✅ Using pipe with Args - UseShell required!
Command: ./scripts/env-check.sh
Args: API_KEY required | grep "API"
UseShell: true  # UseShell is required to include pipes in Args

# ✅ Using pipes/redirections - UseShell required
Command: find . -name "*.log" | xargs rm
UseShell: true

# ✅ Using glob patterns - UseShell required
Command: ls *.go && go fmt
UseShell: true

# ✅ Direct execution (fastest) - Using Args
Command: ./scripts/env-check.sh
Args: API_KEY required
UseShell: false  # Direct execution is faster when shell features are unnecessary

7. 실무 워크플로우

7. Real-World Workflows

7.1 완전 자동화된 CI/CD 워크플로우

7.1 Fully Automated CI/CD Workflow

AI가 코드를 수정할 때 자동으로 검증, 테스트, 포맷팅을 수행하는 워크플로우:

Workflow that automatically validates, tests, and formats code when AI modifies it:

7.2 보안 중심 워크플로우

7.2 Security-Focused Workflow

모든 Bash 명령어를 검증하고 로깅하는 보안 강화 워크플로우:

Security-enhanced workflow that validates and logs all Bash commands:

1. preToolUse - Bash 명령어 로깅 (Non-blocking)
2. preToolUse - 위험 패턴 검증 (Blocking)
3. preToolUse - 민감 파일 접근 검사 (Blocking)
4. postMessageUse - 실행 결과 감사 로그 저장
5. postMessageUse - 보안 팀에 알림 (특정 조건)

1. preToolUse - Log Bash commands (Non-blocking)
2. preToolUse - Validate dangerous patterns (Blocking)
3. preToolUse - Check sensitive file access (Blocking)
4. postMessageUse - Save execution result audit log
5. postMessageUse - Notify security team (under certain conditions)

7.3 품질 보증 워크플로우

7.3 Quality Assurance Workflow

코드 품질을 자동으로 검증하고 개선하는 워크플로우:

Workflow that automatically validates and improves code quality:

1. preToolUse (Write/Edit) - 린팅 및 정적 분석
2. postMessageUse (Write/Edit) - 코드 포맷팅 자동 적용
3. postMessageUse (Write/Edit) - 단위 테스트 실행 + AI 분석
4. postMessageUse (Write/Edit) - 커버리지 리포트 생성
5. postMessageUse - 코드 리뷰 체크리스트 생성 (AI 해석)

1. preToolUse (Write/Edit) - Linting and static analysis
2. postMessageUse (Write/Edit) - Auto-apply code formatting
3. postMessageUse (Write/Edit) - Run unit tests + AI analysis
4. postMessageUse (Write/Edit) - Generate coverage report
5. postMessageUse - Generate code review checklist (AI interpretation)

8. 문제 해결

8. Troubleshooting

8.1 Hook이 실행되지 않아요

8.1 Hook Not Executing

8.2 Hook이 도구 실행을 차단하지 않아요

8.2 Hook Not Blocking Tool Execution

8.3 환경 변수가 비어 있어요

8.3 Environment Variables Are Empty

# Debugging script
#!/bin/bash

echo "=== Environment Variable Debugging ==="
echo "TOOL_NAME: ${ORBITRON_TOOL_NAME:-'(empty)'}"
echo "TOOL_INPUT: ${ORBITRON_TOOL_INPUT:-'(empty)'}"
echo "SESSION_ID: ${ORBITRON_SESSION_ID:-'(empty)'}"
echo "MESSAGE_ID: ${ORBITRON_MESSAGE_ID:-'(empty)'}"
echo "TOOL_RESULT: ${ORBITRON_TOOL_RESULT:-'(empty)'}"

exit 0

참고: ORBITRON_TOOL_RESULT는 postMessageUse 이벤트에서만 사용할 수 있습니다.

Note: ORBITRON_TOOL_RESULT is only available in postMessageUse events.

8.4 UseShell을 사용했는데 파이프가 작동하지 않아요

8.4 Pipes Not Working Even with UseShell

# ✅ Correct usage
Command: find . -name "*.log" | xargs rm
Args: (empty)
UseShell: true

# ❌ Incorrect usage
Command: find
Args: . -name "*.log" | xargs rm
UseShell: true

8.5 Hook 테스트 방법

8.5 How to Test Hooks

Orbitron TUI에서 Hook을 안전하게 테스트할 수 있습니다:

You can safely test hooks in Orbitron TUI:

1. /hooks 명령어로 Hooks 관리 화면 진입
2. 방향키로 테스트할 Hook 선택
3. t 키 입력 (Test)
4. 테스트 결과 화면에서 출력, 종료 코드, 실행 시간 확인

1. Enter Hooks management with /hooks command
2. Select hook to test with arrow keys
3. Press t key (Test)
4. Check output, exit code, execution time on test result screen

테스트 모드에서는 샘플 데이터로 Hook을 실행하므로 실제 도구는 실행되지 않습니다.

In test mode, hooks run with sample data so actual tools are not executed.

8.6 MCP 도구에 Hook이 적용되지 않아요

8.6 Hooks Not Applied to MCP Tools

해결 방법

Solution

// ❌ Incorrect configuration - MCP tools excluded
{
  "hooks": {
    "preToolUse": [
      {
        "matcher": "bash",  // MCP tools won't match!
        "hooks": [
          {
            "command": "./validate-input.sh",
            "blocking": true
          }
        ]
      }
    ]
  }
}

// ✅ Correct configuration - MCP tools included
{
  "hooks": {
    "preToolUse": [
      {
        "matcher": "*",  // All tools (including MCP)
        "hooks": [
          {
            "command": "./validate-input.sh",
            "blocking": true
          }
        ]
      }
    ]
  }
}

언제 *를 사용해야 하나요?

When Should You Use *?

• 보안 검증: 위험한 명령어 차단, 입력 검증 등은 모든 도구에 적용
• 로깅/모니터링: 모든 도구 실행을 추적하려면 * 사용
• 환경 체크: 필수 환경 변수나 파일 존재 여부 확인
• Bash 전용 기능: Bash 명령어에만 특화된 검증 (예: 특정 명령어만 로깅)
• 도구별 최적화: 각 도구 타입에 맞는 별도 hook 설정

• Security validation: Apply dangerous command blocking, input validation to all tools
• Logging/monitoring: Use * to track all tool executions
• Environment checks: Verify required environment variables or file existence
• Bash-specific features: Validation specific to Bash commands (e.g., logging specific commands only)
• Tool-specific optimization: Configure separate hooks for each tool type