Skip to main content
Terraphim AI documentation
  • Bun Package Manager Replacement - Implementation Summary
  • CI Status for PR #179 - OpenRouter and Axum Fix
  • Cloudflare Pages Deployment for Terraphim AI Documentation
  • Comprehensive Test Report: terraphim-agent and terraphim-cli
  • Conare AI vs Terraphim: Implementation Summary
  • LLM Markdown Linter Design for Terraphim KG Schemas
  • LLM Markdown Linter Implementation Plan
  • OpenRouter Integration Testing Plan - Implementation Complete
  • Terraphim AI Performance Benchmarking Framework
  • Right-Side-of-V Report: PR 492 (CLI Onboarding Wizard)
  • Right-Side-of-V Report: PR 494 (agent and CLI test failures)
  • Right-Side-of-V Report: PR 495 (clippy warnings and rocksdb tests)
  • Right-Side-of-V Report: PR 496 (CI timeouts and redundant workflows)
  • Release Process Documentation
  • Ripgrep Tag Filtering Documentation
  • Tauri Signing Keys - 1Password Integration
  • Test Environment Improvements - Implementation Complete
  • Comprehensive Test Report: terraphim-agent and terraphim-cli
  • TinyClaw (CLAW) Component - Test Report
  • Untitled
  • Phase 5: Validation Report - Issue #421
  • Zipsign Signature Verification Fix - Handover Document
  • ADF model selection and agent spawn — reference
  • ADF Operations Guide
  • ADR-0002: Polyrepo GitHub Publish Pipeline
  • Phase 1 §1 — Tooling Inventory
  • Aggregator decoupling sketch (Stage B, Gitea #1910)
  • Phase 1 §10 — Experimental Crate Register
  • Phase 1 §4 — Hub Fan-In Summary
  • Cold-build timing baseline -- Stage A (Gitea #1910)
  • Polyrepo topology (Gitea #1910)
  • Terraphim Architecture Improvement Plan
  • Terraphim Architecture Review Report
  • Release v1.2.3
  • Terraphim AI v1.0.0 Release Notes
  • Terraphim AI v1.0.2 - Multi-Platform Release
  • Building a GitHub Actions-Style Runner with Firecracker VMs and Knowledge Graph Learning
  • 🚀 Terraphim Autocomplete in Novel Editor - Demonstration
  • ✅ Cache-First Architecture with Streaming - IMPLEMENTED
  • Chat Layout Responsive Design Test Plan
  • Novel Editor Autocomplete Integration - Implementation Status
  • ✅ OpenDAL Warnings Fixed
  • ✅ Performance Optimization Complete
  • ✅ Performance Validation Complete - All Issues Resolved
  • ✅ PROOF: All Issues Are Resolved
  • Desktop App for Terraphim AI Assistant
  • Terraphim AI Frontend Testing Guide
  • Test Status Summary
  • bulmaswatch-README
  • Manual Test: Graph Tags in Tauri App
  • Comprehensive Test: Tauri Parameter Naming Fixes
  • Novel Editor Autocomplete Tests
  • Atomic Server Haystack Integration Tests
  • CI-Friendly Playwright Tests
  • Rolegraph End-to-End Test Framework
  • Unit Tests
  • Tauri WebDriver Tests for KG Graph Functionality
  • Blog Post: Building Privacy-First AI Tools with X Integration
  • Hacker News Submission
  • Reddit Posts for Terraphim AI
  • X (Twitter) Marketing Thread
  • Auto-Update Feature - Implementation Plan Summary
  • TerraphimAgent Performance Benchmarks
  • Bigbox Deployment Plan: Firecracker-Rust + Terraphim Multi-Agent System
  • Branch Protection and Naming Conventions
  • Multi-Platform Build Guide for Terraphim AI
  • CI/CD Optimization Implementation Complete
  • CI/CD Troubleshooting Guide
  • CI_FIX_STATUS
  • CI/CD Migration from Earthly to GitHub Actions - COMPLETE
  • CI/CD Migration Guide
  • CI/CD Migration Plan: Earthly to Dagger
  • 🎉 CI/CD Workflows Successfully Fixed and Optimized
  • CI/Testing Infrastructure Enhancement Plan
  • Cloudflare Infrastructure Proof Analysis
  • 🎉 Terraphim TUI Implementation - Comprehensive Test Results
  • Context Management Fixes Summary
  • Terraphim-Agent Crash Analysis Report
  • Terraphim v1.0.0 Cross-Platform Installation Status
  • Database Backend Features
  • Dependency Minimization & Release Hardening - Summary Report
  • Firecracker-Rust Deployment Status
  • Implementation Plan: Automatic Updates Feature
  • Implementation Plan: Auto-Update Signature Verification
  • Terraphim Desktop App Test Checklist
  • Terraphim AI Development Session Summary
  • Disciplined Design Plan: Remaining Quality Issues
  • DNS Migration Guide: Terraphim.ai from Netlify to Cloudflare
  • Documentation Enhancement Implementation Complete
  • Terraphim v1.0.0 - Final Status Report
  • Terraphim Build & Interactive Mode Fix Plan
  • terraphim-agent Fix Verification Report
  • Terraphim AI v1.0.1 - Complete Functional Proof
  • Terraphim AI - Complete Functional Testing Plan
  • GitHub Actions Failure Analysis - PR #186
  • GitHub Actions Status - PR #186
  • Handover Document: Terraphim GitHub Runner Server Integration
  • Handover Document - LLM Router Feature Integration
  • Handover: 2026-03-10 - Agent Workflows E2E Implementation Complete
  • Auto-Update Feature Implementation Handover
  • Handover: GitHub Runner LLM Parser Fix
  • 🎉 Terraphim Implementation Summary - Complete Success!
  • Integration Test Fixes Summary
  • Linting Fixes Implemented
  • Linting Fixes Plan
  • LLM Markdown Linter for Terraphim KG Schemas - Summary
  • LLM Proxy Implementation Summary
  • Matrix Release Build Implementation Summary
  • GitHub Actions Matrix Configuration Fixes
  • Terraphim v1.0.0 Memory Usage Report
  • Phase 2 Complete: Cloudflare Migration - FULL SUCCESS ✅
  • docs.terraphim.ai Migration Plan: Zola → md-book
  • ✅ Terraphim v1.0.0 Minimal Release - COMPLETE!
  • Minimal Release Plan: Lib, REPL, and CLI
  • Disciplined Design Plan: OpenDAL WARN Message Reduction
  • OpenDAL Warning Messages - Research Summary
  • Terraphim AI - Outstanding Items Analysis
  • 🚀 Terraphim Performance Analysis & Optimization Guide
  • Terraphim AI Performance Improvement Plan
  • Phase 2: Core Functionality Validation - IMPLEMENTATION COMPLETE
  • Phase 5 Integration Summary
  • Phase 5 Verification: Complete ✅
  • Phase 1 Complete: Cloudflare Pages Project & 1Password Setup ✅
  • Terraphim AI - Outstanding Tasks and Development Plan
  • Platform Verification Report - v1.0.0
  • Pre-commit Hook Integration - API Key Detection
  • PR #186 - Complete Summary
  • PR #277 - Code Assistant Implementation Summary
  • 🎉 Terraphim v1.0.0 Minimal Release - PUBLISHED!
  • Quality Improvement Summary
  • Query.rs and Reddit Content Fetching Fix Plan
  • Atomic Server Roles for Terraphim
  • Dual Haystack Validation Framework
  • QueryRs Haystack Integration
  • Rebase Integration Test Fix Status
  • Terraphim AI v1.4.7 - Linux Release Build Report
  • ✅ Terraphim AI v1.0.0 Release - COMPLETED
  • Release Branch Consolidation Implementation Plan
  • Terraphim AI v1.0.0 Release Plan
  • 🎉 COMPLETE RELEASE PUBLISHED
  • Terraphim AI Release Readiness Validation Report
  • RELEASE_STATUS
  • Terraphim AI v1.0.0 Release Build Summary
  • Terraphim AI v0.2.4 Release Summary
  • RELEASE_V1.2.3_SUMMARY
  • Research Document: Automatic Updates Feature
  • Research Document: Auto-Update Signature Verification
  • Proof: Search Results Change Based on Role Selection
  • Self-Update Feature Analysis & Implementation Plan
  • Signature Verification Implementation Progress
  • 🚀 Terraphim Novel Autocomplete Testing Scripts
  • Test Implementation Report - Terraphim AI Role Coverage
  • Comprehensive Scoring Function x Haystack Test Matrix
  • 🎯 Terraphim Test Matrix - Comprehensive Results
  • Terraphim AI v1.0.1 Test Report
  • Test Report for v1.1.0 Release
  • Testing & Linting Results Summary - 2025-10-08
  • Test Results for v1.1.0 Release
  • Minimal Release Testing Summary
  • TruthForge Data Leak Response - FINAL STATUS
  • TruthForge Debug Mode - Complete Implementation & Deployment
  • TUI Validation Summary - November 11, 2025
  • TUI REPL Complete Functionality Verification Report
  • Phase 5 Validation Report: Automatic Updates Feature
  • Phase 4 Verification Report: Auto-Update Feature
  • Phase 2.1 Complete: Video Optimization ✅
  • Cloudflare Pages File Size Limitation
  • Terraphim Agent to VM Execution Integration - PROOF
  • Phase 5 Verification Report: VM Allocation Behavior
  • VM Allocation Verification - Executive Summary
  • VM Execution API Design - Comprehensive Architecture
  • VM Execution System Guide
  • VM Execution Testing Plan
  • VM Execution Integration - Implementation Summary
  • Warning Analysis and Implementation Plan - COMPLETED ✅
  • Terraphim.ai Migration: Netlify to Cloudflare Pages
  • Terraphim.ai Website Migration Complete
  • AI Agent CLI Functionality Proof Report
  • CI/CD Critical Issues - Immediate Action Required
  • CI/CD Issues Analysis and Fix Proposal
  • Cross-Reference Validation Report
  • Droid Configuration - Lessons Learned
  • Terraphim AI Security Testing Implementation - Plan Update
  • Terraphim Firecracker Project - Implementation Plan Update
  • Security Testing Lessons Learned (2025-10-07)
  • Lessons Learned - Terraphim AI Development
  • Memories - Terraphim AI Development
  • Phase 5: Final CI/CD Optimizations Implementation
  • Configuration for GitHub Labeler Action
  • Scratchpad - Active Development Tasks
  • TUI Remediation Session Summary
  • test-timeout-investigation
  • CI/CD Timeout Test - Mon 22 Dec 2025 02:30:38 PM CET
  • Terraphim AI Test and Benchmark Report
  • Testing Infrastructure Implementation Status Report
  • Terraphim TUI Implementation Completion Summary
  • Terraphim TUI Validation Report
  • Version Update Report
  • Release v1.0.0 - Accomplishments Summary
  • GitHub Actions Fix Applied
  • Dead Code Investigation: query_rs.rs
  • Terraphim AI v1.0.0 - Final Comprehensive Status
  • Terraphim AI v1.0.0 - Final Validation Status
  • Terraphim AI v1.0.0 - Functional Validation Report
  • GitHub Actions Fix Plan for v1.0.0 Release
  • GitHub Secret Setup for Signed Tauri Releases
  • Release v1.0.0 - Status Update
  • Terraphim AI v1.0.0 Release Notes
  • Terraphim AI v1.0.0 - Step-by-Step Functional Validation
  • Atomic Client Feature Flag Documentation
  • Terraphim Agent Auto-Update System
  • Dynamic Ontology Launch Announcement
  • Introducing Dynamic Ontology: Schema-First Knowledge Graphs
  • FFF Search Integration: Knowledge-Graph-Augmented File Search for AI Agents
  • Hybrid Code Search That Knows When to Ask an LLM
  • FFF Search Integration -- Capability Statement
  • CI/CD Pipeline Migration
  • Code Assistant Requirements vs Current Implementation Analysis
  • Terraphim AI Component Architecture
  • Composio Agent Orchestrator vs Terraphim ADF -- Comparison Analysis
  • Conare AI vs Terraphim: Context Engineering Comparison
  • Context Collections Management
  • Context Engineering with Terraphim: Quick Start
  • Context Library
    1. Gitea Actions is the authoritative CI; GitHub Actions is for release publishing only
  • Terraphim AI Deployment Guide
  • Design & Implementation Plan: Fix UTF-8 Byte Boundary Panic in KG Link Logging
  • ADF Direct Dispatch Remediation -- Design Document
  • ADF Worktree Lifecycle Hardening -- Design Document
  • ADF Worktree Lifecycle Hardening -- Research Document
  • Design & Implementation Plan: DangerousPatternHook Unification
  • turbopuffer ContainsAnyToken vs Terraphim graph/embedding search
  • GrepApp Feature
  • Terraphim AI Domain and Data Models
  • terraphim_automata - Text Matching and Autocomplete Engine
  • terraphim_config - Configuration Management
  • terraphim_middleware - Haystack Indexing and Orchestration
  • terraphim_persistence - Multi-Backend Storage Abstraction
  • terraphim_rolegraph - Knowledge Graph Implementation
  • terraphim_service - Main Service Layer
  • terraphim_types - Core Type Definitions
  • Duplicate Handling in Terraphim AI
  • Terraphim AI Examples & Integration Guide
  • GitHub Actions Issues and Proposed Fixes
  • GitHub Actions Release Workflow Fix Implementation Plan
  • Terraphim GitHub Runner - Architecture Documentation
  • GitHub Runner Integration - Commit Summary
  • Terraphim GitHub Runner - Setup Guide
  • GitHub Runner Webhook Integration - Implementation Complete
  • GitHub Secrets Setup Guide
  • Session Handover: 2026-05-11 ADF Fleet Restart
  • Session Handover: 2026-05-12 (Morning)
  • Handover: terraphim_rlm OpenCode Integration
  • Handover: ADF Orchestrator Investigation & Fix
  • Handover: Evolution Wiring into ADF Orchestrator
  • Handover: ADF Fixes & odilo-developer Investigation
  • Handover: RLM Executor Surface Hardening — Echo Re-verification
  • Handover: RLM Executor Surface Hardening — Echo Session
  • Handover: ADF gate hardening + repo-local autonomous agents
  • ADF Recap & Outstanding Actions -- 2026-06-05
  • ADF PR Gate Result Contract Handover
  • Native CI, Rustup Perms & Gitea Runner Handover
  • Handover: ADF digital-twins improvements & per-project status fix
  • Handover: v1.21.0 Release — KG-Driven Runner, Provider Probe Fixes, Model Roster Update
  • Handover Document: Dynamic Ontology Feature
  • Implementation Plan: terraphim-grep — Intelligent Hybrid Grep
  • Terraphim AI Installation and Deployment Guide
  • knowledge-graph
  • LLM Proxy Configuration Guide
  • MCP File Context Tools
  • ADF Orchestrator systemd Pre-Start Sweep
  • Perplexity Integration for Terraphim AI
  • Architecture Comparison: pi-mono vs terraphim-ai
  • Implementation Plan: Telegram Bot Integration for TinyClaw
  • Decision: Approve Native CI Ignore-Policy Design
  • Decision: Approve Native CI Ignore-Policy Research
  • Decision: Approve Native CI Ignore-Policy Specification
  • Implementation Plan: KG-Driven Dynamic Command Allowlist for Gitea Runner
  • Implementation Plan: Native CI Ignore-Policy Coverage Correction
  • Design Gate — #3184 fleet-internal release bless = Gitea private cargo
  • Apple Container RLM Backend Design Gate
  • Implementation Plan: TinyClaw Hermes Parity — 15 Auxiliary Tools
  • Design: tinyclaw cron surface (#3147) + jmap relocation (#3198)
  • Implementation Plan: TinyClaw Hermes Parity Tools — Sandbox, Subagents, Browser
  • Design Gate — tinyclaw hermetic env scrubber (issue #3161)
  • Plan: GitHub Actions -> Gitea Actions CI migration
  • Implementation Plan: Fix Search Output/Result Regressions (#578, #579)
  • Research Document: Fix terraphim-agent/terraphim-cli Search Regressions (#578, #579)
  • Research: Fix LegacyTerm deserialization in terraphim_automata
  • Research: Fix LegacyTerm deserialisation in parse_thesaurus_json
  • Implementation Plan: Make Offline Mode Default for terraphim-agent TUI
  • Research Document: Make Offline Mode Default for terraphim-agent
  • Implementation Plan: Fix Pre-Existing Clippy Errors Blocking PR #2971
  • Implementation Plan: PR/Issue Execution with PR #527 Merged First
  • Implementation Plan: Post-#527 Portfolio Execution (Overall)
  • Disciplined Research: Current PR and Issue Portfolio
  • Research Document: PR #529 Gap Analysis
  • Implementation Plan: PR #529 Gap Coverage
  • Research: KG-Driven Dynamic Command Allowlist for Gitea Runner
  • Research Document: Native CI Ignore Policy Coverage Gap
  • Research: TinyClaw Hermes Parity — 15 Auxiliary Tools
  • Research: tinyclaw cron surface (#3147) + jmap crate relocation (#3198)
  • Research: TinyClaw Hermes Parity Wave — Sandbox (rlm), Subagents (spawner), Browser
  • Implementation Plan: Clarify terraphim-agent TUI Offline/Server Requirement (terraphim-ai-cbm)
  • Research Document: Clarify terraphim-agent TUI Offline/Server Requirement (terraphim-ai-cbm)
  • Implementation Plan: TinyClaw OpenClaw Parity via Terraphim Extensions
  • Research Document: TinyClaw OpenClaw Parity via Terraphim Extensions
  • Phase 2 Implementation Plan: TinyClaw Enhancements
  • Phase 2 Research Document: TinyClaw Enhancements
  • Implementation Plan: TinyClaw Slack Channel Adapter
  • Research Document: TinyClaw Slack Channel Adapter
  • Implementation Plan: TinyClaw Slack Test Leverage (12 Tests + 3 Bug Fixes)
  • Research Document: Leveraging OpenClaw and NanoClaw Slack Tests for TinyClaw
  • Implementation Plan: TinyClaw on Terraphim (terraphim_tinyclaw)
  • Rebuilding TinyClaw with Terraphim AI
  • Research Document: Rebuilding TinyClaw on Terraphim AI
  • Design & Implementation Plan: Revert NormalizedTerm.id and Concept.id from String to u64
  • Research Document: Revert NormalizedTerm.id and Concept.id from String to u64
  • Verification Report: Native CI Ignore-Policy Coverage Correction
  • Platform-Specific Installation Guide
  • PR Evaluation: 4 Open Pull Requests
  • Quickwit Integration Guide
  • Desktop Extraction + Crate Dependency Minimization Review (2026-02-25)
  • Traceability Matrix: Issues #578 and #579
  • Validation Report: Issues #578 and #579
  • Verification Report: Issues #578 and #579
  • Research Document: Next PR Selection -- Post 5-PR Merge Sprint
  • Terraphim Agent and CLI Multi-Agent Orchestration Status
  • Major Version Updates Test Results
  • PR #502 Changes Summary
  • Terraphim AI -- Full Codebase Exploration Report
  • Terraphim AI Release Constraints Analysis
  • Terraphim AI Release Validation System - Architecture Design
  • Implementation Plan: Fix Cross-Mode Consistency Test Failures
  • Implementation Plan: terraphim_orchestrator -- AI Dark Factory
  • Implementation Plan: Dependabot PR Triage and Dependency Optimization
  • Terraphim AI Release Validation System - File/Module Change Plan
  • Design & Implementation Plan: Fix SearchResultDoc Compilation Errors in Integration Tests
  • Implementation Plan: Issue #589 - Wire WebToolsConfig to Web Search/Fetch Tools
  • Implementation Plan: Issue #611 - Sessions Files and By-File Subcommands
  • Implementation Plan: Issue #623 - Exclude Unused Haystack Providers
  • Implementation Plan: Issue #624 - Remove terraphim_repl, Consolidate CLIs
  • Implementation Plan: Replace atty with std::io::IsTerminal
  • Implementation Plan: OpenDAL Upgrade Decision
  • Terraphim AI Server API Testing Framework Design
  • Design & Implementation Plan Review: PR #502
  • Implementation Plan: PR #652 Merge Conflict Resolution
  • Terraphim AI Release Validation - Risk Review and Mitigation
  • Terraphim AI Release Validation System - Design Phase Summary
  • Terraphim AI Release Validation System - Design Document
  • Implementation Plan: Validation Framework for terraphim-ai
  • Research Document: Dynamic Ontology Feature Gates
  • Implementation Plan: Dynamic Ontology Feature Gates
  • Terraphim AI Functional Validation Requirements
  • Handover: terraphim_orchestrator -- AI Dark Factory
  • Terraphim AI Phase 2 Implementation Summary
  • Phase 1 Research — Polyrepo Split of Terraphim AI
  • Research Document: PR #2971 Merge Block
  • Document Quality Evaluation Report
  • Quality Evaluation: polyrepo-split-2026-05-10.md
  • Document Quality Evaluation Report
  • Document Quality Evaluation Report
  • Research Document: Cross-Mode Consistency Test Failures
  • Research Document: AI Dark Factory -- End-to-End Multi-Agent Orchestration
  • Research Document: Dependency Optimization and Dependabot Merge Planning
  • Terraphim AI Release Validation Research Document
  • Research Document: Fix SearchResultDoc Compilation Errors in Integration Tests
  • Research Document: Issue #589 - Wire WebToolsConfig to Web Search/Fetch Tools
  • Research Document: Issue #611 - Sessions Files and By-File Subcommands
  • Research Document: Issue #623 - Exclude Unused Haystack Providers
  • Research Document: Issue #624 - Remove terraphim_repl, Consolidate CLIs
  • Research Document: Replace atty and fxhash Dependencies
  • Research Document: Replace instant with web-time
  • Research Document: OpenDAL Upgrade Analysis
  • Research Document: pi-mono vs terraphim-ai Architecture Analysis
  • Research Document: PR #502 - plan/kg dynamic routing
  • Research Document: PR #652 Agent Workflows E2E Implementation
  • Terraphim AI Release Validation Research Questions
  • Research Document: Validation Framework for terraphim-ai
  • RFC: Cycle Break for terraphim_config ↔ terraphim_persistence ↔ terraphim_multi_agent
  • Terraphim AI Release Risk Assessment
  • Runtime Validation Hooks Documentation## OverviewTerraphim AI implements a two-stage runtime validation system that provides safety and knowledge-graph enhancement for AI-assisted development workflows. This system operates through pre/post hooks around LLM generation and tool execution.## Two-Stage Hook Flow### Stage 1: Guard Stage (Security & Bypass Protection)Purpose: Prevent dangerous operations and enforce safety invariants before any processing occurs.Location: ~/.claude/hooks/pre_tool_use.shImplementation:bash#!/bin/bash# Extract command from JSON inputCOMMAND=$(echo "$1" | jq -r '.tool_input.command // empty')# Strip quoted strings to avoid false positivesCLEAN_COMMAND=$(echo "$COMMAND" | sed 's/"[^"]*"//g')# Check for dangerous bypass flagsif [[ "$CLEAN_COMMAND" =~ (--no-verify|-n)(?=.*\bgit\s+(commit|push)) ]]; then # Return deny decision echo '{"decision": "deny", "reason": "Git bypass flags detected"}' exit 0fi# Continue to replacement stagecd ~/.config/terraphimterraphim-agent hook "$1"Guard Actions:- Block: --no-verify or -n flags in git commit/push commands- Allow: All other commands proceed to replacement stage- Log: All guard decisions with reasons### Stage 2: Replacement Stage (Knowledge Graph Enhancement)Purpose: Replace text using knowledge graph patterns and connectivity validation.Location: terraphim-agent hook command in Terraphim agentImplementation:rust// terraphim_agent/src/commands/hook.rspub async fn execute_hook( input: HookInput, agent: &TerraphimAgent,) -> Result<HookOutput, HookError> { // Apply knowledge graph replacements let enhanced_text = agent .rolegraph .apply_replacements(&input.text)?; // Validate connectivity agent .automata .validate_connectivity(&enhanced_text)?; Ok(HookOutput { modified_text: enhanced_text, was_modified: enhanced_text != input.text, })}Replacement Actions:- Enhance: Apply role-based knowledge graph patterns- Validate: Ensure semantic connectivity and coherence- Transform: Use thesaurus and autocomplete for consistency## Runtime LLM/Tool Hooks### Pre-LLM HooksPurpose: Validate LLM inputs before generation.Context:rustPreLlmContext { prompt: String, // Command type + description agent_id: String, // Agent identifier conversation_history: Vec<String>, // Previous messages token_count: usize, // Estimated tokens}Hook Decisions:- Allow: Proceed with LLM generation- Block: Stop with reason (security, policy, etc.)- Modify: Transform prompt (not recommended for LLM)- AskUser: Require human confirmation### Post-LLM HooksPurpose: Validate and potentially modify LLM outputs.Context:rustPostLlmContext { prompt: String, // Original prompt response: String, // Generated response agent_id: String, // Agent identifier token_count: usize, // Total tokens used model: String, // LLM model used}Hook Decisions:- Allow: Return original response unchanged- Block: Prevent response delivery (harmful content, policy violations)- Modify: Transform response (formatting, style, safety fixes)- AskUser: Require human review before delivery### Pre-Tool HooksPurpose: Validate code and commands before execution.Context:rustPreToolContext { code: String, // Code to execute language: String, // Programming language agent_id: String, // Agent identifier vm_id: String, // VM execution environment metadata: HashMap<String, String>, // Additional context}Security Validations:- Dangerous Patterns: rm -rf /, sudo, chmod 777, etc.- Language Restrictions: Block execution in disallowed languages- Resource Limits: Validate memory, CPU, and file access- Injection Prevention: Command injection and shell escape detection### Post-Tool HooksPurpose: Monitor and analyze execution results.Context:rustPostToolContext { original_code: String, // Original code executed output: String, // Execution output exit_code: i32, // Process exit code duration_ms: u64, // Execution time agent_id: String, // Agent identifier vm_id: String, // VM identifier}Monitoring Actions:- Success/Failure Tracking: Learn patterns of successful executions- Performance Analysis: Track execution times and resource usage- Security Logging: Record blocked or suspicious activities- Knowledge Graph Learning: Update successful patterns for future reference## Configuration### Runtime Validation ConfigLocation: ~/.config/terraphim/runtime-validation.toml````toml[hooks]enabled = truefail_open = true # Allow execution if hooks fail (development mode)[guard]strict_mode = false # Block on any suspicion vs. specific patternslog_all_decisions = true # Log allow/block decisions[llm_hooks]enabled = truerequire_human_review = false # Only for high-stakes operations[tool_hooks]enabled = truevm_isolation = trueresource_limits = true[replacement]knowledge_graph_enhancement = trueconnectivity_validation = true```### Environment Variables```bash# Enable/disable specific hook categoriesTERRAPHIM_RUNTIME_VALIDATION_HOOKS=trueTERRAPHIM_GUARD_STAGE=trueTERRAPHIM_REPLACEMENT_STAGE=true# Hook behavior overridesTERRAPHIM_FAIL_OPEN=false # Production mode: fail closedTERRAPHIM_HOOK_TIMEOUT_MS=5000 # Hook execution timeout```## Hook Development### Creating Custom Hooks```rustuse crate::vm_execution::{hooks::*, VmExecutionError};#[derive(Debug)]pub struct SecurityHook { blocked_patterns: Vec<regex::Regex>,}#[async_trait]impl Hook for SecurityHook { fn name(&self) -> &str { "security-hook" } async fn pre_tool(&self, context: &PreToolContext) -> Result<HookDecision, VmExecutionError> { for pattern in &self.blocked_patterns { if pattern.is_match(&context.code) { return Ok(HookDecision::Block { reason: format!("Blocked pattern: {}", pattern.as_str()), }); } } Ok(HookDecision::Allow) } async fn post_tool(&self, context: &PostToolContext) -> Result<HookDecision, VmExecutionError> { // Log execution for learning if context.exit_code != 0 { log::warn!("Tool execution failed: {:?}", context); } Ok(HookDecision::Allow) }}```### Registering Hooks```rust// In agent initializationlet mut agent = TerraphimAgent::new(config).await?;// Add custom hooksagent.hook_manager.add_hook(Arc::new(SecurityHook::new()));agent.hook_manager.add_hook(Arc::new(PerformanceHook::new()));agent.hook_manager.add_hook(Arc::new(LearningHook::new()));```## Troubleshooting### Hook Not Invoked**Symptoms**: LLM/tool execution without hook validation**Causes**:- HookManager not initialized in agent- Hooks not registered with manager- Hook execution disabled in config**Resolution**:```bash# Check configcat ~/.config/terraphim/runtime-validation.toml# Verify agent initializationgrep -r "hook_manager" src/agent.rs# Check registrationgrep -r "add_hook" src/```### Hook Blocking Too Much**Symptoms**: Many operations blocked as "dangerous"**Causes**: Overly strict regex patterns, false positives**Resolution**:- Review blocked_patternsin security hooks- Enable debug logging to see exact matches- Adjust patterns to be more specific### Performance Issues**Symptoms**: Slow LLM/tool response times**Causes**: Hook timeout, expensive operations, network calls**Resolution**:- IncreaseTERRAPHIM_HOOK_TIMEOUT_MS- Profile hook execution with tokio-console- Move expensive operations to background threads## Best Practices1. **Fail-Open Development**: Use fail_open = trueduring development to avoid blocking2. **Specific Patterns**: Use targeted regex patterns instead of broad blocks3. **Async Operations**: Keep hook implementations fast and non-blocking4. **Comprehensive Logging**: Log all decisions for debugging and learning5. **Knowledge Graph Integration**: Leverage existing rolegraph and automata for intelligence6. **Security First**: Always implement security validation before functionality7. **Testing**: Test both success and failure scenarios for all hooks## Integration Points- **Claude Code**:pre_tool_use.sh` → Guard → Replacement → Tool execution- Terraphim Agent: CommandExecutor with HookManager integration- VM Execution: Pre/post tool hooks around Firecracker execution- LLM Generation: Pre/post LLM hooks in all agent types- Knowledge Graph: Replacement service using rolegraph connectivityThis two-stage validation system ensures both security (guard stage) and intelligence enhancement (replacement stage) while maintaining clear separation of concerns and comprehensive audit trails.
  • Terraphim AI Release System Map
  • Terraphim AI Test Scenarios
  • Validation Report: terraphim_orchestrator -- AI Dark Factory
  • Terraphim AI Release Validation Implementation Roadmap
  • Validation Report: Issue #589 - Wire WebToolsConfig to Web Search/Fetch Tools
  • Validation Report: Issue #624 - terraphim_repl Removal
  • Validation Report: Validation Framework Implementation
  • Verification Report: Issue #589 - Wire WebToolsConfig to Web Search/Fetch Tools
  • Verification Report: Validation Framework Implementation
  • Verification and Validation Report: Issue #538
  • Verification and Validation Report: Issue #589
  • Verification and Validation Report: Issue #8
  • Verification and Validation Report: Issues #10, #56, #91, #96
  • Verification and Validation Report: Performance Issues #189-#203
  • Verification and Validation Report: Issues #207-#248
  • Verification and Validation Report: Issues #261-#382
  • Verification and Validation Report: Issues #539, #540, #541
  • Verification and Validation Report: KG Ranking Integration Tests
  • V-Model Final Report: Validation Framework Implementation
  • Research: rlmgrep vs terraphim_rlm — Evolving build-runner-llm with Hybrid Search + RLM
  • Research Document: terraphim-grep — Intelligent Hybrid Grep
  • Research: rlmgrep vs Terraphim — Proposal for Intelligent Hybrid Grep
  • Runbook: Fix Meta-Coordinator Health Check (blind under no_new_privs)
  • Runbook: Fix Worktree Disk-Usage Alert (dedup storm + frozen title)
  • Release Runbook (Gitea-authoritative, GitHub publish)
  • ROC v1 Staged Rollout Runbook
  • Sentrux Quality Gates
  • Design & Implementation Plan: Terraphim Knowledge Graph Workflows
  • Implementation Summary: Knowledge Graph Validation Workflows
  • Research Document: Underutilized Terraphim Features for Pre/Post-LLM Knowledge Graph Workflows
  • Session 20251228-201509
  • Development Session - 2025-12-29 10:49:27
  • Session Log: Build Scripts Investigation
  • Session: Merge PR 440
  • Fetching main, creating branch, drafting detailed specification
  • ADF Behaviour Specifications
  • Specification: Local Project Skill Path Resolution
  • Specification: Provider Probe Timeout and Health Classification
  • Specification: Redacted Output Capture and Timeout Reporting
  • Specification: Webhook Group Alias Dispatch and Expansion Limits
  • Specification: Worktree Fail-Closed Behaviour
  • Chat & Session History - Quick Reference
  • Chat and Session History Specification
  • Specification Interview Findings: Enhanced Learning Capture System
  • Terraphim Agent Session Search - Architecture Document
  • Terraphim Agent Session Search - Feature Specification
  • Terraphim Agent Session Search - Implementation Tasks
  • Terraphim-Based Codebase Evaluation Check
  • Terraphim Desktop Application - Technical Specification
  • Terraphim AI Architecture
  • Code of Conduct
  • Contributing to Terraphim AI
  • Using Terraphim Desktop with Claude via MCP
  • Design Decisions
  • Introduction
  • Terraphim documentation
  • Summary
  • Use cases for Terraphim AI
  • Terraphim AI Agent Evolution System Architecture
  • 5 AI Agent Workflows for Consistent Results (with Code) | Data Science Collective
  • Terraphim AI Agent Evolution System - API Reference
  • Artifacts
  • Artifact: GitHub Actions Fix Plan for v1.0.0 Release
  • Artifact: v1.0.0 Final Validation Status
  • Artifact: Release Status Final
  • Atomic Server Integration
  • Automata Paragraph Extraction
  • Your AI Agent Has Amnesia. We Fixed That.
  • Reddit Announcements
  • Reddit Announcements -- Terraphim Grep
  • Grep That Knows When to Ask an LLM
  • X/Twitter Thread
  • X/Twitter Thread -- Terraphim Grep
  • Branch Protection and Security
  • Case Studies
  • Case Study: Symphony Builds a Web Application
  • Changelog
  • Claude Code Skills Integration
  • Code Assistant Implementation (PR #277)
  • How-To: Learning-Driven Command Rewriting
  • Terraphim Atomic Client
  • Terraphim Automata
  • Terraphim Service
  • Crate Reference
  • Desktop App
  • Development Setup Guide
  • CI/CD Domain
  • Deployment Lessons: Vanilla JS UI + Caddy + 1Password
  • GitHub Actions Fix Plan (v1.0.0)
  • Desktop Domain
  • Release Domain
  • Final Validation Status (v1.0.0)
  • Security Domain
  • Security Testing Lessons Learned
  • VM Domain
  • Dynamic Ontology
  • Automata Evaluation Framework
  • Graph Connectivity Check for Matched Terms
  • 1Password Integration for Terraphim AI\n\n## Overview\n\nThis document describes the comprehensive 1Password integration for Terraphim AI, providing enterprise-grade secret management across all components including backend services, desktop applications, and CI/CD pipelines.\n\n## Architecture\n\n### Three-Vault Strategy\n\n- Terraphim-Dev: Development environment secrets\n- Terraphim-Prod: Production environment secrets \n- Terraphim-Shared: Shared secrets across environments (signing keys, monitoring)\n\n### Integration Methods\n\n#### Method 1: Process Memory Injection (Recommended)\nbash\n# Secrets are injected directly into process memory\nop run --env-file=\".env.terraphim\" -- cargo run\n\n\n#### Method 2: Secure File Injection\nbash\n# Secrets are written to secure temporary files\nop inject -i templates/settings.toml.template -o settings.toml\ncargo run\n\n\n## Setup Instructions\n\n### 1. Install 1Password CLI\n\nmacOS:\nbash\nbrew install 1password-cli\n\n\nLinux:\nbash\ncurl -sS https://downloads.1password.com/linux/keys/1password.asc | gpg --import\nwget https://downloads.1password.com/linux/debian/amd64/stable/1password-cli-amd64-latest.deb\nsudo dpkg -i 1password-cli-amd64-latest.deb\n\n\n### 2. Initialize 1Password Integration\n\nbash\n# Run the setup script to create vaults and secret structure\n./scripts/setup-1password-terraphim.sh dev\n\n# For production setup\n./scripts/setup-1password-terraphim.sh prod\n\n# For complete setup\n./scripts/setup-1password-terraphim.sh all\n\n\n### 3. Populate Secrets\n\nAfter running the setup script, you'll need to update the placeholder values in 1Password with actual secrets:\n\n1. Open 1Password and navigate to the appropriate vault\n2. Update each secret item with real values\n3. Ensure all op:// references in templates are valid\n\n## Usage\n\n### Backend Services\n\n#### Option 1: Direct 1Password Integration\nrust\nuse terraphim_settings::DeviceSettings;\n\n#[tokio::main]\nasync fn main() -> Result<(), Box<dyn std::error::Error>> {\n // Load settings with 1Password integration\n let settings = DeviceSettings::load_with_onepassword(None).await?;\n println!(\"Loaded settings with resolved secrets\");\n Ok(())\n}\n\n\n#### Option 2: Template-based Configuration\nbash\n# Generate configuration from template\nop inject -i templates/settings.toml.template -o settings.toml\n\n# Run application with resolved configuration\ncargo run\n\n\n### Desktop Application\n\nThe Tauri desktop application includes built-in 1Password commands:\n\ntypescript\nimport { invoke } from '@tauri-apps/api/tauri';\n\n// Check 1Password status\nconst status = await invoke('onepassword_status');\nconsole.log('1Password available:', status.available);\nconsole.log('1Password authenticated:', status.authenticated);\n\n// Resolve a secret reference\nconst secret = await invoke('onepassword_resolve_secret', {\n request: { reference: 'op://Terraphim-Dev/OpenRouter/API_KEY' }\n});\n\n// Process configuration with 1Password\nconst config = await invoke('onepassword_process_config', {\n request: { config: 'api_key = \"op://Terraphim-Dev/OpenRouter/API_KEY\"' }\n});\n\n\n### CI/CD Integration\n\nUse the enhanced GitHub Actions workflow with 1Password service accounts:\n\nyaml\n# .github/workflows/ci-1password.yml\nname: CI with 1Password\n\nenv:\n OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}\n\njobs:\n build:\n steps:\n - name: Install 1Password CLI\n uses: 1password/install-cli-action@v1\n \n - name: Generate configuration\n run: |\n op inject -i templates/env.terraphim.template -o .env.terraphim\n \n - name: Build with secrets\n run: |\n source .env.terraphim\n cargo build --release\n\n\n## Configuration Templates\n\n### Environment Variables Template\nbash\n# templates/env.terraphim.template\nOPENROUTER_API_KEY=\"op://Terraphim-Dev/OpenRouter/API_KEY\"\nANTHROPIC_API_KEY=\"op://Terraphim-Dev/Anthropic/API_KEY\"\nATOMIC_SERVER_SECRET=\"op://Terraphim-Dev/AtomicServer/SECRET\"\n\n\n### Settings Configuration Template\ntoml\n# templates/settings.toml.template\n[profiles.s3]\nbucket = \"op://Terraphim-Dev/AWS_S3/BUCKET_NAME\"\naccess_key_id = \"op://Terraphim-Dev/AWS_S3/ACCESS_KEY_ID\"\nsecret_access_key = \"op://Terraphim-Dev/AWS_S3/SECRET_ACCESS_KEY\"\n\n\n### Application Configuration Template\njson\n{\n \"llm\": {\n \"openrouter\": {\n \"api_key\": \"op://Terraphim-Dev/OpenRouter/API_KEY\"\n }\n }\n}\n\n\n## Secret Categories\n\n### LLM API Keys\n- OpenRouter: API_KEY, ORGANIZATION_ID\n- Anthropic: API_KEY, MODEL_NAME\n- Ollama: BASE_URL, MODEL_NAME\n\n### Search Services\n- Perplexity: API_KEY\n- Atomic Server: URL, SECRET\n- ClickUp: API_TOKEN, TEAM_ID, LIST_ID\n\n### Cloud Storage\n- AWS S3: ACCESS_KEY_ID, SECRET_ACCESS_KEY, BUCKET_NAME, REGION\n- Cloudflare R2: ACCOUNT_ID, ACCESS_KEY_ID, SECRET_ACCESS_KEY\n\n### External APIs\n- GitHub: TOKEN, ORGANIZATION, REPOSITORY\n- Discord: BOT_TOKEN, GUILD_ID, CHANNEL_ID\n\n### Database Connections\n- PostgreSQL: CONNECTION_STRING, USERNAME, PASSWORD\n- Redis: URL, PASSWORD, HOST, PORT\n\n### Shared Secrets\n- Tauri Signing: PRIVATE_KEY, PUBLIC_KEY, PASSPHRASE\n- Code Signing: CERTIFICATE_PATH, CERTIFICATE_PASSWORD\n- Monitoring: SENTRY_DSN, DATADOG_API_KEY\n\n## Security Best Practices\n\n### 1. Vault Access Control\n- Use separate vaults for different environments\n- Implement least-privilege access policies\n- Regularly audit vault permissions\n\n### 2. Secret Rotation\n- Rotate API keys regularly\n- Update 1Password references when secrets change\n- Monitor for deprecated or expired secrets\n\n### 3. Template Security\n- Never include hardcoded secrets in templates\n- Use only op:// references in configuration templates\n- Validate template format before deployment\n\n### 4. CI/CD Security\n- Use 1Password service accounts for automation\n- Limit service account permissions to specific vaults\n- Clean up generated configuration files after use\n\n## Troubleshooting\n\n### Common Issues\n\n#### 1Password CLI Not Authenticated\nbash\n# Sign in to 1Password\nop signin\n\n# Verify authentication\nop vault list\n\n\n#### Secret Reference Not Found\nbash\n# Check vault contents\nop item list --vault=\"Terraphim-Dev\"\n\n# Verify specific item\nop item get \"OpenRouter\" --vault=\"Terraphim-Dev\"\n\n\n#### Template Processing Failed\nbash\n# Validate template syntax\nop inject -i templates/env.terraphim.template --dry-run\n\n# Check for malformed references\ngrep -n \"op://\" templates/env.terraphim.template\n\n\n### Debug Commands\n\nbash\n# Test 1Password integration\ncargo run --bin debug-onepassword\n\n# Validate configuration templates\n./scripts/validate-templates.sh\n\n# Check secret resolution\nop run --env-file=\".env.terraphim\" -- env | grep -E '^(OPENROUTER|ANTHROPIC)'\n\n\n## Development Workflow\n\n### Local Development\n1. Install 1Password CLI and authenticate\n2. Run vault setup script: ./scripts/setup-1password-terraphim.sh dev\n3. Populate development secrets in 1Password\n4. Generate configuration: op inject -i templates/env.terraphim.template -o .env.terraphim\n5. Run application: source .env.terraphim && cargo run\n\n### Testing\n1. Use separate test vault or test-specific items\n2. Generate test configuration with mock values\n3. Run tests with isolated secrets: op run --env-file=\".env.test\" -- cargo test\n\n### Production Deployment\n1. Use production vault and service accounts\n2. Validate all secret references before deployment\n3. Deploy using CI/CD pipeline with 1Password integration\n4. Monitor for secret-related errors and alerts\n\n## Migration Guide\n\n### From Environment Variables\n1. Identify current environment variables\n2. Create corresponding 1Password items\n3. Update configuration templates with op:// references\n4. Test secret resolution in development\n5. Deploy with 1Password integration\n\n### From Configuration Files\n1. Extract sensitive values from configuration files\n2. Store values in 1Password vaults\n3. Replace sensitive values with op:// references\n4. Use op inject to generate final configuration\n5. Update deployment scripts to use template injection\n\n## Support\n\nFor issues with 1Password integration:\n1. Check this documentation for common solutions\n2. Validate 1Password CLI installation and authentication\n3. Review secret references and vault permissions\n4. Test with minimal configuration first\n5. Contact the Terraphim team for additional support\n\n---\n\nNext Steps:\n- Set up your 1Password vaults using the setup script\n- Populate secrets with real values\n- Test integration in development environment\n- Deploy with 1Password-enhanced CI/CD pipeline
  • Haystack Configuration with Extra Parameters
  • Lessons Learned
  • Progress Memories
  • Terraphim AI Project Memory
  • Current Work: Terraphim Multi-Role Agent System Testing & Production 🚀
  • Comprehensive Lessons Learned - Terraphim AI Development
  • Security Testing Patterns - Terraphim AI
  • Security Testing Lessons Learned (2025-10-07)
  • Terraphim Firecracker Project - Implementation Plan
  • Terraphim AI Security Testing Implementation - Complete
  • Terraphim AI Testing Infrastructure Improvement Plan
  • Installing Terraphim AI
  • AI Agent Onboarding Quickstart
  • Howto: Learning Capture for Claude Code
  • Howto: Learning Capture for opencode
  • Plug Terraphim Search into Claude Code and opencode
  • Personal Assistant Role: Search Email and Notes Together
  • Package Manager Replacement with Bun
  • API
  • Bug Reporting
  • bun install
  • bun
  • Case Study: Knowledge Graph Validation Workflows for Pre/Post-LLM
  • code_review_checklist
  • security_checklist
  • Configuration
  • Database
  • docker compose
  • Exit Classes
  • Generated with Terraphim AI
  • Terraphim Graph Embeddings: Learning Agent Guide
  • Graph
  • Haystack
  • https://terraphim.ai
  • Issue Tracking
  • Terraphim Knowledge Graph System
  • Knowledge Graph
  • Learning Capture System
  • Middleware
  • [email protected]
  • Terraphim KG Schema Linter
  • Search
  • Service
  • System
  • Terraphim-graph
  • Terraphim AI
  • Thesaurus
  • uv
  • uv add
  • Knowledge Graph Bug Reporting Enhancement
  • Learning Compile
  • Listener Shell Dispatch
  • MCP Integration
  • OpenRouter AI-Powered Article Summarization
  • Release Channels
  • Release Process for Terraphim AI
  • Design: PageRank Bug Fixes for Gitea Robot API
  • Research: PageRank Computation Bug in Gitea Robot API
  • Research Document: TypeScript Bindings for TLA+
  • Design Document: TypeScript Bindings for TLA+
  • Title-Scorer
  • BM25 Scorers
  • Terraphim Graph Embeddings vs Cleora
  • Terraphim Graph scorer
  • Terraphim vs OpenClaw: Search Architecture Comparison
  • Terraphim Search Architecture
  • Symphony Orchestrator
  • Test KG Auto-linking Demo
  • Relationship between Aircraft and Crew
  • Comprehensive Testing Strategies for Terraphim
  • Desktop Testing
  • Chat Layout Responsive Design Test Plan
  • Desktop Frontend Testing Guide
  • Knowledge Graph Ranking Expansion Testing
  • MCP Integration Testing
  • Testing Overview
  • Terraphim AI Agent Evolution System - Testing Matrix
  • TypeScript Bindings with tsify
  • Terraphim TUI
  • Terraphim AI Agent Workflow Patterns Guide
  • Decision Tier
  • Implementation Tier
  • Planning Tier
  • Review Tier
  • Runner Command Policy
  • Setting Up Telegram Bot with TinyClaw
  • Enabling terraphim-grep Offline (lessons learned)
  • Terraphim TUI Features
  • Terraphim Terminal User Interface (TUI)
  • Terraphim AI Update Signing Keys
  • Getting Started with Terraphim AI
  • Installation Guide
  • Quick Start Guide
  • Quickwit Log Exploration Guide
  • Troubleshooting Guide
  • Documentation Validation Plan
  • Validation Report: Learning Capture System
  • Vendor API Drift Report - Echo/Twin Maintainer
  • Phase 5 Verification Documentation Index
  • Verification Report: Learning Capture System
  • Verification Report: Word Boundary Matching (#395)
  • VM Allocation Architecture - Visual Verification
  • Vibe-Rules
  • Documentation Standards
  • Global Naming Conventions
  • Rust Async Programming Patterns
  • Rust Error Handling Patterns
  • Creating a Front-End Developer Agent with Terraphim
  • weather-report-2026-06-23

Release Domain

This section covers release processes, signing/notarization, and changelog history.

What belongs here

  • Release pipeline and tooling
  • Artifact signing and verification
  • Versioning and changelog

Reports

  • Final Validation Status (v1.0.0)

Case studies

  • v1.0.0 CI + Validation Case Study
  • Case Studies Index
Desktop Domain Final Validation Status (v1.0.0)

© 2026 Terraphim AI documentation. Built with md-book.

GitHub