tui-usage.md

Terraphim Terminal User Interface (TUI)

Terraphim includes a terminal interface with three execution modes:

• Fullscreen TUI (terraphim-agent) - server-backed interactive UI
• REPL (terraphim-agent repl) - offline-capable by default
• CLI subcommands (terraphim-agent <command>) - offline-capable by default unless --server is used

These modes support VM management, web operations, and intelligent file operations with semantic awareness.

Installation

Prerequisites

• Rust toolchain (cargo)
• Running Terraphim server (required for fullscreen TUI and --server mode)

Building from Source

Build the TUI from the workspace with optional feature flags:

# Clone the repository (if you haven't already)
git clone https://github.com/terraphim/terraphim-ai.git
cd terraphim-ai

# Build with all features (recommended)
cargo build -p terraphim_tui --features repl-full --release

# Build with specific features
cargo build -p terraphim_tui --features repl,repl-chat,repl-file,repl-mcp --release

# Build minimal TUI (basic functionality only)
cargo build -p terraphim_tui --release

# The binary will be available at
# ./target/release/terraphim-agent

Feature Flags

The TUI supports modular feature flags for different capabilities:

• repl - Basic REPL functionality and search commands
• repl-chat - AI chat integration with OpenRouter and Ollama
• repl-file - Enhanced file operations with semantic awareness
• repl-mcp - Model Context Protocol (MCP) tools integration
• repl-full - All features enabled (recommended)

Example: Install with chat and file operations:

cargo install --path crates/terraphim_tui --features repl-chat,repl-file

Configuration

