> 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/bash-mode-guide.md).

# Bash 모드 가이드

> Bash 모드는 Orbitron 터미널 내에서 직접 Bash 명령어를 실행할 수 있는 배치(batch) 모드입니다. AI 컨텍스트와 분리되어 빠르고 효율적으로 시스템 명령어를 실행할 수 있으며, 실행 중인 명령어를 즉시 취소할 수도 있습니다.

***

## 🎯 Bash 모드란?

Bash 모드는 Orbitron에서 제공하는 특별한 입력 모드로, 프롬프트에 `!`를 입력하면 활성화됩니다. 이 모드에서는:

* AI를 거치지 않고 **직접** Bash 명령어를 실행합니다
* 명령어와 그 결과가 **AI 컨텍스트에 포함되지 않아** 토큰을 절약할 수 있습니다
* **비동기 실행**으로 긴 작업도 부담 없이 실행 가능합니다
* 명령어 **완료 후 출력 결과를 한번에** 확인할 수 있습니다
* `ESC` 키로 **실행 중인 명령어를 즉시 취소**할 수 있습니다

***

## ⚠️ 중요: 배치 모드의 제한사항

Bash 모드는 **배치(batch) 방식**으로 동작합니다:

* ✅ **지원**: 명령어 실행 후 완료되면 출력을 한번에 표시
* ❌ **미지원**: 실시간 스트리밍 출력 (명령어가 완료되어야 결과 확인 가능)

### 적합한 명령어

```bash
ls -la          # 즉시 완료
git status      # 즉시 완료
npm run build   # 완료 후 결과 표시
go test ./...   # 완료 후 결과 표시
```

### 부적합한 명령어 (별도 터미널 사용 권장)

```bash
tail -f app.log    # 무한 실행 (출력 볼 수 없음)
top                # 실시간 모니터링 (출력 볼 수 없음)
vim file.txt       # 대화형 (작동 안 함)
npm run dev        # 서버 실행 (완료되지 않음)
```

***

## 🚀 Bash 모드 사용하기

### 모드 진입

프롬프트에 `!`를 입력하면 Bash 모드로 전환됩니다:

```
!
```

입력창의 프롬프트가 변경되어 Bash 모드임을 알려줍니다.

***

### 명령어 실행

Bash 모드에서는 일반적인 쉘 명령어를 그대로 입력할 수 있습니다:

```bash
ls -la
```

```bash
git status
```

```bash
npm run build
```

```bash
docker ps
```

명령어를 입력하고 `Enter`를 누르면 즉시 실행되며, 완료 후 출력이 화면에 표시됩니다.

***

### 명령어 취소

실행 중인 명령어를 중단하고 싶다면 `ESC` 키를 누르세요:

```
ESC
```

* 긴 실행 시간이 필요한 작업 (빌드, 테스트 등)을 취소할 때 유용합니다
* 명령어가 즉시 종료되고 제어권이 돌아옵니다

***

### 모드 종료

Bash 모드를 종료하고 일반 대화 모드로 돌아가려면 빈 프롬프트에서 `ESC` 키를 누르세요.

***

## ⚡ 주요 기능

### 🔄 1. 비동기 배치 실행

Bash 모드는 명령어를 비동기로 실행하므로:

* 긴 작업이 진행되는 동안에도 터미널이 블로킹되지 않습니다
* 명령어가 완료될 때까지 "Executing command..." 메시지가 표시됩니다
* 실행 중 언제든 `ESC`로 취소 가능합니다

***

### 📊 2. 배치 출력 표시

명령어 실행이 완료되면 출력이 한번에 표시됩니다:

* stdout과 stderr 출력을 모두 캡처
* 출력이 긴 경우 처음 20줄만 표시하고 "Click to expand" 링크 표시
* 코드 블록 형식으로 가독성 있게 렌더링

**중요**: 스트리밍 출력은 지원하지 않습니다. 명령어가 완료되어야 결과를 볼 수 있습니다.

***

### 🧹 3. AI 컨텍스트 분리

Bash 모드에서 실행한 명령어는:

* **AI 대화 히스토리에 포함되지 않습니다**
* 토큰 사용량을 절약할 수 있습니다
* AI가 불필요한 명령어 출력에 혼동되지 않습니다

