> For the complete documentation index, see [llms.txt](https://orbitron.gitbook.io/orbitron-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://orbitron.gitbook.io/orbitron-docs/documentation/ko/user-guide/hooks-guide.md). # Shell 훅 가이드 > Shell 훅(Hooks)은 AI가 도구를 실행하기 전후에 커스텀 명령어를 자동으로 실행할 수 있게 해주는 강력한 자동화 시스템입니다. 이를 통해 자동 테스트, 보안 검증, 로깅, 백업 등 다양한 워크플로우를 구성할 수 있습니다. *** ## 🎯 Shell 훅이란? Shell 훅은 특정 이벤트가 발생할 때 자동으로 실행되는 커스텀 쉘 명령어입니다. Orbitron에서는 다음 두 가지 타이밍에 훅을 실행할 수 있습니다: * **preToolUse**: AI가 도구를 실행하기 직전 * **postMessageUse**: AI가 도구 실행 결과를 포함한 응답을 완료한 직후 이러한 훅을 활용하면 AI의 작업 흐름에 자동화된 검증, 로깅, 알림 등을 추가할 수 있습니다. *** ## ⚡ 주요 기능 ### 🔧 1. 두 가지 훅 이벤트 #### preToolUse (도구 실행 전) * AI가 도구를 실행하기 **직전**에 실행됩니다 * **실행 차단 가능**: 0이 아닌 종료 코드를 반환하면 도구 실행을 차단할 수 있습니다 * 검증, 백업, 사전 조건 확인에 유용합니다 예시 활용: * 코드 변경 전 Git 커밋 상태 확인 * 파일 수정 전 자동 백업 * 특정 조건이 충족되었는지 검증 #### postMessageUse (응답 완료 후) * AI가 도구 실행 결과를 포함한 **전체 응답을 완료한 후** 실행됩니다 * 후처리, 알림, 로깅에 유용합니다 예시 활용: * 코드 변경 후 자동으로 테스트 실행 * 작업 완료 알림 전송 * 변경 사항 로그 기록 *** ### 🎯 2. 유연한 도구 타겟팅 훅을 설정할 때 어떤 도구에 적용할지 선택할 수 있습니다: * **특정 도구**: `bash`, `edit`, `read`, `write` 등 특정 도구에만 적용 * **모든 도구**: `*`를 사용하여 모든 도구에 적용 *** ### 📊 3. 환경 변수를 통한 컨텍스트 제공 훅 명령어는 다음 환경 변수를 통해 실행 컨텍스트 정보를 받을 수 있습니다. #### 환경 변수 레퍼런스 | 변수명 | 설명 | 사용 가능 이벤트 | 예시 값 | | ---------------------- | --------------------- | -------------------------- | ------------------------------ | | `ORBITRON_TOOL_NAME` | 실행되는 도구의 이름 | preToolUse, postMessageUse | `bash`, `edit`, `read` | | `ORBITRON_TOOL_INPUT` | 도구에 전달되는 JSON 형식의 입력값 | preToolUse, postMessageUse | `{"file_path": "src/main.go"}` | | `ORBITRON_SESSION_ID` | 현재 세션 ID | preToolUse, postMessageUse | `sess_abc123` | | `ORBITRON_MESSAGE_ID` | 현재 메시지 ID | preToolUse, postMessageUse | `msg_xyz789` | | `ORBITRON_TOOL_RESULT` | 도구 실행 결과 (JSON) | **postMessageUse만** | `{"success": true}` | #### 환경 변수 활용 예시 **1. 도구 이름으로 분기 처리:** ```bash #!/bin/bash case "$ORBITRON_TOOL_NAME" in bash) echo "Bash 명령어 실행 전 검증..." ;; edit) echo "파일 편집 전 백업..." ;; *) echo "기타 도구: $ORBITRON_TOOL_NAME" ;; esac ``` **2. JSON 입력값 파싱:** ```bash #!/bin/bash # jq를 사용하여 JSON 파싱 FILE_PATH=$(echo "$ORBITRON_TOOL_INPUT" | jq -r '.file_path') COMMAND=$(echo "$ORBITRON_TOOL_INPUT" | jq -r '.command') echo "처리할 파일: $FILE_PATH" echo "실행할 명령: $COMMAND" ``` **3. 도구 결과 분석 (postMessageUse):** ```bash #!/bin/bash # postMessageUse 훅에서만 사용 가능 if [ -n "$ORBITRON_TOOL_RESULT" ]; then SUCCESS=$(echo "$ORBITRON_TOOL_RESULT" | jq -r '.success') if [ "$SUCCESS" = "true" ]; then echo "✅ 도구 실행 성공!" else echo "❌ 도구 실행 실패" fi fi ``` **4. 세션/메시지 ID 활용:** ```bash #!/bin/bash # 로그 파일에 세션 정보와 함께 기록 LOG_FILE=".orbitron-audit.log" TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S') echo "[$TIMESTAMP] Session: $ORBITRON_SESSION_ID" >> "$LOG_FILE" echo " Tool: $ORBITRON_TOOL_NAME" >> "$LOG_FILE" ``` *** ## 🛠️ 훅 관리하기 ### `/hooks` 명령어 터미널에서 `/hooks`를 입력하면 훅 관리 인터페이스가 열립니다. ``` /hooks ``` ### 훅 목록 보기 훅 목록 화면에서는 현재 설정된 모든 훅을 확인할 수 있습니다: * **이름**: 훅의 이름 * **이벤트**: `preToolUse` 또는 `postMessageUse` * **도구**: 훅이 적용되는 도구 (`*`는 모든 도구) * **상태**: 활성화/비활성화 상태 #### 훅 목록 단축키: * `a`: 새 훅 추가 * `e`: 선택한 훅 편집 * `Enter`: 선택한 훅 테스트 * `Space`: 선택한 훅 활성화/비활성화 토글 * `d`: 선택한 훅 삭제 * `ESC`: 훅 관리 창 닫기 *** ### 훅 추가/편집하기 훅을 추가하거나 편집할 때는 다음 정보를 입력합니다: 1. **이름**: 훅을 식별하기 위한 이름 2. **이벤트**: `preToolUse` 또는 `postMessageUse` 3. **도구**: 특정 도구 이름 또는 `*` (모든 도구) 4. **명령어**: 실행할 쉘 명령어 5. **옵션 설정**: * **Enabled**: 훅 활성화 여부 * **Blocking**: 0이 아닌 종료 코드 시 도구 실행 차단 (preToolUse만 해당) * **InterpretOutput**: AI가 출력을 해석하여 사용자에게 요약 제공 * **UseShell**: 셸을 통해 실행 (파이프, 리다이렉션 가능) * **Args**: 명령어에 전달할 인자 (공백으로 구분) #### 훅 추가/편집 단축키: * `↑/↓`: 필드 간 이동 * `Ctrl + T`: 현재 설정으로 훅 테스트 * `Ctrl + S`: 훅 저장 * `ESC`: 취소 *** ### 훅 테스트하기 훅을 저장하기 전에 테스트할 수 있습니다: 1. 훅 추가/편집 화면에서 `Ctrl + T`를 누르거나 2. 훅 목록에서 훅을 선택하고 `Enter`를 누릅니다 테스트 시 샘플 컨텍스트 데이터가 환경 변수로 제공되며, 명령어의 출력과 종료 코드가 표시됩니다. *** ## ⚙️ Hook 옵션 상세 가이드 ### Blocking `Blocking=true`로 설정하면 Hook 스크립트가 0이 아닌 종료 코드로 종료했을 때 도구 실행을 차단합니다. **preToolUse 이벤트에서만 의미가 있습니다.** #### 차단 시 동작 방식 Hook이 도구 실행을 차단하면: 1. **도구 실행 중단**: 해당 도구와 이후 도구들이 모두 실행되지 않음 2. **에러 메시지 표시**: 사용자에게 차단 메시지 표시 3. **대화 종료**: AI가 도구 결과를 받지 못하므로 응답 중단 **사용자에게 표시되는 메시지:** ``` ❌ PreToolUse hook blocked execution: {hook 출력 내용} ``` Hook 스크립트에서 `echo`로 출력한 메시지가 사용자에게 그대로 전달되므로, **왜 차단되었는지, 어떻게 해결해야 하는지** 명확히 설명하세요! #### InterpretOutput과 함께 사용 `Blocking=true`와 `InterpretOutput=true`를 함께 사용하면, AI가 Hook 출력을 해석하여 더 자연스럽고 친절한 메시지로 변환합니다. **예시 (InterpretOutput 없이):** ``` ❌ PreToolUse hook blocked execution: ❌ Uncommitted 변경사항이 있습니다! 변경된 파일 목록: M internal/config/config.go M internal/llm/agent/agent.go 💡 변경사항을 커밋한 후 다시 시도하세요. ``` **예시 (InterpretOutput 사용):** ``` 코드를 수정하기 전에 먼저 커밋되지 않은 변경사항을 처리해야 합니다. 현재 변경된 파일: - internal/config/config.go - internal/llm/agent/agent.go git add와 git commit으로 변경사항을 커밋한 후 다시 시도해주세요. ``` *** ### InterpretOutput `InterpretOutput=true`로 설정하면 Hook 출력을 AI가 읽고 해석하여 사용자에게 요약된 형태로 제공합니다. 복잡한 로그나 테스트 결과를 분석할 때 유용합니다. #### 최적화 팁 * **JSON 형식**으로 출력하면 AI가 더 정확하게 파싱 * 중요한 정보를 `"status"`, `"summary"`, `"errors"` 등의 키로 구조화 * 긴 출력은 요약 섹션을 먼저 출력하고 상세 내용은 나중에 * 에러 메시지는 명확하고 실행 가능한 형태로 작성 **예시:** ```bash # Hook 스크립트에서 JSON 출력 echo '{ "status": "failed", "summary": "3 tests failed", "errors": ["test_login", "test_auth", "test_permissions"], "recommendation": "Check authentication service logs" }' ``` *** ### Args (인자) `Args` 필드에 공백으로 구분된 인자를 입력하면, 스크립트 실행 시 `$1`, `$2` 등으로 접근할 수 있습니다. **예시:** ```bash # Hook 설정 Command: ./check-env.sh Args: API_KEY required # check-env.sh 스크립트 ENV_NAME=$1 # "API_KEY" REQUIREMENT=$2 # "required" if [ -z "${!ENV_NAME}" ]; then echo "❌ $ENV_NAME is $REQUIREMENT but not set" exit 1 fi ``` #### Args 활용 방법 * 여러 상황에 재사용 가능한 범용 스크립트 작성 * 환경별로 다른 파라미터 전달 (dev, staging, prod) * 옵션 플래그 전달 (`--verbose`, `--strict`) * 동일한 스크립트로 다양한 검증 수행 *** ### UseShell `UseShell=true`로 설정하면 `sh -c "command args..."` 형태로 실행되어 셸 기능(파이프, 리다이렉션 등)을 사용할 수 있습니다. **UseShell=false (기본값):** ```bash # 직접 실행: ./script.sh arg1 arg2 Command: ./script.sh Args: arg1 arg2 ``` **UseShell=true:** ```bash # 셸을 통해 실행 가능 Command: echo $ORBITRON_TOOL_NAME | tee -a log.txt ``` #### 언제 UseShell을 사용해야 할까? **UseShell=true가 필요한 경우:** * 파이프 (`|`) 사용 * 리다이렉션 (`>`, `>>`, `<`) * 셸 변수 치환 (`$VAR`, `$(command)`) * 여러 명령어 체이닝 (`&&`, `||`, `;`) **UseShell=false로 충분한 경우:** * 단일 스크립트 실행 * 실행 파일 호출 * 환경 변수만 필요한 경우 (ORBITRON\_\* 변수는 자동 제공) *** ## 💡 활용 예시 ### 예시 1: 코드 변경 전 Git 상태 확인 파일을 수정하기 전에 Git 작업 디렉토리가 깨끗한지 확인하고, 변경사항이 있으면 차단합니다. **TUI에서 설정:** * Event: `preToolUse` * Matcher: `edit` * Command: `git diff --quiet || (echo 'Warning: Uncommitted changes exist' && exit 1)` * Blocking: ✅ (활성화) **효과**: 커밋되지 않은 변경사항이 있을 때 AI가 파일을 수정하는 것을 방지 *** ### 예시 2: 코드 변경 후 자동 테스트 실행 AI가 코드를 수정한 후 자동으로 테스트를 실행합니다. **TUI에서 설정:** * Event: `postMessageUse` * Matcher: `edit` * Command: `npm test` * InterpretOutput: ✅ (활성화) **효과**: 변경사항이 테스트를 통과하는지 즉시 확인하고, AI가 결과를 해석하여 요약 *** ### 예시 3: 파일 변경 로그 기록 모든 도구 실행을 로그 파일에 기록합니다. **TUI에서 설정:** * Event: `postMessageUse` * Matcher: `*` (모든 도구) * Command: `echo "[$(date)] Tool: $ORBITRON_TOOL_NAME" >> .orbitron-changes.log` * UseShell: ✅ (활성화) **효과**: AI의 모든 작업 이력을 추적 가능 *** ### 예시 4: Bash 명령어 실행 전 권한 확인 위험한 Bash 명령어 실행을 사전에 차단합니다. **TUI에서 설정:** * Event: `preToolUse` * Matcher: `bash` * Command: `echo $ORBITRON_TOOL_INPUT | grep -q 'rm -rf' && (echo 'Dangerous command blocked' && exit 1) || exit 0` * Blocking: ✅ (활성화) * UseShell: ✅ (활성화) **효과**: 위험한 명령어로부터 시스템 보호 *** ### 예시 5: 파일 수정 전 자동 백업 파일을 수정하기 전에 자동으로 백업 파일을 생성합니다. **TUI에서 설정:** * Event: `preToolUse` * Matcher: `edit` * Command: `echo $ORBITRON_TOOL_INPUT | jq -r '.file_path' | xargs -I {} cp {} {}.backup` * UseShell: ✅ (활성화) **효과**: 변경 전 상태를 항상 보존 *** ## ⚙️ 설정 파일 훅 설정은 **Orbitron 실행 위치**에 따라 다른 파일에 저장됩니다: * **홈 디렉토리에서 실행**: `~/.orbitron/hooks.json` * **프로젝트 디렉토리에서 실행**: `/.orbitron/hooks.json` ### 저장 형식 ```json { "preToolUse": [ { "matcher": "bash", "hooks": [ { "command": "echo 'Running pre-tool hook'", "blocking": true, "enabled": true, "interpretOutput": false, "useShell": true, "args": "" } ] } ], "postMessageUse": [ { "matcher": "*", "hooks": [ { "command": "echo 'Post message hook'", "blocking": false, "enabled": true, "interpretOutput": true } ] } ] } ``` **구조 설명:** * 최상위 키: `preToolUse`, `postMessageUse` (이벤트 타입별로 구분) * `matcher`: 적용할 도구 이름 (예: `bash`, `edit`, `*`) * `hooks`: 해당 도구와 이벤트에 적용되는 훅 배열 {% hint style="warning" %} **보안 참고사항**: 프로젝트 디렉토리에서 Orbitron을 실행하면 해당 프로젝트의 `.orbitron/hooks.json`에 저장되며, 홈 디렉토리에서 실행하면 `~/.orbitron/hooks.json`에 저장됩니다. 의도하지 않은 명령어 실행을 방지하기 위해 실행 위치를 확인하세요. {% endhint %} *** ## 🔒 보안 고려사항 1. **훅 명령어 검토**: 훅은 시스템에서 직접 실행되므로, 신뢰할 수 있는 명령어만 사용하세요 2. **실행 위치 확인**: 프로젝트별로 다른 훅이 적용되므로, Orbitron 실행 위치와 해당 `.orbitron/hooks.json` 파일을 확인하세요 3. **차단 기능 활용**: `preToolUse` 훅에서 위험한 작업을 사전에 차단할 수 있습니다 4. **테스트 먼저**: 새 훅을 추가할 때는 항상 테스트 기능을 사용하여 예상대로 작동하는지 확인하세요 *** ## 🔄 실무 워크플로우 ### 완전 자동화된 CI/CD 워크플로우 코드 변경부터 테스트, 빌드, 배포까지 자동화된 워크플로우를 구성할 수 있습니다. ```json { "preToolUse": [ { "matcher": "edit", "hooks": [ { "command": "git diff --quiet || exit 1", "blocking": true, "enabled": true } ] } ], "postMessageUse": [ { "matcher": "edit", "hooks": [ { "command": "npm test", "blocking": false, "enabled": true, "interpretOutput": true }, { "command": "npm run build", "blocking": false, "enabled": true, "interpretOutput": true } ] } ] } ``` **효과:** 1. 파일 수정 전 커밋되지 않은 변경사항 확인 2. 파일 수정 후 자동으로 테스트 실행 3. 테스트 통과 시 자동으로 빌드 실행 4. AI가 테스트/빌드 결과를 해석하여 사용자에게 요약 제공 *** ### 보안 중심 워크플로우 위험한 작업을 사전에 차단하는 보안 중심 워크플로우: ```json { "preToolUse": [ { "matcher": "bash", "hooks": [ { "command": "echo $ORBITRON_TOOL_INPUT | jq -r '.command' | grep -qE 'rm -rf|dd if=|mkfs' && echo '⚠️ 위험한 명령어가 감지되었습니다!' && exit 1 || exit 0", "blocking": true, "enabled": true, "useShell": true } ] }, { "matcher": "edit", "hooks": [ { "command": "echo $ORBITRON_TOOL_INPUT | jq -r '.file_path' | grep -qE '\\.env$|credentials' && echo '❌ 환경 설정 파일은 직접 수정할 수 없습니다!' && exit 1 || exit 0", "blocking": true, "enabled": true, "useShell": true } ] } ] } ``` *** ### 품질 보증 워크플로우 코드 품질을 자동으로 검증하는 워크플로우: ```json { "postMessageUse": [ { "matcher": "edit", "hooks": [ { "command": "eslint $(echo $ORBITRON_TOOL_INPUT | jq -r '.file_path')", "blocking": false, "enabled": true, "interpretOutput": true, "useShell": true }, { "command": "prettier --check $(echo $ORBITRON_TOOL_INPUT | jq -r '.file_path')", "blocking": false, "enabled": true, "interpretOutput": true, "useShell": true } ] } ] } ``` *** ## 🐛 트러블슈팅 ### Hook이 실행되지 않아요 **확인 사항:** * ✅ Hook이 **활성화(Enabled)** 상태인지 확인 (훅 목록에서 `Space`로 토글) * ✅ 도구 이름(Matcher)이 정확한지 확인 * 대소문자 구분: `bash` (올바름) vs `Bash` (틀림) * 도구 목록: `bash`, `edit`, `read`, `write`, `grep`, `glob` 등 * ✅ 이벤트 타입이 올바른지 확인 (`preToolUse` vs `postMessageUse`) **테스트 방법:** ```bash # 1. 훅 목록에서 해당 훅 선택 후 'Enter' 키 입력 # 2. 테스트 결과에서 종료 코드와 출력 확인 # 3. 스크립트를 터미널에서 직접 실행해보기 ./your-hook-script.sh echo $? # 종료 코드 확인 (0이면 성공) ``` *** ### Hook이 도구 실행을 차단하지 않아요 **확인 사항:** * ✅ `Blocking=true`로 설정되어 있는지 확인 * ✅ `preToolUse` 이벤트인지 확인 (postMessageUse에서는 차단 불가) * ✅ 스크립트가 0이 아닌 종료 코드를 반환하는지 확인 **예시 (올바른 차단 스크립트):** ```bash #!/bin/bash # check-git.sh if ! git diff --quiet; then echo "❌ 커밋되지 않은 변경사항이 있습니다!" exit 1 # 0이 아닌 값으로 종료해야 차단됨 fi exit 0 # 정상 종료 ``` **테스트:** ```bash ./check-git.sh echo $? # 1이 출력되어야 차단됨 (0이면 차단 안 됨) ``` *** ### 환경 변수가 비어 있어요 **확인 사항:** * ✅ 환경 변수 이름이 정확한지 확인 (`ORBITRON_` 접두사 필수) * ✅ 쉘 문법이 올바른지 확인 * 올바름: `$ORBITRON_TOOL_NAME` * 틀림: `$TOOL_NAME`, `${TOOL_NAME}` * ✅ `postMessageUse`에서 `ORBITRON_TOOL_RESULT` 사용 중인지 확인 **환경 변수 테스트 스크립트:** ```bash #!/bin/bash # test-env.sh echo "=== Orbitron 환경 변수 테스트 ===" echo "Tool Name: $ORBITRON_TOOL_NAME" echo "Tool Input: $ORBITRON_TOOL_INPUT" echo "Session ID: $ORBITRON_SESSION_ID" echo "Message ID: $ORBITRON_MESSAGE_ID" # postMessageUse에서만 사용 가능 if [ -n "$ORBITRON_TOOL_RESULT" ]; then echo "Tool Result: $ORBITRON_TOOL_RESULT" fi ``` *** ### UseShell을 사용했는데 파이프가 작동하지 않아요 **확인 사항:** * ✅ `UseShell=true`로 설정되어 있는지 확인 * ✅ 파이프 문법이 올바른지 확인 * ✅ 중간 명령어가 정상 작동하는지 확인 **디버깅 방법:** ```bash # 1. 각 단계를 개별적으로 테스트 echo $ORBITRON_TOOL_INPUT # 입력 확인 echo $ORBITRON_TOOL_INPUT | jq . # JSON 파싱 확인 echo $ORBITRON_TOOL_INPUT | jq -r '.file_path' # 최종 결과 확인 # 2. 전체 명령어를 터미널에서 직접 실행 ORBITRON_TOOL_INPUT='{"file_path": "test.js"}' bash -c 'echo $ORBITRON_TOOL_INPUT | jq -r ".file_path"' ``` *** ### Hook 테스트 방법 Orbitron TUI에서 Hook을 안전하게 테스트할 수 있습니다: 1. `/hooks` 명령어로 Hooks 관리 화면 진입 2. 방향키로 테스트할 Hook 선택 3. `Enter` 키 입력 (Test) 4. 테스트 결과 화면에서 출력, 종료 코드, 실행 시간 확인 **테스트 모드 특징:** * 샘플 데이터로 Hook 실행 (실제 도구는 실행 안 됨) * 환경 변수에 샘플 값이 자동으로 설정됨 * 안전하게 스크립트의 동작 확인 가능 *** ### MCP 도구에 Hook이 적용되지 않아요 **현재 제한사항:** * Orbitron의 내장 도구에만 Hook 적용 가능 * MCP (Model Context Protocol) 도구에는 현재 Hook 미지원 * 내장 도구: `bash`, `edit`, `read`, `write`, `grep`, `glob` 등 **대안:** * MCP 도구 실행 후 `postMessageUse` + `*` Hook으로 후처리 * Bash 도구를 통해 MCP 기능을 간접적으로 실행 *** ## 📚 관련 문서 * [명령어 및 단축키 가이드](/orbitron-docs/documentation/ko/user-guide/slash-commands-shortcut.md) * [Bash 모드 가이드](/orbitron-docs/documentation/ko/user-guide/bash-mode-guide.md) * [MCP 통합](/orbitron-docs/documentation/ko/user-guide/mcp-integration.md)