Set the Terraphim server URL (defaults to http://localhost:8000):

export TERRAPHIM_SERVER=http://localhost:8000

This environment variable is used by fullscreen TUI and --server mode. REPL and CLI subcommands in default mode can run offline.

Command Reference

Fullscreen TUI Mode (Server-Backed)

terraphim-agent

Use this mode when you want the fullscreen terminal UI and a running Terraphim server.

REPL Mode (Offline-Capable)

terraphim-agent repl

Use terraphim-agent repl --server --server-url http://localhost:8000 to run REPL in server mode.

In REPL mode, you have access to:

• Smart Search: Type queries and get intelligent suggestions from the rolegraph
• VM Management: Control Firecracker VMs for isolated operations
• Web Operations: Perform web requests through secure VM sandboxing
• File Operations: Intelligent file management with semantic analysis
• AI Chat: Integrated AI assistant with context awareness
• Configuration: Real-time role and configuration management
• Help System: Built-in command help and suggestions

REPL Commands

Navigation and Help:

/help                    # Show all available commands
/quit                    # Exit the REPL
/clear                   # Clear the screen

Search and Knowledge:

/search "async rust"     # Search with semantic understanding
/graph                   # Show rolegraph visualization
/roles list              # List available roles
/role select Developer   # Switch to Developer role

VM Management:

/vm list                 # List all VMs
/vm create my-vm         # Create new VM
/vm start my-vm          # Start VM
/vm stop my-vm           # Stop VM
/vm status my-vm         # Check VM status
/vm logs my-vm           # View VM logs

Web Operations:

/web get https://api.example.com/data
/web post https://api.example.com/submit '{"data": "value"}'
/web scrape https://example.com '.content'
/web screenshot https://example.com
/web pdf https://example.com/article
/web history             # View operation history

File Operations (Semantic):

/file search "error handling" --path ./src --semantic
/file classify ./src --recursive --update-metadata
/file analyze ./main.rs --classification --extract-entities
/file summarize ./README.md --detailed --key-points
/file tag ./lib.rs rust,core,module --auto-suggest
/file index ./docs --recursive
/file metadata ./src/main.rs --extract-concepts

AI Chat:

/chat "Explain async patterns in Rust" --role Developer
/chat "Help me debug this issue" --context ./src/main.rs

Search Command

Search for documents using the CLI:

terraphim-agent search --query "terraphim-graph" --role "Default" --limit 10

Parameters:

• --query (required): The search term or phrase
• --role (optional): Role name to use for search context (default: "Default")
• --limit (optional): Maximum number of results to return (default: 10)

Example output:

- 0.95    Introduction to Terraphim Graph
- 0.82    Graph-based Knowledge Representation
- 0.75    Implementing Graph Algorithms

Roles Management

List available roles:

terraphim-agent roles list

Select a role for future queries:

terraphim-agent roles select "Engineer"

Configuration Commands

Display current configuration:

terraphim-agent config show

Update configuration settings:

# Change selected role
terraphim-agent config set selected_role=Engineer

# Update global shortcut
terraphim-agent config set global_shortcut=Ctrl+X

# Change theme for a specific role
terraphim-agent config set role.Default.theme=spacelab

Rolegraph Visualization

Display ASCII representation of the rolegraph:

terraphim-agent graph --role "Default" --top-k 10

Parameters:

• --role (optional): Role name to visualize (default: "Default")
• --top-k (optional): Number of top nodes to display (default: 50)

Example output:

Nodes: 1250  Edges: 3750
- [95] terraphim-graph -> knowledge representation, semantic networks, graph theory, ontology, rolegraph
- [87] knowledge management -> information retrieval, knowledge base, organization, metadata, taxonomy
- [76] graph database -> neo4j, arangodb, knowledge graph, query language, traversal

Chat Command (AI Integration)

Interact with AI models through OpenRouter or Ollama:

# REPL mode
/chat "Explain async patterns in Rust" --role Developer

# CLI mode
terraphim-agent chat --role "Default" --prompt "Summarize terraphim graph" --model anthropic/claude-3-sonnet

Parameters:

• --prompt (required): The message to send to the AI
• --role (optional): Role context to use (default: "Default")
• --model (optional): Specific model to use (overrides role default)
• --context (optional): File or directory to provide as context

Supported AI Providers:

• OpenRouter: Multiple models including Claude, GPT, Llama (requires OPENROUTER_KEY)
• Ollama: Local models (requires OLLAMA_BASE_URL)

VM Management (Firecracker Integration)

Manage isolated Firecracker virtual machines for secure operations:

# List all VMs and their status
/vm list

# Create a new VM with specific configuration
/vm create my-dev-vm --cpu 2 --memory 2048 --image ubuntu

# Start and stop VMs
/vm start my-dev-vm
/vm stop my-dev-vm
/vm restart my-dev-vm

# Monitor VM status and resources
/vm status my-dev-vm
/vm metrics my-dev-vm

# View logs and connect to VM
/vm logs my-dev-vm
/vm shell my-dev-vm

# VM pool management
/vm pool list
/vm pool create dev-pool --size 3 --cpu 2 --memory 2048

VM Features:

• Isolated Execution: Secure sandboxing for sensitive operations
• Resource Management: CPU, memory, and storage allocation
• Lifecycle Control: Start, stop, pause, and restart operations
• Monitoring: Real-time metrics and health status
• Integration: Seamless integration with web and file operations

Web Operations (VM-Sandboxed)

Perform web operations through secure VM isolation:

# HTTP requests
/web get https://api.example.com/data
/web post https://api.example.com/submit '{"data": "value"}' --headers "Content-Type: application/json"

# Web scraping and content extraction
/web scrape https://example.com '.content' --selector '.article'
/web screenshot https://example.com --full-page --wait 2000
/web pdf https://example.com/article --output article.pdf

# Form interactions
/web form https://example.com/login '{"username": "user", "password": "pass"}' --submit

# API exploration
/web api https://api.github.com /users/user1,/repos/repo1 --auth token

# Operation management
/web history
/web status webop-1642514400000
/web cancel webop-1642514400000

# Configuration
/web config show
/web config set timeout_ms 45000
/web config set user_agent "Terraphim-TUI/1.0"

Web Operation Features:

• VM Sandboxing: All requests run in isolated Firecracker VMs
• Security: No direct network access from host system
• Versatility: GET, POST, scraping, screenshots, PDF generation
• Authentication: Support for API keys, tokens, and form-based auth
• Operation Tracking: History, status monitoring, and cancellation

File Operations (Semantic Intelligence)

Intelligent file operations with semantic understanding and analysis:

# Semantic file search
/file search "error handling" --path ./src --semantic --limit 10
/file search "async patterns" --file-types rs,js --recursive

# Content-based classification
/file classify ./src --recursive --update-metadata
/file analyze ./main.rs --classification --semantic --extract-entities

# Content summarization
/file summarize ./README.md --detailed --key-points
/file summarize ./docs/api.md --brief

# Semantic metadata extraction
/file metadata ./src/main.rs --extract-concepts --extract-entities --extract-keywords

# Intelligent file indexing
/file index ./docs --recursive --force-reindex
/file find "function_name" --path ./src --type rs

# Smart file listing
/file list ./src --show-metadata --show-tags --sort-by name
/file list ./src --sort-by relevance --limit 20

# Semantic file tagging
/file tag ./lib.rs rust,core,module --auto-suggest
/file suggest --context "error handling" --limit 5

# Operation status
/file status indexing
/file status classification

File Operation Features:

• Semantic Search: Understanding of content meaning, not just text matching
• Content Classification: Automatic detection of file types, languages, frameworks
• Metadata Extraction: Concepts, entities, keywords, complexity metrics
• Relationship Discovery: Find related files based on content similarity
• Smart Tagging: Automatic tag suggestions based on content analysis
• Performance Analysis: Reading time estimation and complexity scoring

File Categories Supported:

• Code: Language detection (Rust, JavaScript, Python, etc.) with framework identification
• Documentation: Markdown, HTML, text files with complexity analysis
• Configuration: JSON, YAML, TOML, XML with purpose inference
• Data: CSV, JSON data files with structure analysis
• Media: Images, videos, audio files with metadata extraction
• Archives: ZIP, TAR, GZ with content type detection
• Scripts: Shell scripts, batch files with purpose analysis

Configuration Requirements

Environment Variables

Variable	Required	Default	Description
TERRAPHIM_SERVER	Mode-dependent	http://localhost:8000	Server URL used by fullscreen TUI and --server mode
OPENROUTER_KEY	No	None	OpenRouter API key for chat functionality
OLLAMA_BASE_URL	No	http://127.0.0.1:11434	Ollama server URL for local models
VM_STORAGE_PATH	No	./vm-storage	Directory for VM disk images
VM_NETWORK_BRIDGE	No	virbr0	Network bridge for VM networking
WEB_OPERATION_TIMEOUT	No	30000	Default timeout for web operations (ms)
FILE_INDEX_PATH	No	./file-index	Directory for file operation indexes

VM Configuration

The VM management requires Firecracker and proper system configuration:

# Install Firecracker (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y firecracker

# Set up kernel permissions for microVMs
sudo sysctl -w vm.nr_hugepages=1024
sudo chmod 666 /dev/kvm
sudo chown $USER:$USER /dev/kvm

# Create VM storage directory
mkdir -p ./vm-storage
chmod 755 ./vm-storage

VM Requirements:

• Linux kernel with KVM support
• Firecracker binary installed
• Proper permissions for /dev/kvm and /dev/vhost-net
• Sufficient memory and CPU for microVMs

MCP Tools Configuration

For Model Context Protocol integration:

# Set MCP server URL (optional)
export MCP_SERVER_URL=http://localhost:3001

# Set MCP authentication token (if required)
export MCP_AUTH_TOKEN=your-mcp-token

Server Requirements

Fullscreen TUI mode and --server mode require a running Terraphim server with the following endpoints:

• /config - Configuration management
• /config/selected_role - Role selection
• /documents/search - Document search
• /rolegraph - Role graph data
• /chat - AI chat functionality (optional)
• /documents/summarize - AI-powered document summarization (optional)

Feature-specific server requirements:

• Chat functionality: Server compiled with openrouter feature flag
• VM operations: Firecracker integration and proper system permissions
• File operations: Sufficient disk space for indexes and metadata
• Web operations: Network connectivity through VM sandboxing

Known Limitations

OpenRouter Feature Flag

The chat functionality requires the server to be compiled with the openrouter feature flag:

# Server must be built with OpenRouter support
cargo build --package terraphim_server --features openrouter

Without this feature flag enabled during server compilation, the chat command will return an error.

External Service Timeouts

• Server Connection: If the Terraphim server is unreachable, operations will time out after approximately 30 seconds
• OpenRouter API: Chat requests may time out after 60 seconds for complex or long requests
• VM Operations: VM startup and shutdown may take 10-30 seconds depending on system resources
• Web Operations: Timeout configurable via WEB_OPERATION_TIMEOUT (default: 30 seconds)
• File Indexing: Large repositories may require significant time for initial indexing
• Network Connectivity: Intermittent network issues may cause unexpected behavior

Command Support Limitations

• Configuration editing is limited to selected_role, global_shortcut, and role themes
• Chat functionality lacks streaming responses (planned for future releases)
• ASCII graph visualization is limited to basic node-neighbor representation
• VM operations require root privileges and proper KVM setup
• File operations are currently read-only (no file modification capabilities)
• Web operations through VMs may have limited JavaScript execution support

Platform Limitations

• VM Management: Currently only supported on Linux with KVM support
• Firecracker: Requires specific kernel configurations and permissions
• File Operations: Semantic analysis optimized for code and documentation files
• Web Scraping: Complex single-page applications may have limited support

Resource Requirements

• VM Operations: Minimum 2GB RAM recommended for running microVMs
• File Indexing: Disk space required for semantic indexes (varies by repository size)
• Web Operations: Memory usage scales with the complexity of web pages processed

Integration with Terraphim Ecosystem

The TUI seamlessly integrates with the broader Terraphim ecosystem:

Server Compatibility

The TUI is compatible with:

• Standard Terraphim server
• Custom server implementations that adhere to the API endpoints
• Cloud-hosted Terraphim instances

Data Access

• Leverages the same rolegraph and knowledge base as the desktop application
• Uses identical search algorithms and relevance functions
• Maintains consistent role-based context switching

Workflow Integration

The TUI can be integrated into existing workflows:

• CI/CD pipelines for knowledge retrieval
• Shell scripts for automated searches
• Terminal-based development environments

Example Integration Scripts

Build Script Integration:

#!/bin/bash
# Example of integrating Terraphim TUI into a build script

export TERRAPHIM_SERVER="http://knowledge.internal.example.com:8000"

# Run search and capture results
SEARCH_RESULTS=$(terraphim-agent search --query "deployment best practices" --role "DevOps" --limit 5)

# Process results
if echo "$SEARCH_RESULTS" | grep -q "deployment automation"; then
  echo "Found deployment automation documentation"
  # Additional processing...
fi

Code Review Automation:

#!/bin/bash
# Automated code analysis using TUI file operations

# Classify files in the repository
terraphim-agent file classify ./src --recursive --update-metadata

# Find potential issues
terraphim-agent file search "TODO" "FIXME" --path ./src --semantic

# Generate summary of changes
terraphim-agent file summarize ./CHANGELOG.md --detailed

Security Analysis:

#!/bin/bash
# Security analysis using VM-sandboxed web operations

# Check dependencies for known vulnerabilities
terraphim-agent web get "https://api.github.com/advisories?ecosystem=npm" --auth "$GITHUB_TOKEN"

# Scan web application securely
terraphim-agent web screenshot "https://app.example.com" --full-page
terraphim-agent web scrape "https://app.example.com" '.security-info'

Roadmap

Near-term (Next 3 months)

• Enhanced VM Management: VM snapshots, cloning, and migration
• Streaming Chat: Real-time streaming responses in the TUI
• File Editing: Safe file modification capabilities with backup
• Advanced Web Scraping: JavaScript execution and dynamic content support
• Performance Improvements: Optimized indexing and caching

Medium-term (3-6 months)

• Cross-platform VM Support: Windows and macOS VM management
• Collaborative Features: Shared sessions and real-time collaboration
• Advanced Analytics: Usage statistics and performance metrics
• Plugin System: Extensible architecture for custom operations
• Enhanced Security: Certificate management and secure enclaves

Long-term (6+ months)

• GUI Integration: Seamless integration with desktop application
• Mobile Support: Mobile-friendly interface and capabilities
• Cloud Integration: Direct cloud service integrations (AWS, GCP, Azure)
• AI-Powered Automation: Intelligent workflow automation
• Enterprise Features: SSO, audit logging, and compliance tools

Community Contributions

We welcome contributions for:

• Language Support: Expanding semantic analysis to more programming languages
• Documentation: Improving documentation and adding examples
• Testing: Comprehensive test coverage for all features
• Performance: Optimization and benchmarking improvements
• Accessibility: Making the TUI more accessible to all users