이는 다음과 같은 상황에서 특히 유용합니다:

* 긴 로그를 확인해야 할 때
* 반복적인 명령어를 실행할 때
* AI의 도움 없이 빠르게 터미널 작업을 할 때

***

### 🎛️ 4. 세션별 상태 관리

각 Orbitron 세션은 독립적인 Bash 모드 상태를 유지합니다:

* 세션을 전환해도 각 세션의 Bash 모드 상태는 유지됩니다
* 여러 프로젝트를 동시에 작업할 때 편리합니다

***

## 💡 활용 예시

### 예시 1: 빠른 파일 확인

디렉토리 구조나 파일 내용을 빠르게 확인:

```bash
!
ls -la
cat package.json
```

AI에게 묻지 않고 직접 확인하여 시간과 토큰을 절약합니다.

***

### 예시 2: Git 상태 확인 및 조작

Git 작업을 빠르게 수행:

```bash
!
git status
git log --oneline -5
git diff HEAD~1
```

***

### 예시 3: 빌드 및 테스트 실행

프로젝트 빌드나 테스트를 실행하고 완료 후 결과 확인:

```bash
!
npm run build
# "Executing command..." 표시 → 완료 후 출력 확인
# 너무 오래 걸리면 ESC로 취소 가능
```

***

### 예시 4: 로그 확인

로그 파일 내용 확인:

```bash
!
tail -100 /var/log/app.log  # 마지막 100줄 확인
# 또는
cat debug.log
```

**주의**: `tail -f`처럼 계속 실행되는 명령어는 완료되지 않으므로 출력을 볼 수 없습니다. ESC로 취소할 수 있지만, 일반 터미널에서 사용하는 것이 좋습니다.

***

### 예시 5: 도커 컨테이너 관리

도커 컨테이너를 빠르게 관리:

```bash
!
docker ps
docker logs container-name --tail 50  # 마지막 50줄만
```

**주의**: `docker exec -it`처럼 대화형(interactive) 명령어는 지원하지 않습니다.

***

## 🔄 일반 모드와의 차이점

| 특징        | 일반 모드 (AI 명령어)     | Bash 모드                  |
| --------- | ------------------ | ------------------------ |
| **실행 방식** | AI가 bash 도구를 통해 실행 | 직접 실행 (배치 모드)            |
| **컨텍스트**  | AI 대화 히스토리에 포함됨    | AI 컨텍스트와 분리됨             |
| **토큰 사용** | 명령어와 출력이 토큰 사용     | 토큰 사용 없음                 |
| **출력 방식** | AI가 해석하여 응답        | 완료 후 stdout/stderr 직접 표시 |
| **출력 제한** | 없음 (전체 표시)         | 20줄 제한 (초과분은 라인 수 표시)    |
| **취소**    | AI 응답 전체를 취소해야 함   | 명령어만 즉시 취소 가능 (ESC)      |
| **속도**    | AI 처리 시간 필요        | 즉시 실행                    |
| **AI 지원** | AI가 명령어 제안 및 설명    | 사용자가 직접 입력               |

***

## 🎯 언제 Bash 모드를 사용할까?

### Bash 모드가 적합한 경우:

* ✅ 빠른 파일 확인이나 간단한 명령어 실행 (`ls`, `pwd`, `cat`)
* ✅ 완료 시점이 명확한 빌드나 테스트 실행 (`npm run build`, `go test`)
* ✅ 반복적인 명령어 실행 (토큰 절약)
* ✅ 짧은 로그 확인 (`tail -100`, `cat log.txt`)
* ✅ AI의 도움 없이 익숙한 명령어 실행

### Bash 모드가 부적합한 경우:

* ❌ 스트리밍 출력이 필요한 명령어 (`tail -f`, `watch`, `top`)
* ❌ 대화형(interactive) 명령어 (`vim`, `nano`, `python REPL`)
* ❌ 사용자 입력이 필요한 명령어 (프롬프트가 있는 명령어)
* ❌ 무한 실행 명령어 (`npm run dev`, 서버 실행)

> **권장**: 위와 같은 명령어는 별도의 터미널 창에서 실행하세요.

