Add TUI documentation (index + getting started) (#313)

* docs: add TUI documentation index page - Create docs/tui/ directory structure - Add comprehensive TUI overview and index page - Document TUI features: multi-terminal support, teams, parallel execution - Add comparison table: TUI vs CLI use cases - Include system requirements and supported terminals - Document keyboard shortcuts and commands reference - Add architecture overview and component structure - Include quick start guide and documentation navigation * docs: add TUI main interface screenshot - Add cai-tui-main.png screenshot to docs/media/ - Screenshot shows TUI interface for documentation * docs: add TUI getting started guide - Add comprehensive getting-started.md for TUI - Cover all 9 steps from launch to monitoring costs - Include prerequisites and system requirements - Document API key configuration process - Explain model and agent selection - Provide practical examples for first conversations - Document multi-terminal workflows - Explain team configurations - Add troubleshooting section for common issues - Include next steps and learning paths * docs: improve security and update model information in getting-started - Replace private IP 192.168.1.1 with documentation IP 198.51.100.50 (RFC 5737) - Add GPT-5 model to available models table - Add Claude 4-5 model to available models table - Update model descriptions for clarity - Ensure example IPs are safe for public documentation * docs: minimum change * docs: rename getting-started.md to getting_started.md for consistency - Rename docs/tui/getting-started.md to getting_started.md (underscore format) - Update all references in tui_index.md (3 occurrences) - Maintain consistency with other markdown files naming convention * docs: simplify TUI launch section in getting_started - Remove alternative launch methods for cleaner first steps - Remove 'Launch with Initial Prompt' section - Remove 'Launch with YAML Configuration' section - Focus on basic launch command for new users * docs: prepare TUI docs for PR by managing broken links - Replace broken documentation links with 🚧 indicators - Add explanatory notes about documentation in development - Convert inline links to plain text references - Keep existing links (getting_started.md, cai_installation.md, cai_architecture.md) - Maintain documentation structure for future expansion * docs: add CAI-Pro exclusive banner to TUI documentation
2025-10-27 12:05:16 +01:00 · 2025-10-27 12:05:16 +01:00 · 6498ade7da
parent 1bdc0522d7
commit 6498ade7da
3 changed files with 561 additions and 0 deletions
--- a/docs/media/cai-tui-main.png
+++ b/docs/media/cai-tui-main.png
--- a/docs/tui/getting_started.md
+++ b/docs/tui/getting_started.md
@ -0,0 +1,345 @@
 # Getting Started with CAI TUI
 > **⚡ CAI-Pro Exclusive Feature**  
 > The Terminal User Interface (TUI) is available exclusively in **CAI-Pro**. To access this feature and unlock advanced multi-agent workflows, visit [Alias Robotics](https://aliasrobotics.com) for more information.
 ---
 This guide will walk you through launching the CAI TUI for the first time and performing your first security assessment.
 ## Prerequisites
 Before starting, ensure you have:
 - ✅ CAI installed (see [Installation Guide](../cai_installation.md))
 - ✅ Python 3.9+ installed
 - ✅ A valid `ALIAS_API_KEY` from [Alias Robotics](https://aliasrobotics.com)
 ## Step 1: Launch the TUI
 Open your terminal and run:
 ```bash
 cai --tui
 ```
 If your `ALIAS_API_KEY` is not configured, you'll see an authentication error. Don't worry—we'll fix this in the next step.
 ## Step 2: Configure Your API Key
 The first time you use CAI TUI, you need to configure your API key:
 1. **Open the Sidebar**
   - Press `Ctrl+S` to toggle the sidebar (if not already visible)
 2. **Navigate to Keys Tab**
   - Click on the **"Keys"** tab in the sidebar
   - This shows all configured API keys
 3. **Add Your API Key**
   - Click the **"Add New Key"** button
   - A dialog will appear with two fields:
     - **Key Name**: Enter `ALIAS_API_KEY`
     - **Key Value**: Enter your API key (e.g., `ak_live_1234567890abcdef`)
 4. **Save the Key**
   - Click the **"Save"** button
   - Your key is now securely stored in `~/.cai/.env`
 ### Alternative: Using Environment Variables
 You can also set your API key via environment variable:
 ```bash
 export ALIAS_API_KEY="your_api_key_here"
 cai --tui
 ```
 Or create a `.env` file in your project directory:
 ```env
 ALIAS_API_KEY=your_api_key_here
 ```
 ## Step 3: Select Your Model
 CAI supports multiple AI models. For optimal performance and cost balance, we recommend `alias1`:
 ### Option 1: Using the Dropdown (Recommended)
 1. Look at the terminal header (top bar of each terminal)
 2. Find the **"model"** dropdown (center-right area)
 3. Click on it to see available models
 4. Select **`alias1`**
 ### Option 2: Using a Command
 Type in the input field at the bottom:
 ```
 /model alias1
 ```
 Press **Enter**.
 ### Available Models
 | Model | Provider | Best For | Cost |
 |-------|----------|----------|------|
 | `alias1` | Alias Robotics | **Recommended** - Balanced performance | Medium |
 | `gpt-5` | OpenAI | Latest reasoning and code generation | Very High |
 | `gpt-4o` | OpenAI | Complex reasoning and multi-modal | High |
 | `claude-4-5` | Anthropic | Advanced reasoning and long contexts | Very High |
 | `claude-3-5-sonnet-20241022` | Anthropic | Fast responses with good quality | High |
 > **💡 Tip**: You can change models at any time without losing your conversation history.
 ## Step 4: Choose Your Agent
 CAI comes with specialized agents for different security tasks. Here's how to choose:
 ### Option 1: Use the Agent Recommendation System
 The easiest way to start:
 1. Click the **agent** dropdown in the terminal header
 2. Select **`selection_agent`** 
 3. Type your task description: `"I need to test a web application for SQL injection"`
 4. The agent will recommend the best agent for your task
 Alternatively, use the command:
 ```
 /agent selection_agent
 ```
 Then describe your task.
 ### Option 2: Choose Directly from the Dropdown
 If you know which agent you need:
 1. Click the **agent** dropdown
 2. Browse available agents (scroll if needed)
 3. Select your desired agent (e.g., `redteam_agent`, `bug_bounter_agent`)
 ### Option 3: List All Agents
 To see all available agents with descriptions:
 ```
 /agent list
 ```
 ### Common Agent Types
 | Agent | Purpose | When to Use |
 |-------|---------|-------------|
 | `redteam_agent` | Offensive security testing | Default for penetration testing |
 | `blueteam_agent` | Defensive security analysis | Security posture assessment |
 | `bug_bounter_agent` | Bug bounty hunting | Finding high-value vulnerabilities |
 | `retester_agent` | Vulnerability retesting | Confirming fixes |
 | `selection_agent` | Agent recommendation | **When unsure which agent to use** |
 > **💡 Pro Tip**: Start with `selection_agent` if you're new to CAI—it will guide you to the right agent for your task.
 ## Step 5: Start Your First Conversation
 Now you're ready to interact with CAI!
 ### Example 1: Basic Reconnaissance
 In the input field at the bottom (marked with `CAI>`), type:
 ```
 Scan 198.51.100.50 for open ports and services
 ```
 Press **Enter**.
 The agent will:
 - Process your request
 - Use appropriate tools (nmap, etc.)
 - Display results in the terminal output area
 ### Example 2: Web Application Testing
 Prompt example:
 ```
 Test https://example.com for common web vulnerabilities
 ```
 Press **Enter**.
 The agent will:
 - Process your request
 - Use appropriate tools (nmap, etc.)
 - Display results in the terminal output area
 ### Example 3: Network Analysis
 Prompt example:
 ```
 Analyze the network traffic from this pcap file: capture.pcap
 ```
 ### Understanding the Output
 As the agent works, you'll see:
 1. **Tool Execution**: Messages showing which tools are being launched
 2. **Streaming Output**: Real-time results from tools
 3. **Agent Reasoning**: The agent's thought process (if `CAI_DEBUG=1`)
 4. **Final Response**: Summary and recommendations
 ### Queuing Prompts
 If the agent is busy, you can send another prompt—it will be **automatically queued**:
 - View the queue: Press `Ctrl+Shift+Q` or use `/queue`
 - The next prompt will execute when the current one finishes
 ## Step 6: Working with Multiple Terminals
 One of the TUI's most powerful features is multi-terminal support.
 ### Adding a New Terminal
 Click the **"Add +"** button in the top of the screen
 Each new terminal:
 - Starts with `alias1` model and `redteam_agent`
 - Has an independent conversation history
 - Can run a different agent and model
 ### Navigating Between Terminals
 - **Next terminal**: `Ctrl+N`
 - **Previous terminal**: `Ctrl+B`
 - **Click directly** on any terminal to focus it
 ### Example Workflow: Dual-Perspective Analysis
 1. **Terminal 1**: Keep `redteam_agent` for offensive testing
 2. **Terminal 2**: Add a new terminal, switch to `blueteam_agent`
 3. Send the same target to both:
   - T1: Offensive analysis
   - T2: Defensive recommendations
 4. Compare results side-by-side
 ## Step 7: Using Preconfigured Teams
 For common multi-agent workflows, use **Teams**:
 1. Open the sidebar (`Ctrl+S`)
 2. Click the **"Teams"** tab
 3. Select a team (e.g., **"#1: 2 red + 2 bug"**)
 This will:
 - Automatically open 4 terminals (or reuse existing ones)
 - Assign agents according to the team configuration
 - Ready to process your prompt in parallel
 **Popular Teams**:
 - **2 Red + 2 Bug**: Comprehensive penetration testing + bug hunting
 - **2 Red + 2 Blue**: Offensive + defensive analysis
 - **Red + Blue + Retester + Bug**: Full security assessment lifecycle
 Learn more about Teams and Parallel Execution in the full TUI documentation.
 ## Step 8: Saving Your Work
 To save your conversation for later:
 ```
 /save my-assessment.json
 ```
 Or in Markdown format:
 ```
 /save my-assessment.md
 ```
 Files are saved in your current working directory.
 ### Loading a Saved Session
 ```
 /load my-assessment.json
 ```
 This restores the conversation history for the current terminal.
 ## Step 9: Monitoring Costs
 CAI tracks your API usage and costs in real-time.
 ### View Costs for Current Agent
 ```
 /cost
 ```
 This shows:
 - Total tokens used (input + output)
 - Estimated cost in USD
 - Breakdown by interaction
 ### Check Stats in Sidebar
 Open the sidebar (`Ctrl+S`) and go to **"Stats"** tab to see:
 - Session duration
 - Total agents used
 - Total cost across all terminals
 ## Common First-Time Issues
 ### Issue: Agent is not responding
 **Solution**: 
 - Press `Ctrl+C` to cancel the current agent
 - Check your internet connection
 - Verify your API key is valid
 ### Issue: Terminal output is cluttered
 **Solution**:
 - Clear the terminal: `Ctrl+L` or `/clear`
 - Reduce debug output: Set `CAI_DEBUG=0` before launching
 - Use `/flush` to clear conversation history
 ### Issue: I can't see the full interface
 **Solution**:
 - Resize your terminal window to at least 120x40 characters
 - Try full-screen mode: `F11` (on most terminals)
 - Zoom out: `Ctrl+-` (on most terminals)
 ## Next Steps
 Congratulations! You've completed the basics of CAI TUI. Here's what to explore next:
 > **Note**: Additional TUI documentation is currently being developed. Topics marked with 🚧 will be available soon.
 ### Learn More Commands
 - 📖 Commands Reference 🚧 - Master all available commands
 - ⌨️ Keyboard Shortcuts 🚧 - Speed up your workflow
 ### Explore Advanced Features
 - 👥 Teams and Parallel Execution 🚧 - Multi-agent workflows
 - 🔧 MCP Integration 🚧 - Connect external tools
 - 💾 Session Management 🚧 - Advanced save/load
 ### Customize Your Setup
 - ⚙️ Configuration 🚧 - Environment variables and settings
 ### Get Help
 - ❓ FAQ 🚧 - Common questions
 - 🔧 Troubleshooting 🚧 - Solve issues
 - 💬 [Community Discord](https://discord.gg/aliasrobotics) - Ask questions
--- a/docs/tui/tui_index.md
+++ b/docs/tui/tui_index.md
@ -0,0 +1,216 @@
 # CAI Terminal User Interface (TUI)
 > **⚡ CAI-Pro Exclusive Feature**  
 > The Terminal User Interface (TUI) is available exclusively in **CAI-Pro**. To access this feature and unlock advanced multi-agent workflows, visit [Alias Robotics](https://aliasrobotics.com) for more information.
 ---
 The CAI TUI provides a modern, terminal-based interface for interacting with CAI agents, enabling powerful multi-agent workflows, parallel execution, and advanced security testing capabilities.
 ![CAI TUI Interface](../media/cai-tui-main.png)
 ## Overview
 The TUI is built on [Textual](https://textual.textualize.io/), offering:
 - **🖥️ Multi-Terminal Support**: Work with up to 4 agents simultaneously in split-screen layouts
 - **👥 Preconfigured Teams**: One-click deployment of specialized agent teams for security assessments
 - **⚡ Parallel Execution**: Execute multiple agents in parallel with independent conversations
 - **📊 Real-Time Stats**: Monitor costs, tokens, and agent performance
 - **🎯 Smart Agent Selection**: Built-in agent recommendation system
 - **🔧 MCP Integration**: Connect to external tools via Model Context Protocol
 - **💾 Session Management**: Save and restore conversations across sessions
 ## When to Use the TUI vs CLI
 | Feature | TUI | CLI |
 |---------|-----|-----|
 | **Visual feedback** | ✅ Rich UI with colors and layouts | ⚠️ Basic text output |
 | **Multi-agent workflows** | ✅ Visual split-screen | ❌ Sequential only |
 | **Agent teams** | ✅ One-click preconfigured teams | ❌ Manual setup |
 | **Real-time monitoring** | ✅ Stats sidebar | ⚠️ Limited |
 | **Session management** | ✅ Visual queue and history | ⚠️ Command-based |
 | **Scripting/Automation** | ❌ Interactive only | ✅ Full scripting support |
 | **Resource usage** | ⚠️ Higher (UI overhead) | ✅ Minimal |
 **Use TUI for**: Interactive security testing, bug bounty hunting, team-based analysis, exploratory testing
 **Use CLI for**: Automation, scripting, CI/CD integration, headless environments
 ## Quick Start
 Launch the TUI:
 ```bash
 cai --tui
 ```
 Basic workflow:
 1. Configure your `ALIAS_API_KEY` in **Sidebar → Keys**
 2. Select a model (recommended: `alias1`) from the terminal header dropdown
 3. Choose an agent or use `selection_agent` for recommendations
 4. Type your prompt and press **Enter**
 See the [Getting Started Guide](getting_started.md) for detailed instructions.
 ## System Requirements
 - **Python**: 3.9 or higher
 - **Terminal**: Modern terminal with 256+ color support
 - **Minimum window size**: 120x40 characters (recommended)
 - **API Key**: Valid `ALIAS_API_KEY` (get one from [Alias Robotics](https://aliasrobotics.com))
 ### Supported Terminals
 - ✅ iTerm2 (macOS)
 - ✅ Terminal.app (macOS)
 - ✅ GNOME Terminal (Linux)
 - ✅ Konsole (Linux)
 - ✅ Windows Terminal (Windows)
 - ✅ Alacritty (all platforms)
 - ⚠️ tmux/screen (limited color support)
 ## Key Features
 ### 🖥️ Multiple Terminals
 Work with multiple agents simultaneously in responsive layouts:
 - **1 terminal**: Full-screen mode
 - **2 terminals**: Horizontal split
 - **3 terminals**: 2+1 grid layout
 - **4+ terminals**: 2x2 grid with scroll
 Each terminal maintains its own:
 - Independent agent and model selection
 - Isolated conversation history
 - Separate execution context
 Learn more about terminal management in the full TUI documentation.
 ### 👥 Preconfigured Teams
 Access specialized agent teams from the sidebar:
 - **Team: 2 Red + 2 Bug**: Offensive testing + bug hunting
 - **Team: 2 Red + 2 Blue**: Dual-perspective security analysis
 - **Team: Red + Blue + Retester + Bug**: Comprehensive assessment workflow
 Learn more about Teams and Parallel Execution in the full TUI documentation.
 ### 🎯 Smart Agent Selection
 Use the `selection_agent` to get intelligent agent recommendations based on your task:
 ```
 /agent selection_agent
 ```
 Or simply select it from the agent dropdown.
 Learn more about commands in the full TUI documentation.
 ### 📊 Sidebar Features
 The collapsible sidebar (`Ctrl+S`) provides:
 - **Teams**: One-click team deployment
 - **Queue**: Visual prompt queue management
 - **Stats**: Real-time session statistics and costs
 - **Keys**: Manage API keys for multiple providers
 Learn more about sidebar features in the full TUI documentation.
 ## Documentation Structure
 > **Note**: TUI documentation is being actively developed. Topics marked with 🚧 are coming soon.
 ### For New Users
 1. [Getting Started](getting_started.md) ✅ - First steps and basic usage
 2. User Interface 🚧 - Understanding the layout
 3. Keyboard Shortcuts 🚧 - Essential shortcuts
 ### For Regular Users
 4. Commands Reference 🚧 - Complete command list
 5. Terminals Management 🚧 - Working with multiple terminals
 6. Sidebar Features 🚧 - Sidebar tabs and capabilities
 ### For Advanced Users
 7. Teams and Parallel Execution 🚧 - Multi-agent workflows
 8. Configuration 🚧 - Environment variables and settings
 9. Advanced Features 🚧 - MCP, Meta Agent, and more
 ### Support Resources
 10. Troubleshooting 🚧 - Common issues and solutions
 11. FAQ 🚧 - Frequently asked questions
 ## Quick Reference
 ### Essential Keyboard Shortcuts
 | Shortcut | Action |
 |----------|--------|
 | `Ctrl+S` | Toggle sidebar |
 | `Ctrl+L` | Clear all terminals |
 | `Ctrl+Q` | Exit CAI |
 | `Ctrl+N` / `Ctrl+B` | Navigate terminals |
 | `Ctrl+C` | Cancel current agent |
 | `ESC` | Cancel all agents |
 See complete keyboard shortcuts reference in the full TUI documentation (coming soon).
 ### Most Used Commands
 | Command | Description |
 |---------|-------------|
 | `/help` | Show help |
 | `/agent list` | List all agents |
 | `/agent <name>` | Switch agent |
 | `/model <name>` | Change model |
 | `/queue` | Show prompt queue |
 | `/cost` | Show costs and tokens |
 | `/save <file>` | Save conversation |
 | `/load <file>` | Load conversation |
 See complete commands reference in the full TUI documentation (coming soon).
 ## Architecture
 ```
 CAI TUI
 ├── Core Components
 │   ├── SessionManager - Coordinates all terminals
 │   ├── TerminalRunner - Manages agent execution per terminal
 │   └── AgentExecutor - Handles parallel execution
 ├── UI Components
 │   ├── UniversalTerminal - Individual terminal widget
 │   ├── StableTerminalGrid - Layout manager
 │   ├── Sidebar - Navigation and features
 │   └── InfoStatusBar - Real-time status display
 └── Display System
    ├── DisplayManager - Output routing
    ├── StreamingDisplay - Real-time streaming
    └── AgentDisplay - Agent message formatting
 ```
 For technical details, see the [Architecture Overview](../cai_architecture.md).
 ## Community and Support
 - **Documentation**: [https://docs.aliasrobotics.com](https://docs.aliasrobotics.com)
 - **GitHub Issues**: [https://github.com/aliasrobotics/cai/issues](https://github.com/aliasrobotics/cai/issues)
 - **Discord**: [Join our community](https://discord.gg/aliasrobotics)
 - **Twitter**: [@aliasrobotics](https://twitter.com/aliasrobotics)
 ## What's Next?
 - 📖 [Getting Started Guide](getting_started.md) ✅ - Learn the basics
 - ⌨️ Keyboard Shortcuts 🚧 - Boost your productivity
 - 🎯 Commands Reference 🚧 - Master the commands
 - 👥 Teams and Parallel Execution 🚧 - Advanced workflows
 ---
 *Last updated: October 2025 | CAI TUI v0.6+*