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

# Bash Mode Guide

> Bash Mode is a batch mode that allows you to execute Bash commands directly within the Orbitron terminal. It operates separately from the AI context, enabling fast and efficient system command execution, and you can instantly cancel running commands.

***

## 🎯 What is Bash Mode?

Bash Mode is a special input mode in Orbitron that activates when you enter `!` in the prompt. In this mode:

* Execute Bash commands **directly** without going through the AI
* Commands and their results are **not included in the AI context**, saving tokens
* **Asynchronous execution** allows running long tasks without burden
* **View output all at once after command completion**
* **Instantly cancel** running commands with the `ESC` key

***

## ⚠️ Important: Batch Mode Limitations

Bash Mode operates in a **batch** manner:

* ✅ **Supported**: Displays output all at once when command completes
* ❌ **Not Supported**: Real-time streaming output (must wait for command to complete to see results)

### Suitable Commands

```bash
ls -la          # Completes immediately
git status      # Completes immediately
npm run build   # Shows results after completion
go test ./...   # Shows results after completion
```

### Unsuitable Commands (Use Separate Terminal)

```bash
tail -f app.log    # Infinite execution (no output visible)
top                # Real-time monitoring (no output visible)
vim file.txt       # Interactive (won't work)
npm run dev        # Server execution (won't complete)
```

***

## 🚀 Using Bash Mode

### Entering the Mode

Enter `!` in the prompt to switch to Bash mode:

```
!
```

The input prompt will change to indicate you're in Bash mode.

***

### Executing Commands

In Bash mode, you can enter regular shell commands as-is:

```bash
ls -la
```

```bash
git status
```

```bash
npm run build
```

```bash
docker ps
```

Enter a command and press `Enter` to execute immediately, with output displayed on screen after completion.

***

### Canceling Commands

To stop a running command, press the `ESC` key:

```
ESC
```

* Useful for canceling long-running tasks (builds, tests, etc.)
* Commands terminate immediately and control returns to you

***

### Exiting the Mode

To exit Bash mode and return to normal conversation mode, press `ESC` key on an empty prompt.

***

## ⚡ Key Features

### 🔄 1. Asynchronous Batch Execution

Bash mode executes commands asynchronously, so:

* The terminal remains unblocked even during long tasks
* "Executing command..." message displays until command completes
* Cancel anytime with `ESC`

***

### 📊 2. Batch Output Display

Command output displays all at once after execution completes:

* Captures both stdout and stderr output
* For long output, shows only the first 20 lines with a "Click to expand" link
* Renders in code block format for readability

**Important**: Streaming output is not supported. You must wait for command completion to see results.

***

### 🧹 3. AI Context Separation

Commands executed in Bash mode:

* **Are not included in AI conversation history**
* Save token usage
* Prevent AI confusion from unnecessary command output

This is especially useful in situations like:

* When checking long logs
* When executing repetitive commands
* When quickly working in terminal without AI assistance

***

### 🎛️ 4. Per-Session State Management

Each Orbitron session maintains an independent Bash mode state:

* Bash mode state persists when switching sessions
* Convenient when working on multiple projects simultaneously

***

## 💡 Usage Examples

### Example 1: Quick File Checks

Quickly check directory structure or file contents:

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

Save time and tokens by checking directly without asking the AI.

***

### Example 2: Git Status Check and Operations

Quickly perform Git operations:

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

***

### Example 3: Running Builds and Tests

Execute project builds or tests and view results after completion:

```bash
!
npm run build
# "Executing command..." displays → view output after completion
# Cancel with ESC if taking too long
```

***

### Example 4: Log Viewing

View log file contents:

```bash
!
tail -100 /var/log/app.log  # View last 100 lines
# or
cat debug.log
```

**Note**: Commands like `tail -f` that run continuously won't complete, so you won't see output. You can cancel with ESC, but it's better to use a regular terminal.

***

### Example 5: Docker Container Management

Quickly manage Docker containers:

```bash
!
docker ps
docker logs container-name --tail 50  # Last 50 lines only
```