### 일반 모드(AI)가 적합한 경우:

* ✅ 복잡한 명령어가 필요하지만 정확한 문법을 모를 때
* ✅ 명령어 실행 결과를 AI가 분석하고 해석해야 할 때
* ✅ 여러 파일을 함께 수정하는 복잡한 작업
* ✅ 명령어 실행 결과에 따라 다음 작업을 결정해야 할 때
* ✅ 긴 출력을 전부 확인하고 AI가 분석해야 할 때

***

## ⚙️ 기술적 세부사항

### 배치 모드 실행 메커니즘

Bash 모드는 명령어를 백그라운드에서 비동기로 실행합니다:

* 명령어가 실행되는 동안에도 UI는 반응성을 유지합니다
* 표준 출력(stdout)과 에러 출력(stderr)을 모두 캡처합니다
* 명령어 완료 후 수집된 출력을 한번에 화면에 표시합니다
* ESC 키를 누르면 취소 신호가 즉시 실행 중인 프로세스에 전달됩니다

***

### 출력 제한 및 표시

출력은 UI 가독성을 위해 제한됩니다:

* **최대 표시 라인**: 20줄
* **초과 시**: "Click to expand" 링크로 전체 내용 확인 가능
* **긴 라인 처리**: 너무 긴 라인은 자동으로 잘림 (한글/특수문자 안전 처리)
* **렌더링**: bash 코드 블록 형식으로 표시

전체 출력은 세션 히스토리에 저장되며, 화면에는 처음 20줄만 표시됩니다.

***

### 메시지 필터링

Bash 모드에서 실행된 명령어는 AI 컨텍스트에서 자동으로 필터링됩니다:

* `UserBash` 타입의 메시지는 LLM에 전달되지 않습니다
* 시스템 메시지도 필터링되어 컨텍스트를 깔끔하게 유지합니다
* AI 토큰을 절약하면서도 사용자는 히스토리에서 확인 가능합니다

***

### 세션별 독립 실행

각 Orbitron 세션은 독립적으로 Bash 명령을 실행할 수 있습니다:

* 여러 세션에서 동시에 명령 실행 가능
* 각 세션의 명령은 서로 영향을 주지 않음
* 세션마다 독립적으로 취소 가능

***

## 🐛 트러블슈팅

### 명령어가 실행되지 않음

* Bash 모드로 제대로 진입했는지 확인하세요 (프롬프트 변경 확인)
* 명령어 문법이 올바른지 확인하세요
* 필요한 프로그램이 PATH에 있는지 확인하세요

### 출력이 표시되지 않음

**원인**: 명령어가 완료되지 않았거나 스트리밍 명령어를 실행했을 수 있습니다.

**해결 방법**:

* "Executing command..." 메시지가 계속 표시되면 명령어가 아직 실행 중입니다
* `tail -f`, `watch`, `top` 같은 무한 실행 명령어는 ESC로 취소해야 합니다
* 완료되었는데도 출력이 없다면 명령어가 실제로 출력을 생성하지 않은 것입니다

### 출력이 잘렸음 (Click to expand)

**원인**: 출력이 20줄을 초과했습니다.

**현재 동작**: 처음 20줄만 표시하고 "Click to expand" 링크로 전체 내용 확인 가능합니다.

**해결 방법**:

* AI에게 명령어를 실행하도록 요청하면 전체 출력을 볼 수 있습니다
* 예: "ls -la 명령어를 실행해줘" (AI 도구 사용)
* 또는 출력을 파일로 리다이렉트: `!command > output.txt` 후 파일 읽기

### 명령어가 취소되지 않음

**원인**: 일부 프로세스는 즉시 종료되지 않을 수 있습니다.

**해결 방법**:

* `ESC` 키를 다시 눌러보세요
* 여전히 실행 중이면 별도 터미널에서 `ps aux | grep command` 후 `kill` 사용
* 세션을 전환했다가 다시 돌아와서 ESC 시도

### 대화형/스트리밍 명령어 제한

**문제**: Bash 모드는 배치 모드이므로 다음 명령어들은 작동하지 않거나 출력을 볼 수 없습니다:

