Terraphim Agent and CLI Multi-Agent Orchestration Status

Date: March 7, 2026 Status: All systems operational - builds passing, tests passing

Overview

The terraphim-ai repository contains a comprehensive multi-agent orchestration system with three main CLI tools and a sophisticated agent framework.

1. terraphim-cli (Automation CLI)

Location: crates/terraphim_cli Binary: terraphim-cli Status: Building successfully

Purpose

Non-interactive command-line tool for scripting and automation. Outputs JSON for easy parsing and integration with other tools.

Key Features

• Semantic knowledge graph search
• JSON output for automation
• Role-based configuration management
• Graph visualization (top concepts)
• Shell completion generation

Commands

• search <query> - Search documents with role-based filtering
• config - Show current configuration
• roles list/select - Manage roles
• graph - Show knowledge graph top concepts
• replace - Text replacement with knowledge graph synonyms
• completions - Generate shell completions

Dependencies

• terraphim_service, terraphim_config, terraphim_types
• terraphim_automata, terraphim_rolegraph
• terraphim_settings, terraphim_persistence
• clap for CLI framework

Build Status

cargo build -p terraphim-cli
# Finished successfully

2. terraphim-agent (Interactive Agent CLI)

Location: crates/terraphim_agent Binary: terraphim-agent Status: Building successfully, 138 tests passing

Purpose

Interactive AI agent CLI with REPL, chat interface, and advanced features for direct user interaction.

Key Features

• Interactive REPL with history
• Chat interface with LLM integration
• ASCII graph visualization
• Session management and search
• Markdown-defined custom commands
• Auto-update capability
• Onboarding wizard
• Robot mode for structured automation

REPL Features (Feature-Gated)

• repl - Basic REPL functionality
• repl-interactive - Interactive prompts
• repl-chat - Chat functionality
• repl-mcp - MCP tools integration
• repl-file - Enhanced file operations
• repl-custom - Markdown-defined commands
• repl-web - Web operations
• repl-sessions - Session history search

Dependencies

• All core terraphim crates
• ratatui for TUI interface
• crossterm for terminal control
• rustyline for REPL (optional)
• terraphim_sessions for session search (optional)

Build Status

cargo build -p terraphim_agent
# Finished successfully

Test Results

cargo test -p terraphim_agent --lib
# 138 passed; 0 failed

3. terraphim_multi_agent (Multi-Agent Orchestration)

Location: crates/terraphim_multi_agent Status: Building successfully, 69 tests passing

Purpose

Production-ready multi-agent system built on Terraphim's role-based architecture with Rig framework integration.

Architecture

Core Components

TerraphimAgent (src/agent.rs)

• Role configuration + Knowledge Graph + Evolution
• Status tracking (Initializing, Ready, Busy, Paused, Error, Terminating, Offline)
• Command history and context management
• LLM client integration (GenAiLlmClient)
• Token usage and cost tracking
• Goal alignment scoring

AgentRegistry (src/registry.rs)

• Agent discovery and registration
• Capability-based agent lookup
• Role-to-agent mapping
• Load metrics tracking

AgentPool (src/pool.rs)

• Pool configuration (min/max size, idle timeout)
• Load balancing strategies:
  • RoundRobin
  • LeastConnections
  • FastestResponse
  • Random
  • WeightedCapabilities
• Agent lifecycle management
• Performance optimization

PoolManager (src/pool_manager.rs)

• Multi-pool coordination
• Global statistics tracking
• Pool cleanup and maintenance
• On-demand pool creation

Specialized Agents (src/agents/)

ChatAgent (chat_agent.rs)

• Conversational interface
• Multi-turn dialogue support

OntologyAgents (ontology_agents.rs)

• Ontology creation and management
• Knowledge graph construction

SummarizationAgent (summarization_agent.rs)

• Document summarization
• Content extraction

Workflows (src/workflows/)

OntologyWorkflow (ontology_workflow.rs)

• Coverage-based ontology generation
• Signal computation for quality assessment

Supporting Modules

Agent Evolution (terraphim_agent_evolution)

• Versioned memory tracking
• Task list evolution
• Lessons learned database
• Goal alignment tracking

VM Execution (src/vm_execution/)

• Firecracker VM integration
• Code extraction from LLM responses
• Execution hooks and validation
• Session management

LLM Integration

• GenAiLlmClient for LLM communication
• Prompt sanitization and injection detection
• Token usage tracking
• Cost tracking

Multi-Agent Patterns Supported

1. Role Chaining - Sequential agent processing
2. Role Routing - Dynamic agent selection based on task
3. Role Parallelization - Concurrent agent execution
4. Lead-Specialist - Coordinator with specialized agents
5. Review-Optimize - Iterative improvement workflows

