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