**Note**: Interactive commands like `docker exec -it` are not supported.

***

## 🔄 Differences from Normal Mode

| Feature              | Normal Mode (AI Commands)           | Bash Mode                                       |
| -------------------- | ----------------------------------- | ----------------------------------------------- |
| **Execution Method** | AI executes via bash tool           | Direct execution (batch mode)                   |
| **Context**          | Included in AI conversation history | Separated from AI context                       |
| **Token Usage**      | Commands and output use tokens      | No token usage                                  |
| **Output Method**    | AI interprets and responds          | Direct stdout/stderr display after completion   |
| **Output Limit**     | None (full display)                 | 20 line limit (additional lines shown as count) |
| **Cancellation**     | Must cancel entire AI response      | Cancel only command instantly (ESC)             |
| **Speed**            | AI processing time required         | Immediate execution                             |
| **AI Support**       | AI suggests and explains commands   | User enters directly                            |

***

## 🎯 When to Use Bash Mode?

### When Bash Mode is Suitable:

* ✅ Quick file checks or simple command execution (`ls`, `pwd`, `cat`)
* ✅ Builds or tests with clear completion points (`npm run build`, `go test`)
* ✅ Repetitive command execution (save tokens)
* ✅ Short log viewing (`tail -100`, `cat log.txt`)
* ✅ Executing familiar commands without AI assistance

### When Bash Mode is Unsuitable:

* ❌ Commands requiring streaming output (`tail -f`, `watch`, `top`)
* ❌ Interactive commands (`vim`, `nano`, `python REPL`)
* ❌ Commands requiring user input (commands with prompts)
* ❌ Infinite execution commands (`npm run dev`, server execution)

> **Recommendation**: Use a separate terminal window for such commands.

### When Normal Mode (AI) is Suitable:

* ✅ Need complex commands but unsure of exact syntax
* ✅ AI needs to analyze and interpret command execution results
* ✅ Complex tasks involving multiple file modifications
* ✅ Need to decide next actions based on command results
* ✅ Need full output for AI analysis

***

## ⚙️ Technical Details

### Batch Mode Execution Mechanism

Bash mode executes commands asynchronously in the background:

* UI maintains responsiveness while commands run
* Captures both standard output (stdout) and error output (stderr)
* Displays collected output all at once after command completion
* Pressing ESC immediately sends cancellation signal to the running process

***

### Output Limiting and Display

Output is limited for UI readability:

* **Maximum displayed lines**: 20 lines
* **When exceeded**: Full content viewable via the "Click to expand" link
* **Long line handling**: Very long lines are automatically truncated (safe handling of multibyte characters)
* **Rendering**: Displayed as bash code block format

Full output is saved in session history, and only the first 20 lines are displayed on screen.

***

### Message Filtering

Commands executed in Bash mode are automatically filtered from AI context:

* `UserBash` type messages are not passed to the LLM
* System messages are also filtered to keep context clean
* Saves AI tokens while users can still view in history

***

### Independent Execution per Session

Each Orbitron session can execute Bash commands independently:

* Multiple sessions can run commands simultaneously
* Each session's commands don't affect others
* Can cancel independently per session

***

## 🐛 Troubleshooting

### Command Not Executing

* Verify you properly entered Bash mode (check prompt change)
* Check command syntax is correct
* Verify required programs are in PATH

### Output Not Displaying

**Cause**: Command may not have completed or you may have run a streaming command.

**Solutions**:

* If "Executing command..." keeps showing, command is still running
* Infinite execution commands like `tail -f`, `watch`, `top` must be cancelled with ESC
* If completed but no output, command didn't actually generate output

### Output Truncated (Click to expand)

**Cause**: Output exceeded 20 lines.

**Current behavior**: Shows only the first 20 lines, with the full content viewable via the "Click to expand" link.

**Solutions**:

* Ask AI to execute command to see full output
* Example: "Please run ls -la command" (uses AI tool)
* Or redirect output to file: `!command > output.txt` then read the file

### Command Won't Cancel