* ❌ `vim`, `nano` - 대화형 에디터
* ❌ `python`, `node` - REPL (인터프리터)
* ❌ `tail -f` - 스트리밍 로그
* ❌ `top`, `htop` - 실시간 모니터링
* ❌ `watch` - 명령어 반복 실행
* ❌ `docker exec -it` - 대화형 셸
* ❌ 프롬프트가 있는 명령어 (입력 대기)

**해결 방법**:

* 위 명령어들은 **별도의 터미널 창**에서 실행하세요
* 대안 명령어 사용: `tail -f` → `tail -100`, `docker exec -it` → `docker exec` (단일 명령)

***

## 🔒 보안 고려사항

1. **명령어 확인**: Bash 모드에서 실행하는 모든 명령어는 시스템에서 직접 실행되므로 주의하세요
2. **권한 관리**: 민감한 작업은 적절한 권한으로 실행하세요
3. **경로 확인**: 명령어 실행 전 현재 작업 디렉토리를 확인하세요
4. **훅 활용**: Shell 훅을 설정하여 위험한 명령어를 사전에 차단할 수 있습니다

***

## 📋 명령어 타입별 분류표

아래 표를 참고하여 Bash 모드 사용 여부를 결정하세요:

| 명령어 타입          | 예시                                  | Bash 모드 적합성 | 설명               |
| --------------- | ----------------------------------- | ----------- | ---------------- |
| **일반 명령어**      | `ls`, `pwd`, `cat`, `echo`          | ✅ 매우 적합     | 즉시 완료되고 출력이 짧음   |
| **빌드/테스트**      | `npm run build`, `go test`, `make`  | ✅ 적합        | 완료 시점이 명확함       |
| **로그 확인**       | `tail -100`, `cat log.txt`, `head`  | ✅ 적합        | 고정된 출력량          |
| **Git 명령어**     | `git status`, `git log`, `git diff` | ✅ 매우 적합     | 빠르게 완료됨          |
| **Docker (조회)** | `docker ps`, `docker images`        | ✅ 적합        | 조회 명령어는 빠름       |
| **스트리밍**        | `tail -f`, `watch`, `less`          | ❌ 부적합       | 무한 실행, 출력 볼 수 없음 |
| **실시간 모니터링**    | `top`, `htop`, `iotop`              | ❌ 부적합       | 화면 갱신, 출력 볼 수 없음 |
| **대화형 에디터**     | `vim`, `nano`, `emacs`              | ❌ 불가능       | 사용자 입력 필요        |
| **REPL**        | `python`, `node`, `irb`             | ❌ 불가능       | 대화형 인터프리터        |
| **서버 실행**       | `npm run dev`, `./server`           | ❌ 부적합       | 완료되지 않음          |
| **대화형 셸**       | `docker exec -it`, `ssh`            | ❌ 불가능       | 사용자 입력 필요        |
| **프롬프트형**       | `sudo`, `rm -i`                     | ⚠️ 주의       | `-y` 플래그로 자동화 가능 |

### 팁

**출력이 긴 명령어의 경우:**

```bash
# Bash 모드 (처음 20줄만 표시됨)
!ls -la /usr/bin
# 20줄 초과 시 "Click to expand" 링크로 전체 확인 가능

# 또는 파일로 저장
!ls -la /usr/bin > output.txt
# 그 다음 AI에게 "output.txt 파일 읽어줘"
```

**무한 실행 명령어의 대안:**

```bash
# ❌ Bash 모드에서 불가능
!tail -f app.log

# ✅ 대신 이렇게
!tail -100 app.log  # 마지막 100줄만
```

**서버 실행:**

```bash
# ❌ Bash 모드에서 부적합 (완료되지 않음)
!npm run dev

# ✅ 별도 터미널에서 실행
# 또는 백그라운드 실행 후 로그 확인
!npm run dev > server.log 2>&1 &
!tail -50 server.log  # 로그 확인
```

***

## 📚 관련 문서

* [명령어 및 단축키 가이드](/orbitron-docs/documentation/ko/user-guide/slash-commands-shortcut.md)
* [Shell 훅 가이드](/orbitron-docs/documentation/ko/user-guide/hooks-guide.md)
* [MCP 통합](/orbitron-docs/documentation/ko/user-guide/mcp-integration.md)