terraphim_agent

Terraphim AI Agent CLI — semantic search, knowledge-graph exploration, and an interactive REPL for AI coding workflows.

Overview

terraphim_agent is the primary command-line interface for Terraphim. It combines offline-capable local search with optional server-backed fullscreen TUI mode, knowledge-graph validation, hook integration for AI coding assistants, and operational learning capture.

Install the binary as terraphim-agent.

Features

Semantic search across configured haystacks with KG-aware ranking
Interactive REPL with markdown-defined commands and autocomplete
Knowledge graph tools — validate, replace, extract, and visualize concepts
Session search — import and query AI coding assistant session history
Operational learning — capture corrections, query learnings, replay procedures
Safety guards — block destructive git/filesystem commands before execution
Robot mode — structured JSON output for automation and agent orchestration

Installation

From crates.io

cargo install terraphim_agent

From source

git clone https://git.terraphim.cloud/terraphim/terraphim-clients.git
cd terraphim-clients
cargo build -p terraphim_agent --release --bin terraphim-agent

The release binary is at target/release/terraphim-agent.

Feature Flags

Feature	Default	Description
`repl-interactive`	Yes	Interactive REPL with rustyline
`llm`	Yes	Ollama and LLM router integration
`repl-sessions`	Yes	Session import and search
`server`	No	HTTP client for server-backed TUI
`repl-full`	No	All REPL sub-features (chat, MCP, web, file)
`shared-learning`	No	Cross-agent learning store and wiki sync
`enrichment`	No	Concept enrichment for session search

Build with extra features:

cargo build -p terraphim_agent --release --features repl-full,server

Quick Start

# Show available commands
terraphim-agent --help

# Semantic search (offline)
terraphim-agent search "async error handling"

# List and select roles
terraphim-agent roles list
terraphim-agent roles select "Terraphim Engineer"

# Validate text against the knowledge graph
terraphim-agent validate --connectivity "haystack service uses automata"

# Start the REPL
terraphim-agent repl

# First-time setup wizard
terraphim-agent setup

Server-backed TUI

When a Terraphim server is running:

terraphim-agent --server --server-url http://127.0.0.1:8000 interactive

Robot / automation output

terraphim-agent search "retry policy" --robot --format json

Configuration

On first run, the agent reads settings.toml from the platform config directory (~/.config/terraphim/ on Linux). Point role_config at a JSON role definition to bootstrap roles and haystacks:

role_config = "/path/to/terraphim_engineer_config.json"
default_data_path = "~/.local/share/terraphim"

Use terraphim-agent config show to inspect the active configuration and terraphim-agent config validate to check role definitions.

Key Commands

Command	Purpose
`search`	Semantic document search
`graph`	ASCII knowledge-graph visualization
`validate`	KG connectivity and checklist validation
`replace`	Thesaurus-based text replacement
`hook`	Pre/post-tool-use hook handler for AI assistants
`guard`	Safety pattern check for shell commands
`learn`	Operational learning capture and query
`sessions`	Import and search AI coding sessions

Testing

# Unit tests
cargo test -p terraphim_agent --lib

# Integration tests (hermetic, no server required)
cargo test -p terraphim_agent --test offline_mode_tests
cargo test -p terraphim_agent --test exit_codes

Related Crates

terraphim-cli — lightweight CLI for scripted search
terraphim_grep — hybrid grep with KG boost and LLM fallback
terraphim_mcp_server — MCP tools for editor integration

License

Apache-2.0

terraphim_agent 1.20.5