**Cause**: Some processes may not terminate immediately.

**Solutions**:

* Try pressing `ESC` key again
* If still running, use `ps aux | grep command` then `kill` in separate terminal
* Switch sessions and return, then try ESC

### Interactive/Streaming Command Limitations

**Issue**: Bash mode is batch mode, so these commands won't work or won't show output:

* ❌ `vim`, `nano` - Interactive editors
* ❌ `python`, `node` - REPL (interpreters)
* ❌ `tail -f` - Streaming logs
* ❌ `top`, `htop` - Real-time monitoring
* ❌ `watch` - Repeated command execution
* ❌ `docker exec -it` - Interactive shell
* ❌ Commands with prompts (waiting for input)

**Solutions**:

* Use these commands in a **separate terminal window**
* Use alternative commands: `tail -f` → `tail -100`, `docker exec -it` → `docker exec` (single command)

***

## 🔒 Security Considerations

1. **Verify commands**: All commands executed in Bash mode run directly on your system, so be careful
2. **Manage permissions**: Execute sensitive tasks with appropriate permissions
3. **Check paths**: Verify the current working directory before executing commands
4. **Use hooks**: Configure Shell hooks to proactively block dangerous commands

***

## 📋 Command Type Classification Table

Refer to this table to decide whether to use Bash mode:

| Command Type             | Examples                            | Bash Mode Suitability | Description                             |
| ------------------------ | ----------------------------------- | --------------------- | --------------------------------------- |
| **General Commands**     | `ls`, `pwd`, `cat`, `echo`          | ✅ Very Suitable       | Completes immediately with short output |
| **Build/Test**           | `npm run build`, `go test`, `make`  | ✅ Suitable            | Clear completion point                  |
| **Log Viewing**          | `tail -100`, `cat log.txt`, `head`  | ✅ Suitable            | Fixed output amount                     |
| **Git Commands**         | `git status`, `git log`, `git diff` | ✅ Very Suitable       | Completes quickly                       |
| **Docker (Query)**       | `docker ps`, `docker images`        | ✅ Suitable            | Query commands are fast                 |
| **Streaming**            | `tail -f`, `watch`, `less`          | ❌ Unsuitable          | Infinite execution, no output visible   |
| **Real-time Monitoring** | `top`, `htop`, `iotop`              | ❌ Unsuitable          | Screen refresh, no output visible       |
| **Interactive Editors**  | `vim`, `nano`, `emacs`              | ❌ Not Possible        | Requires user input                     |
| **REPL**                 | `python`, `node`, `irb`             | ❌ Not Possible        | Interactive interpreter                 |
| **Server Execution**     | `npm run dev`, `./server`           | ❌ Unsuitable          | Won't complete                          |
| **Interactive Shell**    | `docker exec -it`, `ssh`            | ❌ Not Possible        | Requires user input                     |
| **Prompt Type**          | `sudo`, `rm -i`                     | ⚠️ Caution            | Can automate with `-y` flag             |

### Tips

**For commands with long output:**

```bash
# Bash mode (only shows the first 20 lines)
!ls -la /usr/bin
# Beyond 20 lines, view everything via the "Click to expand" link

# Or save to a file
!ls -la /usr/bin > output.txt
# Then ask AI "please read output.txt"
```

**Alternatives to infinite execution commands:**

```bash
# ❌ Not possible in Bash mode
!tail -f app.log

# ✅ Do this instead
!tail -100 app.log  # Last 100 lines only
```

**Server execution:**

```bash
# ❌ Unsuitable in Bash mode (won't complete)
!npm run dev

# ✅ Run in separate terminal
# Or run in background and check logs
!npm run dev > server.log 2>&1 &
!tail -50 server.log  # Check logs
```

***

## 📚 Related Documentation

* [Command & Shortcut Guide](/orbitron-docs/user-guide/slash-commands-shortcut.md)
* [Shell Hooks Guide](/orbitron-docs/user-guide/hooks-guide.md)
* [MCP Integration](/orbitron-docs/user-guide/mcp-integration.md)