# Kollabor Features

Comprehensive catalog of all Kollabor CLI features, capabilities, and functionality.

## Table of Contents

- [Core Features](#core-features)
- [LLM Features](#llm-features)
- [Terminal UI Features](#terminal-ui-features)
- [Plugin System](#plugin-system)
- [Slash Commands](#slash-commands)
- [Configuration & Environment](#configuration--environment)
- [Developer Features](#developer-features)
- [Advanced Features](#advanced-features)

---

## Core Features

### Interactive Mode

Full-featured terminal-based chat interface for conversing with LLMs.

**Features:**
- Real-time streaming responses
- Multi-line input with visual input box
- Conversation history with scrollback
- Three-area status display (A, B, C)
- Thinking animations during LLM processing
- Persistent conversation logging

**Usage:**
```bash
kollab
```

### Pipe Mode

Non-interactive mode for scripting and automation.

**Features:**
- Process single query and exit
- Read from stdin or command arguments
- Configurable timeout
- Full plugin support
- Automatic waiting for LLM and tool completion
- Suppresses interactive UI (status bar, cursor, exit messages)

**Usage:**
```bash
# Direct query
kollab "What is the capital of France?"

# From stdin
echo "Explain quantum computing" | kollab -p

# From file with timeout
cat document.txt | kollab -p --timeout 5min
```

**Plugin Detection:**
Plugins can check `app.pipe_mode` flag to adjust behavior for non-interactive mode.

---

## LLM Features

### Conversation Management

Persistent conversation history with full state management.

**Features:**
- JSONL-based conversation logs (`~/.kollabor-cli/projects/<path>/conversations/`)
- Raw API conversation logs (`conversations/raw/`)
- Intelligence cache for patterns and context (`conversations/memory/`)
- Conversation snapshots (`conversations/snapshots/`)
- Automatic conversation resumption
- Branch management for conversation exploration

**Related Files:**
- `kollabor/llm/conversation_logger.py` - KollaborConversationLogger
- `kollabor/llm/conversation_manager.py` - Conversation state and history

### Tool Execution

Function calling and tool execution capabilities.

**Features:**
- Automatic tool discovery and registration
- Tool result processing
- Error handling and retry logic
- Tool execution suspended during Question Gate (see below)

**Related Files:**
- `kollabor/llm/tool_executor.py` - Tool execution orchestration

### Question Gate Protocol

Suspends tool execution when the agent asks clarifying questions using `<question>` tags.

**Features:**
- Detects `<question>...</question>` tags in responses
- Suspends pending tool calls
- User responds to question
- Tools execute on next input with full context
- Prevents runaway investigation loops

**Configuration:**
```json
{
  "kollabor.llm.question_gate_enabled": true
}
```

**Documentation:** [docs/features/question-gate-protocol.md](docs/features/question-gate-protocol.md)

**Related Files:**
- `kollabor/llm/response_parser.py` - Question gate detection
- `kollabor/llm/llm_service.py` - Pending tool queue management

### Model Context Protocol (MCP)

Built-in support for Model Context Protocol server integration.

**Features:**
- MCP server discovery
- Resource integration
- Tool provider integration

**Related Files:**
- `kollabor/llm/mcp_integration.py` - MCP integration service

### Profile Management

Manage multiple LLM API configurations and switch between them.

**Features:**
- Multiple API profile support
- Profile switching via `/profile` command
- Environment variable overrides
- Model selection modal
- Profile creation UI

**Commands:**
- `/profile` - Show profile selection modal
- `/profile list` - Show profile selection modal
- `/profile set <name>` - Switch to specified profile
- `/profile create` - Open create profile form
- `/model` - Quick model selector
- `/model list` - Show model selection modal
- `/model set <name>` - Switch to profile with specified model

**Related Files:**
- `kollabor/llm/profile_manager.py` - Profile management
- `kollabor/commands/system_commands.py` - Profile commands

### Agent & Skill System

Dynamic agent definitions and skill loading for specialized LLM behavior.

**Features:**
- Agent discovery from `~/.kollabor-cli/agents/` (global) and `.kollabor-cli/agents/` (local)
- Skill loading/unloading
- Agent creation UI
- Skill management modal

**Agent Resolution:**
1. Local `.kollabor-cli/agents/<name>/` (project-specific, highest priority)
2. Global `~/.kollabor-cli/agents/<name>/` (user defaults)

**Commands:**
- `/agent` - Show agent selection modal
- `/agent list` - Show agent selection modal
- `/agent set <name>` - Switch to specified agent
- `/agent create` - Open create agent form
- `/agent clear` - Clear active agent
- `/skill` - Show skill selection modal
- `/skill list` - Show skill selection modal
- `/skill load <name>` - Load specified skill
- `/skill unload <name>` - Unload specified skill
- `/skill create` - Open create skill form

**Related Files:**
- `kollabor/llm/agent_manager.py` - Agent and skill management

### Dynamic System Prompts

System prompts with runtime content rendering using `<trender>` tags.

**Features:**
- Dynamic content injection at runtime
- Project structure rendering
- File content inclusion
- Timestamp injection
- Pattern-based file listings

**Available Tags:**
```markdown
<!-- Project structure -->
<trender type="project_tree" />
<trender type="project_tree" max_depth="3" />

<!-- File listings -->
<trender type="file_list" pattern="**/*.py" />
<trender type="file_list" pattern="kollabor/**/*.py" exclude="__pycache__" />

<!-- File contents -->
<trender type="file_content" path="README.md" />
<trender type="file_content" path="ARCHITECTURE.md" />

<!-- Metadata -->
<trender type="timestamp" />
<trender type="timestamp" format="%Y-%m-%d %H:%M:%S" />
```

**Priority Order:**
1. `KOLLABOR_SYSTEM_PROMPT` env var (direct string)
2. `KOLLABOR_SYSTEM_PROMPT_FILE` env var (file path)
3. Local `.kollabor-cli/system_prompt/default.md`
4. Global `~/.kollabor-cli/system_prompt/default.md`
5. Built-in fallback

**Documentation:** [docs/features/dynamic-system-prompts.md](docs/features/dynamic-system-prompts.md)

**Related Files:**
- `kollabor/utils/prompt_renderer.py` - Dynamic rendering engine

---

## Terminal UI Features

### Status Display System

Widget-based status rendering with adaptive layout and flexible registry.

**Features:**
- Widget registry for pluggable status components
- Adaptive layout (3-column wide terminals, stacked narrow terminals)
- Real-time widget updates
- Interactive widgets (command, toggle, inline_edit, action)
- Per-widget width configuration (auto, relative %, fixed chars)
- Core and plugin widget categories

**Layout Behavior:**
- **Wide terminals (≥80 chars)**: Three-column layout with widgets side-by-side
- **Narrow terminals (<80 chars)**: Vertical stacked layout

**Widget System:**
- Widgets registered via `StatusWidgetRegistry`
- Each widget has: render function, category, width spec, interaction type
- Built-in widgets: directory, profile, model, agent, skills, stats
- Plugins can register custom widgets

**Related Files:**
- `kollabor/io/status/widget_registry.py` - StatusWidgetRegistry and widget definitions
- `kollabor/io/status/core_widgets.py` - Core widget implementations
- `kollabor/io/layout.py` - Adaptive layout manager (_layout_status_areas)

### Widget Status System

Interactive status widgets with full keyboard navigation and state management.

**Features:**
- Multiple widget types (checkbox, dropdown, slider, text input, progress, etc.)
- Keyboard navigation (Tab to enter, arrows to navigate, Enter to activate)
- Visual state indicators
- Real-time updates
- Modern design system styling

**Available Widgets:**
- `CheckboxWidget` - Boolean toggles
- `DropdownWidget` - Single selection from list
- `MultiSelectWidget` - Multiple selections
- `SliderWidget` - Numeric value adjustment
- `TextInputWidget` - Text entry
- `TextAreaWidget` - Multi-line text
- `ProgressWidget` - Progress bars
- `SpinBoxWidget` - Numeric spinners
- `LabelWidget` - Static labels
- `TreeView` - Hierarchical data display
- `FileBrowser` - File system navigation
- `SearchableDropdown` - Filterable dropdown

**Documentation:** [docs/features/widget-status-system.md](docs/features/widget-status-system.md)

**Related Files:**
- `kollabor/ui/widgets/` - Widget implementations

### Visual Effects

Terminal color support and visual effects engine.

**Features:**
- Automatic color capability detection (24-bit, 256-color, 16-color, none)
- Manual color mode override via `KOLLABOR_COLOR_MODE`
- Gradient rendering
- Color palette system
- Matrix rain effect (fullscreen)

**Color Modes:**
- **TRUE_COLOR (24-bit)**: Full RGB colors (16 million colors)
- **EXTENDED (256-color)**: 256-color palette fallback
- **BASIC (16-color)**: Basic ANSI colors
- **NONE**: No colors (monochrome)

**Auto-detection:**
Checks `COLORTERM`, `TERM_PROGRAM`, and `TERM` environment variables.

**Override:**
```bash
KOLLABOR_COLOR_MODE=256 kollab        # Force 256-color
KOLLABOR_COLOR_MODE=truecolor kollab  # Force true color
KOLLABOR_COLOR_MODE=none kollab       # Disable colors
```

**Related Files:**
- `kollabor/io/visual_effects.py` - Color support and effects

### Design System

Consistent theming and UI components for all terminal rendering.

**Features:**
- Centralized theme management
- Color palette access via `T()`
- Style constants (`S.BOLD`, `S.DIM`, etc.)
- Box rendering with solid blocks (▄▀)
- TagBox pattern (tag + content)
- Modern widget styling

**Core Imports:**
```python
from kollabor.ui.design_system import T, S, C, Box, TagBox, solid, solid_fg, gradient
```

**Theme Colors:**
- `T().primary` - Primary accent color (gradient)
- `T().dark` - Dark background colors (gradient)
- `T().text` - Main text color
- `T().text_dim` - Dimmed text color
- `T().success`, `T().error`, `T().warning` - Status colors

**Related Files:**
- `kollabor/ui/design_system/` - Design system components

### Modal System

Full-screen modal overlays with widget support.

**Features:**
- Fullscreen modal overlays
- Widget integration (dropdowns, checkboxes, sliders, text inputs)
- Keyboard navigation
- ANSI alternate buffer support
- Proper render state management

**Modal Pattern:**
```python
async def _show_modal(self) -> bool:
    # 1. Pause render loop
    self.coordinator.enter_alternate_buffer()

    try:
        # 2. Enter ANSI alternate buffer
        sys.stdout.write('\033[?1049h')

        # 3. Render modal and handle input
        # ...

    finally:
        # 4. Exit alternate buffer
        sys.stdout.write('\033[?1049l')

        # 5. Restore render state
        self.coordinator.exit_alternate_buffer(restore_state=True)
```

**Related Files:**
- `kollabor/ui/modals/` - Modal implementations
- `kollabor/io/message_coordinator.py` - Render state coordination

### Fullscreen Plugin System

Framework for fullscreen interactive applications.

**Features:**
- Fullscreen rendering with frame-based updates
- Keyboard input handling
- Terminal size management
- Animation support
- Command integration

**Documentation:** [docs/reference/fullscreen-plugin-system.md](docs/reference/fullscreen-plugin-system.md)

**Related Files:**
- `kollabor/fullscreen/` - Fullscreen plugin framework

### Message Display Coordination

Centralized message flow and render state coordination (CRITICAL).

**Features:**
- Message queue management
- Render state coordination
- Buffer transition handling
- Flag-based synchronization
- Prevents duplicate input boxes and stale renders

**CRITICAL Methods:**
```python
# Display messages
renderer.message_coordinator.display_message_sequence([...])

# Modal/fullscreen transitions
renderer.message_coordinator.enter_alternate_buffer()  # Before modal
renderer.message_coordinator.exit_alternate_buffer()   # After modal (clean state)
renderer.message_coordinator.exit_alternate_buffer(restore_state=True)  # Restore state

# Debugging
renderer.message_coordinator.get_queue_status()
```

**Related Files:**
- `kollabor/io/message_coordinator.py` - Message display coordinator

### Terminal State Management

Global terminal state management for consistent dimension access.

**Features:**
- Centralized terminal size tracking
- Automatic resize detection
- Global singleton pattern
- Convenience functions for all components

**Usage:**
```python
from kollabor.io.terminal_state import get_terminal_size, get_terminal_width, get_terminal_height

# Get dimensions
width, height = get_terminal_size()
width = get_terminal_width()
height = get_terminal_height()
```

**Related Files:**
- `kollabor/io/terminal_state.py` - Global terminal state

### Ready Message System

Visual indicator when the system is ready for input after processing.

**Features:**
- Customizable ready messages
- Automatic display after LLM responses
- Plugin-controlled behavior
- First-run help integration

**Documentation:** [docs/features/ready-message-system.md](docs/features/ready-message-system.md)

---

## Plugin System

### Core Architecture

Dynamic plugin discovery and loading with comprehensive SDK.

**Features:**
- Auto-discovery from `plugins/` directory
- Dynamic instantiation with dependency injection
- Hook registration for event interception
- Configuration merging
- Lifecycle management (initialize, register_hooks, shutdown)

**Plugin Discovery Locations:**
1. Package installation: `<package_root>/plugins/` (pip install)
2. Development mode: `./plugins/` (from source)

**Base Classes:**
- `BasePlugin` - Standard plugin base
- `FullscreenPlugin` - Fullscreen interactive plugins
- `StatusPlugin` - Status area plugins

**Related Files:**
- `kollabor/plugins/` - Plugin system framework
- `plugins/` - Plugin implementations

### Plugin SDK

Comprehensive SDK for plugin development.

**Features:**
- Helper methods for common tasks
- Event bus access
- Configuration access
- Renderer access
- LLM service integration

**Related Files:**
- `kollabor/llm/plugin_sdk.py` - KollaborPluginSDK

### Built-in Plugins

#### Modern Input Plugin

Enhanced input handling with keyboard shortcuts.

**Features:**
- Arrow key navigation
- Input history
- Keyboard shortcuts

**Related Files:**
- `plugins/modern_input_plugin.py`

#### Save Conversation Plugin

Save conversations in multiple formats.

**Features:**
- Multiple export formats (transcript, markdown, JSONL)
- Save to file or clipboard
- Local save option

**Commands:**
- `/save` - Save conversation modal
- `/save transcript` - Save as transcript
- `/save markdown` - Save as markdown
- `/save jsonl` - Save as JSONL
- `/save clipboard` - Save to clipboard
- `/save both` - Save to both file and clipboard
- `/save local` - Save to local directory

**Related Files:**
- `plugins/save_conversation_plugin.py`

#### Resume Conversation Plugin

Session management and conversation branching.

**Features:**
- Resume previous conversations
- Branch management for exploration
- Conversation search
- Session switching

**Commands:**
- `/resume` - Resume conversation modal
- `/search` - Search conversations
- `/branch` - Manage conversation branches

**Documentation:** [docs/features/RESUME_COMMAND_SPEC.md](docs/features/RESUME_COMMAND_SPEC.md)

**Related Files:**
- `plugins/resume_conversation_plugin.py`
- `docs/plugins/kollabor/resume_conversation_plugin_spec.md`

#### Tmux Plugin

Manage tmux sessions with live modal viewing.

**Features:**
- Create new tmux sessions
- View session output in modal
- List all sessions
- Kill sessions
- Attach to sessions

**Commands:**
- `/terminal` (aliases: `/tmux`, `/term`, `/t`)
- `/terminal new <name> <cmd>` - Create new session
- `/terminal view [name]` - View session output
- `/terminal list` - List all sessions
- `/terminal kill <name>` - Kill session
- `/terminal attach <name>` - Attach to session

**Related Files:**
- `plugins/tmux_plugin.py`

#### Hook Monitoring Plugin

Monitor and debug the hook system.

**Features:**
- Hook execution monitoring
- Performance tracking
- Event flow visualization

**Related Files:**
- `plugins/hook_monitoring_plugin.py`

#### Agent Orchestrator Plugin

Multi-agent coordination and orchestration.

**Features:**
- Spawn sub-agents for parallel work
- Agent coordination
- Task distribution

**Commands:**
- `/subagent` - Manage sub-agents

**Related Files:**
- `plugins/agent_orchestrator/` - Agent orchestrator plugin

---

## Slash Commands

Extensible command system with menu-based discovery and subcommand support.

### System Commands

**`/help`** (aliases: `/h`, `/?`)
- Show available commands and usage
- Category: SYSTEM
- Mode: INSTANT

**`/version`** (aliases: `/v`, `/ver`)
- Show application version information
- Category: SYSTEM
- Mode: INSTANT

**`/config`** (aliases: `/settings`, `/preferences`)
- Open system configuration panel
- Category: SYSTEM
- Mode: STATUS_TAKEOVER
- UI: Tree view with navigation

**`/status`** (aliases: `/info`, `/diagnostics`)
- Show system status and diagnostics
- Category: SYSTEM
- Mode: STATUS_TAKEOVER
- UI: Table view

**`/permissions`** (aliases: `/perms`, `/security`)
- Manage tool execution permissions
- Category: SYSTEM
- Mode: INLINE_INPUT
- Subcommands:
  - `show` - Show current permission settings
  - `default` - Use DEFAULT mode (HIGH risk only)
  - `strict` - Use CONFIRM_ALL mode (prompt everything)
  - `trust` - Use TRUST_ALL mode (approve everything)
  - `stats` - Show permission statistics
  - `clear` - Clear session approvals

**`/cd`** (aliases: `/chdir`, `/dir`)
- Change working directory
- Category: SYSTEM
- Mode: STATUS_TAKEOVER
- Subcommands:
  - `<path>` - Change to specified directory
  - `..` - Go to parent directory
  - `-` - Go to previous directory

**`/widgets`** (aliases: `/showcase`, `/widget-showcase`, `/storybook`)
- Interactive widget gallery (terminal Storybook)
- Category: UI
- Mode: STATUS_TAKEOVER

### LLM Commands

**`/profile`** (aliases: `/prof`, `/llm`)
- Manage LLM API profiles
- Category: SYSTEM
- Mode: STATUS_TAKEOVER
- Subcommands:
  - `list` - Show profile selection modal
  - `set <name>` - Switch to specified profile
  - `create` - Open create profile form

**`/model`** (aliases: `/mod`, `/m`)
- Quick model selector
- Category: SYSTEM
- Mode: STATUS_TAKEOVER
- Subcommands:
  - `list` - Show model selection modal
  - `set <name>` - Switch to profile with specified model

**`/agent`** (aliases: `/ag`)
- Manage agents and their configurations
- Category: AGENT
- Mode: STATUS_TAKEOVER
- Subcommands:
  - `list` - Show agent selection modal
  - `set <name>` - Switch to specified agent
  - `create` - Open create agent form
  - `clear` - Clear active agent

**`/skill`** (aliases: `/sk`)
- Load or unload agent skills
- Category: AGENT
- Mode: STATUS_TAKEOVER
- Subcommands:
  - `list` - Show skill selection modal
  - `load <name>` - Load specified skill
  - `unload <name>` - Unload specified skill
  - `create` - Open create skill form

**`/mcp`** (aliases: `/mcps`, `/servers`)
- Manage MCP (Model Context Protocol) servers
- Category: SYSTEM
- Mode: INSTANT
- Subcommands:
  - `setup` - Run MCP setup wizard
  - `list` - List configured servers
  - `test <server>` - Test server connection
  - `enable <server>` - Enable a server
  - `disable <server>` - Disable a server
  - `show` - Show server details
  - `tools [server]` - List available tools

### Conversation Commands

**`/save`** (aliases: `/export`, `/transcript`)
- Save conversation to file or clipboard
- Category: CONVERSATION
- Mode: INSTANT
- Subcommands:
  - `transcript` - Save as transcript
  - `markdown` - Save as markdown
  - `jsonl` - Save as JSONL
  - `clipboard` - Save to clipboard
  - `both` - Save to both file and clipboard
  - `local` - Save to local directory

**`/resume`** (aliases: `/restore`, `/continue`)
- Resume previous conversation
- Category: CONVERSATION
- Mode: STATUS_TAKEOVER

**`/sessions`** (aliases: `/history`, `/conversations`)
- Search and browse conversation sessions
- Category: CONVERSATION
- Mode: STATUS_TAKEOVER

**`/branch`**
- Branch conversation from a specific message
- Category: CONVERSATION
- Mode: STATUS_TAKEOVER

### Terminal Commands

**`/terminal`** (aliases: `/tmux`, `/term`, `/t`)
- Manage tmux sessions
- Category: CUSTOM
- Mode: INSTANT
- Subcommands:
  - `new <name> <cmd>` - Create new tmux session
  - `view [name]` - View session output in modal
  - `list` - List all tmux sessions
  - `kill <name>` - Kill tmux session
  - `attach <name>` - Attach to tmux session

### Agent Orchestrator Commands

**`/sub`** (aliases: `/subagent`, `/sa`)
- Manage parallel agent sessions
- Category: CUSTOM
- Mode: INSTANT
- Subcommands:
  - `list` - List all active agents
  - `status [name]` - Get status of agent(s)
  - `create <name> <task>` - Create new agent with task
  - `capture <name|all> [lines]` - Capture output from agent(s)
  - `stop <name|all>` - Stop agent(s)
  - `message <name> <msg>` - Send message to agent

### Fullscreen Commands

**`/matrix`**
- Enter the Matrix with falling code rain effect
- Category: EFFECTS
- Mode: FULLSCREEN

**`/space`** (aliases: `/shooter`, `/galaga`, `/arcade`)
- 80s arcade space shooter demo
- Category: EFFECTS
- Mode: FULLSCREEN

**`/status-setup`** (aliases: `/status-config`, `/status-edit`)
- Configure status area layout
- Category: SYSTEM
- Mode: FULLSCREEN

**`/example`** (aliases: `/demo`, `/showcase`)
- Comprehensive framework showcase with interactive pages
- Category: DEMO
- Mode: FULLSCREEN

### Command System Features

**Menu Behavior:**
- Triggered by typing `/` in input
- Filters commands as you type with prefix matching
- Arrow keys navigate, Enter executes
- Prioritizes name matches over alias matches
- Subcommands appear when filtered to single command
- No-arg subcommands execute immediately
- Arg subcommands insert text for completion

**Plugin Registration:**
```python
from kollabor.events.models import CommandDefinition, CommandCategory, SubcommandInfo

command_def = CommandDefinition(
    name="mycommand",
    description="My custom command",
    category=CommandCategory.CUSTOM,
    aliases=["mc", "mycmd"],
    handler=my_handler_function,
    subcommands=[
        SubcommandInfo("action1", "", "Execute action 1"),
        SubcommandInfo("action2", "<arg>", "Execute action 2 with argument"),
    ]
)
command_registry.register_command(command_def)
```

**Related Files:**
- `kollabor/commands/` - Command system implementation

---

## Configuration & Environment

### Configuration System

Flexible configuration management with dot notation.

**Features:**
- Dot notation access (e.g., `config.get("kollabor.llm.max_history", 90)`)
- Plugin configuration merging
- JSON-based storage
- Environment variable overrides

**Configuration Directories:**
- **Global**: `~/.kollabor-cli/config.json` - User configuration
- **Project**: `~/.kollabor-cli/projects/<encoded-path>/` - Project-specific data
  - `conversations/` - Conversation logs (JSONL)
  - `conversations/raw/` - Raw API logs
  - `conversations/memory/` - Intelligence cache
  - `conversations/snapshots/` - Conversation snapshots
  - `logs/` - Application logs
- **Local** (optional): `.kollabor-cli/` - Project-specific agents/skills

**Configuration Namespaces:**
- `kollabor.llm.*` - LLM service settings
- `terminal.*` - Terminal rendering options
- `application.*` - Application metadata
- `kollabor.llm.question_gate_enabled` - Question Gate toggle

**Related Files:**
- `kollabor/config/` - Configuration management
- `kollabor/utils/config_utils.py` - Config utilities and project data system

### Environment Variables

Complete configuration via environment variables with precedence over config files.

#### API Configuration

```bash
KOLLABOR_API_ENDPOINT=https://api.example.com/v1/chat/completions
KOLLABOR_API_TOKEN=your-api-token-here        # or KOLLABOR_API_KEY
KOLLABOR_API_MODEL=gpt-4
KOLLABOR_API_MAX_TOKENS=4096
KOLLABOR_API_TEMPERATURE=0.7
KOLLABOR_API_TIMEOUT=30000
```

#### System Prompt Configuration

```bash
# Direct string (highest priority)
KOLLABOR_SYSTEM_PROMPT="You are a helpful coding assistant."

# Custom file path
KOLLABOR_SYSTEM_PROMPT_FILE="./my_custom_prompt.md"
```

#### Color Configuration

```bash
KOLLABOR_COLOR_MODE=256        # Force 256-color mode
KOLLABOR_COLOR_MODE=truecolor  # Force true color
KOLLABOR_COLOR_MODE=none       # Disable colors
```

#### Using .env Files

```bash
# Create .env file
cat > .env <<EOF
KOLLABOR_API_ENDPOINT=https://api.example.com/v1/chat/completions
KOLLABOR_API_TOKEN=your-token-here
KOLLABOR_API_MODEL=gpt-4
KOLLABOR_SYSTEM_PROMPT_FILE="./prompts/specialized.md"
EOF

# Load and run
export $(cat .env | xargs)
kollab
```

**Documentation:** [ENV_VARS.md](ENV_VARS.md)

**Related Files:**
- `docs/specs/dynamic-profile-env-variables-spec.md`

---

## Developer Features

### Hook System

Comprehensive event-driven hook system for plugins.

**Features:**
- Event bus architecture
- Priority-based hook execution (CRITICAL, HIGH, NORMAL, LOW)
- Hook registry with event type lookup
- Error handling and isolation
- Context passing through hook chain

**Available Events:**
- `pre_user_input` - Before processing user input
- `pre_api_request` - Before API calls to LLM
- `post_api_response` - After receiving LLM responses
- `pre_message_display` - Before displaying messages
- `post_message_display` - After displaying messages
- Many more...

**Hook Registration:**
```python
self.event_bus.register_hook(
    EventType.PRE_USER_INPUT,
    self.on_user_input,
    priority=HookPriority.NORMAL
)
```

**Architecture:**
- **HookRegistry** (`kollabor/events/registry.py`) - Hook registration and lookup
- **HookExecutor** (`kollabor/events/executor.py`) - Hook execution with error handling
- **EventProcessor** (`kollabor/events/processor.py`) - Event processing through hooks
- **EventBus** (`kollabor/events/bus.py`) - Central coordinator

**Related Files:**
- `kollabor/events/` - Event system and hook architecture

### Testing System

Comprehensive test suite with multiple test types.

**Test Types:**
- Unit tests (`tests/unit/`) - Individual component tests
- Integration tests (`tests/integration/`) - Cross-component tests
- Visual tests (`tests/visual/`) - Terminal rendering tests
- Tmux tests (`tests/tmux/`) - Automated UI bug reproduction

**Running Tests:**
```bash
# All tests
python tests/run_tests.py

# Specific test file
python -m unittest tests.test_llm_plugin

# Individual test case
python -m unittest tests.test_llm_plugin.TestLLMPlugin.test_thinking_tags_removal
```

**Tmux Testing:**
Used for automated UI bug reproduction and verification.

**Template:**
```bash
cp tests/tmux/templates/spec_verification_template.sh \
   tests/tmux/verify_[feature-name].sh
chmod +x tests/tmux/verify_[feature-name].sh
```

**Dynamic Socket Names (CRITICAL for parallel testing):**
```bash
SOCKET_NAME="kollabor-$$"
SESSION_NAME="verify-feature-$$"
tmux -L "$SOCKET_NAME" new-session -d -s "$SESSION_NAME" "python main.py"
```

**Related Files:**
- `tests/` - Test suite
- `known_issues/templates/tmux_testing_guide.md` - Tmux testing guide

### Known Issues Tracking

Structured issue tracking system for documenting bugs and preventing regressions.

**Directory Structure:**
```
known_issues/
├── README.md              # Complete tracking guide
├── QUICK_START.md         # Quick reference
├── active/                # Issues needing fixes
├── in_progress/           # Issues being worked on
├── resolved/              # Fixed issues (with details)
├── wont_fix/              # Issues not being addressed
├── duplicate/             # Duplicate issue references
└── templates/
    ├── issue_template.md          # Standard issue format
    ├── test_script_template.sh    # Tmux test template
    └── tmux_testing_guide.md      # Testing guide
```

**Workflow:**
```bash
# 1. Create issue
cp known_issues/templates/issue_template.md \
   known_issues/active/2026-01-17-issue-name.md

# 2. Create tmux test
cp known_issues/templates/test_script_template.sh \
   tests/tmux/test_issue_name.sh

# 3. Work on issue: active -> in_progress
mv known_issues/active/issue.md known_issues/in_progress/

# 4. Mark resolved: in_progress -> resolved
mv known_issues/in_progress/issue.md known_issues/resolved/
```

**Related Files:**
- `known_issues/` - Issue tracking system

### Git Workflow

Strict issue-tracking workflow enforced via git hooks.

**Pre-commit Requirements:**
- All commits to `kollabor/`, `plugins/`, or `tests/` must reference a GitHub issue
- Branch naming: `issue-123-description` or `feature/issue-123-description`
- Commit messages must include: `fixes #123`, `closes #123`, `resolves #123`, or `#123`

**Pre-push Protection:**
- Blocks direct pushes to `main` branch
- Requires pull request workflow
- Emergency hotfixes use `hotfix/issue-123-description` branches

**Workflow:**
```bash
# 1. Create issue on GitHub
gh issue create --title "Fix version display"

# 2. Create branch with issue number
git checkout -b issue-8-version-display-fix

# 3. Commit with issue reference
git commit -m "Fix version display in development mode fixes #8"

# 4. Push to remote
git push -u kollaborai issue-8-version-display-fix

# 5. Create pull request
gh pr create --title "Fix version display" --body "Fixes #8"
```

**Related Files:**
- `.github/scripts/` - Git hooks and automation

### Logging System

Comprehensive logging with daily rotation.

**Features:**
- Project-specific log files (`~/.kollabor-cli/projects/<path>/logs/kollabor.log`)
- Daily rotation
- Configurable log levels
- Module-based loggers

**Usage:**
```python
import logging
logger = logging.getLogger(__name__)
logger.info("Message here")
```

**Related Files:**
- `kollabor/logging/` - Logging configuration

### Version Management

Centralized version management from `pyproject.toml`.

**Features:**
- Single source of truth in `pyproject.toml`
- Automatic detection of dev vs production mode
- Development mode reads from file
- Production mode uses package metadata

**Files Reading Version:**
- `kollabor/application.py` - Banner display
- `kollabor/cli.py` - CLI version flag
- `kollabor/config/loader.py` - Config version metadata

**Update Version:**
```bash
# Edit pyproject.toml only - all files read from it automatically
vim pyproject.toml
```

---

## Advanced Features

### Tool Permission System

Comprehensive approval and permission system for controlling tool execution with inline UI prompts.

**Features:**
- **4 Approval Modes:**
  - `CONFIRM_ALL` - Require confirmation for all tool executions (default)
  - `DEFAULT` - Confirm HIGH risk tools only (shell commands with dangerous patterns)
  - `AUTO_APPROVE_EDITS` - Auto-approve file operations, confirm shell commands
  - `TRUST_ALL` - Auto-approve everything (dangerous, use with caution)
- **Risk Assessment:**
  - Pattern-based detection for dangerous shell commands (rm -rf, curl | bash, etc.)
  - Tool type classification (terminal, file_create, file_edit, mcp_tool)
  - Configurable trusted and blocked tool lists
- **Inline Permission Prompts:**
  - Appears in thinking/executing area using Box() design system style
  - Single keypress responses (a/s/d/c/t/A)
  - Color-coded risk levels (HIGH=red, MEDIUM=yellow, LOW=green)
  - No modal interruption - renders in status area
- **Session Approvals:**
  - Remember approvals for the session
  - "Always approve edits" mode for file operations
  - "Trust this MCP tool" for MCP server tools
  - Clear approvals with `/permissions clear`
- **Runtime Configuration:**
  - `/permissions` - Show current mode and statistics
  - `/permissions strict` - Switch to CONFIRM_ALL mode
  - `/permissions default` - Switch to DEFAULT mode
  - `/permissions stats` - View approval statistics
- **Statistics Tracking:**
  - Total permission checks
  - Auto-approved vs user-approved
  - Denied and blocked counts

**Implementation:**
- Event bus integration at SECURITY priority (900)
- Hook intercepts TOOL_CALL_PRE events
- Permission manager with risk assessor
- Inline UI component in status area
- Configuration via `kollabor.permissions.*`

**Usage:**
```bash
# Show current permission settings
/permissions

# Switch to strict mode (confirm everything)
/permissions strict

# Switch to default mode (HIGH risk only)
/permissions default

# View approval statistics
/permissions stats

# Clear session approvals
/permissions clear
```

**Permission Prompt Example:**
```
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
   permission required                                      HIGH RISK
   shell: rm -rf /tmp/*
   a approve   s session   d deny   c cancel
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
```

**Configuration:**
```json
{
  "kollabor.permissions": {
    "enabled": true,
    "approval_mode": "confirm_all",
    "audit_log_enabled": true,
    "risk_assessment": {
      "trusted_tools": ["read_file", "list_directory", "glob"],
      "blocked_tools": []
    }
  }
}
```

**Related Files:**
- `kollabor/llm/permissions/` - Permission system implementation
- `kollabor/io/status/permission_status_view.py` - Inline UI component
- `docs/specs/tool-permission-system-spec.md` - Complete specification

### Async/Await Architecture

Modern Python async patterns throughout for responsive performance.

**Features:**
- Main event loop with `asyncio.run()`
- Concurrent tasks for render loop and input handler
- Background task tracking with `app.create_background_task()`
- Proper cleanup with task cancellation
- All plugin hooks are async

**Pattern:**
```python
# Background tasks
task = app.create_background_task(my_async_function())

# Concurrent execution
await asyncio.gather(
    render_loop(),
    input_handler()
)

# Cleanup
async def cleanup():
    for task in self.background_tasks:
        task.cancel()
    await asyncio.gather(*self.background_tasks, return_exceptions=True)
```

**Related Files:**
- `kollabor/application.py` - Main async orchestration

### Cross-Platform Support

Windows and Unix compatibility.

**Features:**
- Platform-specific terminal handling
- Cross-platform path handling
- Windows-compatible ANSI support

### Installation Methods

Multiple installation options for different use cases.

**Methods:**
- Homebrew (macOS): `brew install kollaborai/tap/kollabor`
- One-line install: `curl -sS https://...install.sh | bash`
- uvx (fastest, isolated): `uvx --from kollabor kollab`
- uv tool: `uv tool install kollabor`
- pipx (isolated): `pipx install kollabor`
- pip (standard): `pip install kollabor`
- From source: `pip install -e .`

---

## Feature Index

Quick reference for finding features:

| Feature | Category | Documentation |
|---------|----------|---------------|
| Interactive Mode | Core | [Core Features](#interactive-mode) |
| Pipe Mode | Core | [Core Features](#pipe-mode) |
| Conversation Management | LLM | [LLM Features](#conversation-management) |
| Tool Execution | LLM | [LLM Features](#tool-execution) |
| Question Gate | LLM | [docs/features/question-gate-protocol.md](docs/features/question-gate-protocol.md) |
| MCP Integration | LLM | [LLM Features](#model-context-protocol-mcp) |
| Profile Management | LLM | [LLM Features](#profile-management) |
| Agent & Skill System | LLM | [LLM Features](#agent--skill-system) |
| Dynamic System Prompts | LLM | [docs/features/dynamic-system-prompts.md](docs/features/dynamic-system-prompts.md) |
| Status Display | UI | [Terminal UI Features](#status-display-system) |
| Widget Status System | UI | [docs/features/widget-status-system.md](docs/features/widget-status-system.md) |
| Visual Effects | UI | [Terminal UI Features](#visual-effects) |
| Design System | UI | [Terminal UI Features](#design-system) |
| Modal System | UI | [Terminal UI Features](#modal-system) |
| Fullscreen Plugins | UI | [docs/reference/fullscreen-plugin-system.md](docs/reference/fullscreen-plugin-system.md) |
| Message Coordination | UI | [Terminal UI Features](#message-display-coordination) |
| Terminal State | UI | [Terminal UI Features](#terminal-state-management) |
| Ready Messages | UI | [docs/features/ready-message-system.md](docs/features/ready-message-system.md) |
| Plugin System | Plugins | [Plugin System](#plugin-system) |
| Save Conversations | Commands | [Built-in Plugins](#save-conversation-plugin) |
| Resume Conversations | Commands | [docs/features/RESUME_COMMAND_SPEC.md](docs/features/RESUME_COMMAND_SPEC.md) |
| Tmux Integration | Commands | [Built-in Plugins](#tmux-plugin) |
| Slash Commands | Commands | [Slash Commands](#slash-commands) |
| Configuration | Config | [Configuration & Environment](#configuration-system) |
| Environment Variables | Config | [Configuration & Environment](#environment-variables) |
| Hook System | Developer | [Developer Features](#hook-system) |
| Testing | Developer | [Developer Features](#testing-system) |
| Known Issues | Developer | [Developer Features](#known-issues-tracking) |
| Git Workflow | Developer | [Developer Features](#git-workflow) |

---

## Contributing

Want to add a new feature? Check out:
- [CLAUDE.md](CLAUDE.md) - Development guidelines and architecture
- [docs/](docs/) - Comprehensive documentation
- [tests/](tests/) - Testing guidelines

When documenting new features:
1. Add feature to appropriate category in this document
2. Create detailed spec in `docs/features/` if needed
3. Update README.md if it's a major feature
4. Add to documentation index in `docs/README.md`
5. Include usage examples and related files

---

**Document Information:**
- Version: 1.0
- Date: 2026-01-20
- Status: Active
- Maintained by: Kollabor Team