Dependencies

• genai (terraphim fork with OpenRouter support)
• terraphim_agent_evolution
• terraphim_config, terraphim_rolegraph
• terraphim_automata, terraphim_service
• reqwest for HTTP client
• tokio for async runtime

Build Status

cargo build -p terraphim_multi_agent
# Finished successfully

Test Results

cargo test -p terraphim_multi_agent --lib
# 69 passed; 0 failed

4. Supporting Agent Crates

terraphim_agent_evolution

Purpose: Agent memory, task, and learning evolution system

Features:

• VersionedMemory - Time-based snapshots of agent memory
• VersionedTaskList - Complete task lifecycle tracking
• VersionedLessons - Learning and knowledge retention
• Goal alignment tracking
• Evolution visualization

terraphim_agent_messaging

Purpose: Inter-agent communication system

Features:

• Message routing between agents
• Mailbox management
• Delivery guarantees

terraphim_agent_registry

Purpose: Agent capability registry

Features:

• Capability-based discovery
• Knowledge graph integration
• Metadata management

terraphim_agent_supervisor

Purpose: Agent supervision and lifecycle management

Features:

• Agent restart strategies
• Supervision trees
• Error recovery

terraphim_kg_agents

Purpose: Knowledge graph-specific agents

Features:

• Worker agents for KG operations
• Planning and coordination
• Pool management

Integration Points

CLI → Multi-Agent

• terraphim-cli uses terraphim_service for backend operations
• Does not directly use multi-agent (simpler, automation-focused)

Agent CLI → Multi-Agent

• terraphim-agent can spawn and coordinate multiple agents
• Uses terraphim_multi_agent for complex workflows
• Session history search via terraphim_sessions

Multi-Agent → Core Services

• Uses terraphim_service for backend operations
• Uses terraphim_config for role management
• Uses terraphim_rolegraph for knowledge graph operations
• Uses terraphim_automata for autocomplete
• Uses terraphim_persistence for storage

Current Limitations

1. Workflow Coverage: Only ontology_workflow.rs is implemented

   • Missing: Role chaining, routing, parallelization workflows

2. LLM Client: Uses genai fork (rig-core disabled)

   • Commented out: llm_client.rs, simple_llm_client.rs

3. VM Execution: Firecracker integration exists but may need testing

4. Documentation: Some modules lack comprehensive documentation

Testing Status

| Crate | Tests | Status | |-------|-------|--------| | terraphim-cli | Binary only | Builds | | terraphim_agent | 138 | All passing | | terraphim_multi_agent | 69 | All passing | | terraphim_agent_evolution | Integrated | Part of multi-agent tests |

Recommendations

High Priority

1. Complete Workflow Implementations

   • Implement role chaining workflow
   • Implement role routing workflow
   • Implement parallelization workflow

2. Integration Testing

   • Add end-to-end multi-agent tests
   • Test agent pool under load
   • Test VM execution paths

Medium Priority

3. Documentation

   • Add comprehensive module documentation
   • Create multi-agent usage examples
   • Document workflow patterns

4. Performance Optimization

   • Benchmark agent pool performance
   • Optimize agent creation/destruction
   • Profile memory usage

Low Priority

5. Feature Expansion
   • Add more specialized agents
   • Implement advanced load balancing
   • Add agent health monitoring

Usage Examples

Basic CLI Usage

# Search with role
terraphim-cli search "rust async" --role RustEngineer

# Show knowledge graph
terraphim-cli graph --top-k 20

# Select role
terraphim-cli roles select RustEngineer

Interactive Agent

# Start REPL
terraphim-agent repl

# Chat mode
terraphim-agent chat

# Session search
terraphim-agent sessions search "rust error handling"

Multi-Agent (Programmatic)

use terraphim_multi_agent::{AgentRegistry, TerraphimAgent, PoolManager};

// Create registry
let registry = AgentRegistry::new();

// Register agents
registry.register_agent(agent).await?;

// Find agents by capability
let agents = registry.find_agents_by_capability("summarization").await;

// Use pool manager
let pool_manager = PoolManager::new(persistence, None).await?;
let pool = pool_manager.get_or_create_pool(role).await?;

Summary

All three main components are operational and building successfully:

1. terraphim-cli: Ready for automation use
2. terraphim-agent: Feature-rich interactive CLI (138 tests passing)
3. terraphim_multi_agent: Sophisticated multi-agent orchestration (69 tests passing)

The multi-agent system has a solid foundation with agent pools, registries, and specialized agents. Main gap is completing the workflow implementations for role chaining, routing, and parallelization patterns.