@tecet/ollm 0.1.3

package/docs/UI&Settings/Terminal.md

@@ -0,0 +1,637 @@
+# Terminal Guide
+
+**Last Updated:** January 26, 2026
+
+Complete guide to the integrated terminal system in OLLM CLI, including architecture, usage, and integration with the shell tool.
+
+---
+
+## Overview
+
+OLLM CLI includes an integrated terminal system that provides two independent terminal sessions within the UI. The terminal uses PTY (pseudo-terminal) for shell process management and xterm.js headless for ANSI parsing and rendering.
+
+---
+
+## Terminal Sessions
+
+### Dual Terminal Design
+
+OLLM CLI provides two independent terminal sessions:
+
+1. **Terminal 1** - Primary terminal (implementation TBD)
+2. **Terminal 2** - Secondary terminal (fully implemented)
+
+**Features:**
+
+- Each terminal runs in its own PTY process
+- Independent shell sessions
+- Separate scrollback buffers
+- Can be focused and controlled independently
+
+---
+
+## Accessing the Terminal
+
+### Opening the Terminal
+
+**Method 1: Side Panel Tab**
+
+1. Press `Ctrl+P` to open side panel (if closed)
+2. Press `Ctrl+8` to switch to Terminal tab
+3. Terminal displays in the side panel
+
+**Method 2: Direct Navigation**
+
+- Press `Ctrl+8` directly to open side panel and switch to terminal
+
+---
+
+### Terminal Layout
+
+```
+┌─ Terminal ───────────────────────────────┐
+│ $ ls -la                                  │
+│ total 48                                  │
+│ drwxr-xr-x  12 user  staff   384 Jan 26  │
+│ drwxr-xr-x   5 user  staff   160 Jan 25  │
+│ -rw-r--r--   1 user  staff  1234 Jan 26  │
+│                                           │
+│ $ _                                       │
+│                                           │
+│ [Ctrl+L: Clear | Ctrl+C: Interrupt]      │
+└───────────────────────────────────────────┘
+```
+
+---
+
+## Terminal Features
+
+### Shell Integration
+
+**Platform-Specific Shells:**
+
+- **Windows:** PowerShell
+- **macOS:** bash or zsh
+- **Linux:** bash
+
+**Shell Configuration:**
+
+- PowerShell: Prediction disabled for cleaner output
+- Bash: Standard configuration
+- Environment variables inherited from parent process
+
+---
+
+### ANSI Rendering
+
+The terminal supports full ANSI escape sequences:
+
+**Text Formatting:**
+
+- Bold, italic, underline
+- Dim, inverse
+- Strikethrough
+
+**Colors:**
+
+- 16 basic colors
+- 256-color palette
+- True color (24-bit RGB)
+
+**Cursor Control:**
+
+- Cursor positioning
+- Cursor visibility
+- Cursor styles
+
+---
+
+### Scrollback Buffer
+
+**Configuration:**
+
+- Default: 1000 lines
+- Prevents unbounded memory growth
+- Older lines automatically removed
+
+**Scrolling:**
+
+- `Ctrl+Shift+Up` - Scroll up
+- `Ctrl+Shift+Down` - Scroll down
+- Auto-scroll to bottom on new output
+
+---
+
+## Terminal Commands
+
+### Sending Commands
+
+**Method 1: Type in Terminal**
+
+1. Focus the terminal (click or navigate)
+2. Type your command
+3. Press `Return` to execute
+
+**Method 2: Programmatic**
+
+```typescript
+// Via Terminal Context
+const { sendCommand } = useTerminal();
+sendCommand('ls -la');
+```
+
+---
+
+### Command Examples
+
+**File Operations:**
+
+```bash
+ls -la                  # List files
+cd src                  # Change directory
+cat file.txt            # View file contents
+```
+
+**Git Operations:**
+
+```bash
+git status              # Check git status
+git diff                # View changes
+git log --oneline       # View commit history
+```
+
+**System Information:**
+
+```bash
+# Windows (PowerShell)
+Get-Process             # List processes
+Get-Service             # List services
+
+# macOS/Linux (bash)
+ps aux                  # List processes
+df -h                   # Disk usage
+```
+
+---
+
+## Terminal Controls
+
+### Keyboard Shortcuts
+
+**Scrolling:**
+
+- `Ctrl+Shift+Up` - Scroll up one line
+- `Ctrl+Shift+Down` - Scroll down one line
+- `Page Up` - Scroll up one page
+- `Page Down` - Scroll down one page
+
+**Control:**
+
+- `Ctrl+C` - Interrupt current process
+- `Ctrl+L` - Clear terminal
+- `Ctrl+D` - Send EOF (exit shell)
+
+**Navigation:**
+
+- `Up` / `Down` - Command history
+- `Ctrl+R` - Reverse search history
+- `Tab` - Auto-complete
+
+---
+
+### Terminal Actions
+
+**Clear Terminal:**
+
+```bash
+/terminal clear
+# or
+Ctrl+L
+```
+
+**Interrupt Process:**
+
+```bash
+Ctrl+C
+```
+
+**Restart Terminal:**
+
+```bash
+/terminal restart
+```
+
+---
+
+## Shell Tool Integration
+
+### Automatic Execution
+
+When the AI uses the shell tool, commands are automatically executed in the terminal:
+
+**Flow:**
+
+1. AI decides to use shell tool
+2. Command sent to terminal
+3. Terminal executes command
+4. Output displayed in terminal
+5. Result returned to AI
+
+**Example:**
+
+```
+User: List all TypeScript files
+Assistant: I'll search for TypeScript files.
+[Tool: shell]
+Command: find . -name "*.ts"
+Output:
+./src/index.ts
+./src/utils.ts
+./tests/app.test.ts
+```
+
+---
+
+### Manual Execution
+
+You can also execute commands manually in the terminal:
+
+**Method 1: Direct Input**
+
+1. Focus terminal
+2. Type command
+3. Press `Return`
+
+**Method 2: Via Chat**
+
+```
+User: Run "npm test" in the terminal
+Assistant: I'll execute that command.
+[Tool: shell]
+Command: npm test
+```
+
+---
+
+## Terminal Context API
+
+### Using Terminal Context
+
+**Import:**
+
+```typescript
+import { useTerminal } from '../contexts/TerminalContext';
+```
+
+**Access:**
+
+```typescript
+const {
+  output, // Structured terminal output
+  isRunning, // PTY process status
+  sendCommand, // Send command + Enter
+  sendRawInput, // Send raw characters
+  clear, // Clear terminal
+  interrupt, // Send Ctrl+C
+  resize, // Resize terminal
+} = useTerminal();
+```
+
+---
+
+### Methods
+
+**sendCommand(command: string)**
+
+- Sends command with carriage return
+- Use for complete commands
+- Example: `sendCommand('ls -la')`
+
+**sendRawInput(char: string)**
+
+- Sends raw characters without modification
+- Use for interactive input
+- Example: `sendRawInput('y')` for yes/no prompts
+
+**clear()**
+
+- Clears xterm buffer
+- Sends `clear` command to shell
+- Resets output state
+
+**interrupt()**
+
+- Sends Ctrl+C to PTY
+- Interrupts running process
+- Does not clear terminal
+
+**resize(cols: number, rows: number)**
+
+- Resizes both xterm and PTY
+- Minimum: 1 col × 1 row
+- Silently fails on error
+
+---
+
+## Terminal Output
+
+### Output Structure
+
+Terminal output is structured as ANSI tokens:
+
+```typescript
+interface AnsiToken {
+  text: string;
+  bold: boolean;
+  italic: boolean;
+  underline: boolean;
+  dim: boolean;
+  inverse: boolean;
+  fg: string; // Hex color
+  bg: string; // Hex color
+}
+
+type AnsiLine = AnsiToken[];
+type AnsiOutput = AnsiLine[];
+```
+
+---
+
+### Rendering
+
+**Text Formatting:**
+
+```typescript
+<Text
+  color={token.fg}
+  backgroundColor={token.bg}
+  bold={token.bold}
+  italic={token.italic}
+  underline={token.underline}
+  dimColor={token.dim}
+  inverse={token.inverse}
+>
+  {token.text}
+</Text>
+```
+
+**Color Support:**
+
+- Default colors (terminal defaults)
+- 256-color ANSI palette
+- True color (24-bit RGB)
+
+---
+
+## Advanced Usage
+
+### Command History
+
+Command history is managed by the shell:
+
+**Bash:**
+
+- Stored in `~/.bash_history`
+- Navigate with `Up` / `Down` arrows
+- Search with `Ctrl+R`
+
+**PowerShell:**
+
+- Managed by PSReadLine module
+- Navigate with `Up` / `Down` arrows
+- Search with `Ctrl+R`
+
+---
+
+### Interactive Programs
+
+The terminal supports interactive programs:
+
+**Examples:**
+
+- `vim` / `nano` - Text editors
+- `htop` / `top` - Process monitors
+- `less` / `more` - Pagers
+- Interactive prompts (y/n)
+
+**Note:** Some programs may not render correctly due to terminal size constraints.
+
+---
+
+### Long-Running Commands
+
+**Behavior:**
+
+- Commands run in background
+- Output streams in real-time
+- Can be interrupted with `Ctrl+C`
+
+**Examples:**
+
+```bash
+# Development server
+npm run dev
+
+# Watch mode
+npm run test -- --watch
+
+# Long-running script
+./deploy.sh
+```
+
+---
+
+## Troubleshooting
+
+### Terminal Not Starting
+
+**Symptoms:**
+
+- Terminal tab is empty
+- No shell prompt appears
+
+**Solutions:**
+
+1. Check shell executable exists
+2. Verify PTY spawn permissions
+3. Check environment variables
+4. Restart OLLM CLI
+
+**Verify:**
+
+```bash
+# Check shell path
+which bash          # macOS/Linux
+where powershell    # Windows
+```
+
+---
+
+### Output Not Displaying
+
+**Symptoms:**
+
+- Commands execute but no output
+- Partial output displayed
+
+**Solutions:**
+
+1. Check xterm.js buffer state
+2. Verify ANSI parsing
+3. Clear terminal and retry
+4. Check terminal size
+
+**Verify:**
+
+```bash
+# Test with simple command
+echo "Hello World"
+
+# Check terminal size
+echo $COLUMNS $LINES    # bash
+$Host.UI.RawUI.WindowSize  # PowerShell
+```
+
+---
+
+### Commands Not Working
+
+**Symptoms:**
+
+- Commands don't execute
+- No response to input
+
+**Solutions:**
+
+1. Check terminal focus
+2. Verify PTY process running
+3. Check for hung process
+4. Restart terminal
+
+**Verify:**
+
+```bash
+# Check if shell is responsive
+echo "test"
+
+# If hung, interrupt
+Ctrl+C
+
+# If still hung, restart terminal
+/terminal restart
+```
+
+---
+
+### Colors Look Wrong
+
+**Symptoms:**
+
+- Colors don't match theme
+- Washed out or incorrect colors
+
+**Solutions:**
+
+1. Check terminal color support
+2. Verify theme settings
+3. Test with different theme
+4. Check ANSI color mode
+
+**Verify:**
+
+```bash
+# Test colors
+ls --color=auto    # Linux
+ls -G              # macOS
+Get-ChildItem      # PowerShell (auto-colored)
+```
+
+---
+
+## Performance Considerations
+
+### Buffer Optimization
+
+**Viewport-Based Rendering:**
+
+- Only renders visible lines
+- Uses viewport position
+- Avoids re-rendering entire buffer
+
+**Memory Management:**
+
+- Scrollback limit prevents unbounded growth
+- Older lines automatically removed
+- Token grouping reduces React components
+
+---
+
+### Responsive Behavior
+
+**Width Calculation:**
+
+- Adapts to UI layout
+- Accounts for side panel visibility
+- Minimum width: 10 columns
+
+**Height Calculation:**
+
+- Adapts to available space
+- Accounts for header and status bar
+- Minimum height: 1 row
+
+**Dynamic Resize:**
+
+- Automatically resizes on layout changes
+- Resizes both xterm and PTY together
+- Errors silently caught
+
+---
+
+## Best Practices
+
+### Terminal Usage
+
+1. **Check Process Status** - Verify `isRunning` before sending commands
+2. **Use Appropriate Method** - `sendCommand()` for complete commands, `sendRawInput()` for interactive input
+3. **Handle Errors** - Wrap PTY operations in try-catch
+4. **Clean Up** - Dispose properly on unmount
+
+---
+
+### Command Execution
+
+1. **Test Commands** - Test commands manually before automation
+2. **Handle Output** - Parse output appropriately
+3. **Check Exit Codes** - Verify command success
+4. **Timeout Long Commands** - Set timeouts for long-running commands
+
+---
+
+### Performance
+
+1. **Limit Scrollback** - Keep scrollback buffer reasonable
+2. **Clear Regularly** - Clear terminal when not needed
+3. **Avoid Spam** - Don't send commands too rapidly
+4. **Monitor Memory** - Watch for memory leaks
+
+---
+
+## Related Documentation
+
+- [UI Guide](./UIGuide.md) - Main interface documentation
+- [Commands Reference](./Commands.md) - All slash commands
+- [Keyboard Shortcuts](./keybinds.md) - Keybind reference
+- [Tools System](../Tools/UserGuide.md) - Tool documentation
+
+---
+
+## External Resources
+
+- [xterm.js Documentation](https://xtermjs.org/)
+- [node-pty Documentation](https://github.com/microsoft/node-pty)
+- [ANSI Escape Codes](https://en.wikipedia.org/wiki/ANSI_escape_code)
+
+---
+
+**Last Updated:** January 26, 2026