{"id":15154147,"url":"https://github.com/terraphim/terraphim-ai","last_synced_at":"2026-04-06T21:02:02.971Z","repository":{"id":197258728,"uuid":"698304144","full_name":"terraphim/terraphim-ai","owner":"terraphim","description":"Terraphim AI: deterministic AI Assistant","archived":false,"fork":false,"pushed_at":"2026-04-02T15:54:33.000Z","size":483073,"stargazers_count":36,"open_issues_count":167,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-03T03:21:14.522Z","etag":null,"topics":["ai","graph-embeddings","rust","rust-lang","svelte","tauri","tauri-app"],"latest_commit_sha":null,"homepage":"https://terraphim.ai","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/terraphim.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-Apache-2.0","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2023-09-29T15:59:32.000Z","updated_at":"2026-04-02T15:54:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"c288ad78-0555-4161-a7a1-2b544a191739","html_url":"https://github.com/terraphim/terraphim-ai","commit_stats":{"total_commits":286,"total_committers":4,"mean_commits":71.5,"dds":"0.48601398601398604","last_synced_commit":"e5e73413bd8a517ced689e584b7f0c6dcfe4e0f0"},"previous_names":["terraphim/terraphim-ai"],"tags_count":66,"template":false,"template_full_name":null,"purl":"pkg:github/terraphim/terraphim-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terraphim%2Fterraphim-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terraphim%2Fterraphim-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terraphim%2Fterraphim-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terraphim%2Fterraphim-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/terraphim","download_url":"https://codeload.github.com/terraphim/terraphim-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/terraphim%2Fterraphim-ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31489427,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T17:22:55.647Z","status":"ssl_error","status_checked_at":"2026-04-06T17:22:54.741Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","graph-embeddings","rust","rust-lang","svelte","tauri","tauri-app"],"created_at":"2024-09-26T17:03:17.610Z","updated_at":"2026-04-06T21:02:02.949Z","avatar_url":"https://github.com/terraphim.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Terraphim AI Assistant\n\n[![Crates.io](https://img.shields.io/crates/v/terraphim_agent.svg)](https://crates.io/crates/terraphim_agent)\n[![Homebrew](https://img.shields.io/badge/homebrew-terraphim-orange?logo=homebrew)](https://github.com/terraphim/homebrew-terraphim)\n[![npm](https://img.shields.io/npm/v/@terraphim/autocomplete.svg)](https://www.npmjs.com/package/@terraphim/autocomplete)\n[![PyPI](https://img.shields.io/pypi/v/terraphim-automata.svg)](https://pypi.org/project/terraphim-automata/)\n[![Discord](https://img.shields.io/discord/852545081613615144?label=Discord\u0026logo=Discord)](https://discord.gg/VPJXB6BGuY)\n[![Discourse](https://img.shields.io/discourse/users?server=https%3A%2F%2Fterraphim.discourse.group)](https://terraphim.discourse.group)\n[![Crates.io](https://img.shields.io/crates/v/terraphim-repl.svg)](https://crates.io/crates/terraphim-repl)\n\nTerraphim is a privacy-first AI assistant that works for you under your complete control and is fully deterministic.\n\n## 🆕 v1.0.0 Minimal Release - NOW AVAILABLE!\n\n**Quick Install** (works on Linux, macOS, Windows):\n\n**Option 1: Universal Installer** (recommended)\n```bash\n# Single command installation with platform detection\ncurl -fsSL https://raw.githubusercontent.com/terraphim/terraphim-ai/main/scripts/install.sh | bash\n\n# Install both agent and CLI tools\ncurl -fsSL https://raw.githubusercontent.com/terraphim/terraphim-ai/main/scripts/install.sh | bash --with-cli\n```\n\n**Option 2: Homebrew** (macOS/Linux - recommended)\n```bash\n# Add Terraphim tap\nbrew tap terraphim/terraphim\n\n# Install server\nbrew install terraphim-server\n\n# Install TUI/REPL\nbrew install terraphim-agent\n```\n\n**Option 3: Cargo Install**\n```bash\ncargo install terraphim-repl    # Interactive REPL (11 commands)\ncargo install terraphim-cli     # Automation CLI (8 commands)\n```\n\n**Features**:\n- 🔍 Semantic knowledge graph search\n- 🔗 Smart text linking (markdown/html/wiki)\n- 💾 Offline-capable (embedded defaults)\n- ⚡ Lightweight (15 MB RAM, 13 MB disk)\n- 🚀 Fast (\u003c200ms operations)\n\n**Learn more**: [Quickstart](QUICKSTART.md) | [Changelog](https://docs.terraphim.ai/src/changelog.html) | [Cross-Platform Guide](docs/archive/root/CROSS_PLATFORM_STATUS.md)\n\nYou can use it as a local search engine, configured to search for different types of content on StackOverflow, GitHub, and the local filesystem using a predefined folder, which includes your Markdown files.\n\nTerraphim operates on local infrastructure and works exclusively for the owner's benefit.\n\n## 🎉 v1.0.0 Major Release\n\nWe're excited to announce Terraphim AI v1.0.0 with comprehensive multi-language support:\n\n### ✨ New Packages Available\n- **🦀 Rust**: `terraphim_agent` - Complete CLI and TUI interface via crates.io\n- **📦 Node.js**: `@terraphim/autocomplete` - Native npm package with autocomplete and knowledge graph\n- **🐍 Python**: `terraphim-automata` - High-performance text processing library via PyPI\n\n### 🚀 Quick Installation\n\n**Universal Installer (Recommended)**\n```bash\n# Single command installation for all platforms\ncurl -fsSL https://raw.githubusercontent.com/terraphim/terraphim-ai/main/scripts/install.sh | bash\n```\n\n**Package Managers**\n```bash\n# Homebrew (macOS/Linux - signed \u0026 notarized binaries)\nbrew tap terraphim/terraphim\nbrew install terraphim-server  # HTTP API server\nbrew install terraphim-agent   # TUI/REPL interface\n\n# Rust CLI (interactive TUI)\ncargo install terraphim_agent\n\n# Node.js package (autocomplete + knowledge graph)\nnpm install @terraphim/autocomplete\n\n# Python library (high-performance text processing)\npip install terraphim-automata\n```\n\nhttps://github.com/terraphim/terraphim-ai/assets/175809/59c74652-bab4-45b2-99aa-1c0c9b90196b\n\n\n## Why Terraphim?\n\nThere are growing concerns about the privacy of data and the sharing of individuals' data across an ever-growing list of services, some of which have questionable data ethics policies. \u003csup\u003e[1],[2],[3],[4]\u003c/sup\u003e\n\n**Individuals struggle to find relevant information in different knowledge repositories:**\n\n- Personal ones like Roam Research, Obsidian, Coda, and Notion.\n- Team-focused ones like Jira, Confluence, and SharePoint.\n- Public sources such as StackOverflow and GitHub.\n\nTerraphim aims to bridge this gap by providing a privacy-first AI assistant that operates locally on the user's hardware, enabling seamless access to various knowledge repositories without compromising privacy. With Terraphim, users can efficiently search personal, team-focused, and public knowledge sources, ensuring that their data remains under their control at all times.\n\n[1]: https://www.coveo.com/en/resources/reports/relevance-report-workplace\n[2]: https://cottrillresearch.com/various-survey-statistics-workers-spend-too-much-time-searching-for-information/\n[3]: https://www.forbes.com/sites/forbestechcouncil/2019/12/17/reality-check-still-spending-more-time-gathering-instead-of-analyzing/\n[4]: https://www.theatlantic.com/technology/archive/2021/06/the-internet-is-a-collective-hallucination/619320/\n\n## 🚀 Getting Started\n\n### Option 1: Install from Package Managers (Recommended)\n\n#### 🦀 Rust CLI/TUI (Most Features)\n```bash\n# Basic installation\ncargo install terraphim_agent\n\n# Full installation with session search support\ncargo install terraphim_agent --features repl-full\n\nterraphim-agent --help\n```\n\n#### 📦 Node.js Package (Autocomplete + Knowledge Graph)\n```bash\nnpm install @terraphim/autocomplete\n# or with Bun\nbun add @terraphim/autocomplete\n```\n\n#### 🐍 Python Library (Text Processing)\n```bash\npip install terraphim-automata\n```\n\n### Option 2: Development Setup\n\n1. **Clone the repository**:\n   ```bash\n   git clone https://github.com/terraphim/terraphim-ai.git\n   cd terraphim-ai\n   ```\n\n2. **Set up development environment**:\n   ```bash\n   # Install Git hooks for code quality (optional but recommended)\n   ./scripts/install-hooks.sh\n   ```\n\n3. **Start the backend server**:\n   ```bash\n   cargo run\n   ```\n   This starts an API endpoint for indexing and querying documents.\n\n4. **Run the frontend** (choose one):\n\n   **Web Frontend:**\n   ```bash\n   cd desktop\n   yarn install\n   yarn run dev\n   ```\n\n   **Desktop App (Tauri):**\n   ```bash\n   cd desktop\n   yarn install\n   yarn run tauri dev\n   ```\n\n   **Terminal Interface (Agent):**\n   ```bash\n   # Build with all features (recommended)\n   cargo build -p terraphim_agent --features repl-full --release\n   ./target/release/terraphim-agent\n\n   # Or run minimal version\n   cargo run -p terraphim_agent --bin terraphim-agent\n   ```\n\n(See the [desktop README](desktop/README.md), [TUI documentation](docs/tui-usage.md), and [development setup guide](docs/src/development-setup.md) for more details.)\n\n## 📚 Usage Examples\n\n### 🦀 Rust CLI/TUI\n```bash\n# Fullscreen TUI (requires a running server at TERRAPHIM_SERVER or localhost:8000)\nterraphim-agent\n\n# Offline-capable REPL\nterraphim-agent repl\n\n# Search commands\nterraphim-agent search \"Rust async programming\"\nterraphim-agent search --role engineer \"microservices\"\n\n# Chat with AI\nterraphim-agent chat \"Explain knowledge graphs\"\n\n# Commands list\nterraphim-agent commands list\nterraphim-agent commands search \"Rust\"\n\n# Auto-update management\nterraphim-agent check-update    # Check for updates without installing\nterraphim-agent update          # Update to latest version if available\n```\n\n### 📦 Node.js Package\n```javascript\n// Import the package\nimport * as autocomplete from '@terraphim/autocomplete';\n\n// Build autocomplete index from JSON thesaurus\nconst thesaurus = {\n  \"name\": \"Engineering\",\n  \"data\": {\n    \"machine learning\": {\n      \"id\": 1,\n      \"nterm\": \"machine learning\",\n      \"url\": \"https://example.com/ml\"\n    }\n  }\n};\n\nconst indexBytes = autocomplete.buildAutocompleteIndexFromJson(JSON.stringify(thesaurus));\n\n// Search for terms\nconst results = autocomplete.autocomplete(indexBytes, \"machine\", 10);\nconsole.log('Autocomplete results:', results);\n\n// Knowledge graph operations\nconst graphBytes = autocomplete.buildRoleGraphFromJson(\"Engineer\", JSON.stringify(thesaurus));\nconst isConnected = autocomplete.areTermsConnected(graphBytes, \"machine learning\");\nconsole.log('Terms connected:', isConnected);\n```\n\n### 🐍 Python Library\n```python\nimport terraphim_automata as ta\n\n# Create thesaurus\nthesaurus = ta.Thesaurus(name=\"Engineering\")\nthesaurus.add_term(\"machine learning\", url=\"https://example.com/ml\")\nthesaurus.add_term(\"deep learning\", url=\"https://example.com/dl\")\n\n# Build autocomplete index\nindex = ta.build_autocomplete_index(thesaurus)\nprint(f\"Index size: {len(index)} bytes\")\n\n# Search for terms\nresults = ta.autocomplete(index, \"machine\", limit=10)\nfor result in results:\n    print(f\"Found: {result.term} (score: {result.score})\")\n\n# Fuzzy search\nfuzzy_results = ta.fuzzy_autocomplete_search(index, \"machin\", min_distance=0.8)\nprint(f\"Fuzzy results: {len(fuzzy_results)}\")\n```\n\n### 📊 Quickwit Log Search\n```bash\n# Search application logs with Quickwit integration\nterraphim-agent --config terraphim_server/default/quickwit_engineer_config.json\n\n# In REPL, search for errors\n\u003e /search \"level:ERROR\"\n\n# Time-based search\n\u003e /search \"timestamp:[2024-01-13T10:00:00Z TO *]\"\n\n# Multi-field search\n\u003e /search \"service:api-server AND (error OR timeout)\"\n\n# Auto-discovery mode (searches all indexes)\nterraphim-agent --config terraphim_server/default/quickwit_autodiscovery_config.json\n\u003e /search error\n\n# With authentication (production)\nexport QUICKWIT_PASSWORD=$(op read \"op://Private/Quickwit/password\")\nterraphim-agent --config terraphim_server/default/quickwit_production_config.json\n\u003e /search \"database connection failed\"\n```\n\n**Complete Example:** See [examples/quickwit-log-search.md](examples/quickwit-log-search.md) for incident investigation walkthrough.\n\n## 🆕 v1.0.0 Features\n\n### 🔍 Enhanced Search Capabilities\n- **Grep.app Integration**: Search across 500,000+ GitHub repositories\n- **Advanced Filtering**: Language, repository, and path-based filtering\n- **Semantic Search**: Knowledge graph-powered semantic understanding\n\n### 📊 Multi-Language Support\n- **Rust**: Native performance with complete CLI/TUI interface\n- **Node.js**: High-performance autocomplete with native bindings\n- **Python**: Fast text processing and autocomplete algorithms\n\n### 🤖 AI Integration\n- **MCP Server**: Model Context Protocol for AI tool integration\n- **Claude Code Hooks**: Automated development workflows\n- **Knowledge Graphs**: Semantic relationship analysis and discovery\n\n### 🔄 Auto-Update System\n- **Seamless Updates**: Self-updating CLI using GitHub Releases\n- **Cross-Platform**: Works on Linux, macOS, and Windows\n- **Smart Versioning**: Intelligent version comparison and update detection\n- **Progress Tracking**: Real-time download progress and status indicators\n\n## Terminal Agent Interface\n\nTerraphim includes a comprehensive terminal agent that provides both interactive REPL functionality and CLI commands for advanced operations:\n\n### Key Features\n\n- **🤖 AI Chat Integration**: OpenRouter and Ollama support for intelligent conversations\n- **⚡ Sub-2 Second VM Boot**: Advanced VM optimization system with sub-500ms allocation\n- **🖥️ Enhanced VM Management**: Firecracker microVM pools with intelligent allocation\n- **📝 Markdown Command System**: Extensible commands defined in YAML frontmatter\n- **🔒 Security-First Execution**: Three execution modes (Local, Firecracker, Hybrid) with knowledge graph validation\n- **🌐 Web Operations**: Secure web requests through VM sandboxing\n- **📁 File Operations**: Semantic file analysis and intelligent content management\n- **🔍 Knowledge Graph**: Interactive rolegraph visualization and navigation\n- **⚙️ Configuration**: Real-time role and configuration management\n- **🔄 Auto-Update**: Seamless self-updating mechanism using GitHub Releases\n\n### 🔄 Auto-Update System\n\nTerraphim-agent includes a built-in auto-update system that keeps your installation current with the latest releases from GitHub.\n\n#### Features\n- **🚀 Seamless Updates**: Automatic binary replacement without manual intervention\n- **📊 Progress Tracking**: Real-time download progress and status indicators\n- **🔒 Secure Verification**: GitHub Releases integration ensures authenticated updates\n- **🌐 Cross-Platform**: Works on Linux, macOS, and Windows\n- **📋 Version Intelligence**: Smart version comparison and update availability detection\n\n#### Usage\n\n```bash\n# Check for updates without installing\nterraphim-agent check-update\n\n# Update to latest version if available\nterraphim-agent update\n\n# Get help for update commands\nterraphim-agent check-update --help\nterraphim-agent update --help\n```\n\n#### Update Status Messages\n\n- **🔍 Checking**: \"🔍 Checking for terraphim-agent updates...\"\n- **✅ Up-to-date**: \"✅ Already running latest version: X.Y.Z\"\n- **📦 Update Available**: \"📦 Update available: X.Y.Z → A.B.C\"\n- **🚀 Updated**: \"🚀 Updated from X.Y.Z to A.B.C\"\n- **❌ Failed**: \"❌ Update failed: [error details]\"\n\n#### Technical Details\n\n- **Source**: GitHub Releases from `terraphim/terraphim-ai` repository\n- **Mechanism**: Rust `self_update` crate with secure binary verification\n- **Architecture**: Async-safe implementation using `tokio::task::spawn_blocking`\n- **Compatibility**: Requires internet connectivity for update checks\n\n#### Example Workflow\n\n```bash\n$ terraphim-agent check-update\n🔍 Checking for terraphim-agent updates...\n📦 Update available: 1.0.0 → 1.0.1\n\n$ terraphim-agent update\n🚀 Updating terraphim-agent...\n✅ Already running latest version: 1.0.1\n```\n\n### Quick Start\n\n```bash\n# Build with all features\ncargo build -p terraphim_agent --features repl-full --release\n\n# Launch fullscreen TUI (server-backed)\n./target/release/terraphim-agent\n\n# Launch REPL (offline-capable by default)\n./target/release/terraphim-agent repl\n\n# Available REPL commands:\n/help           # Show all commands\n/search \"query\" # Semantic search\n/chat \"message\" # AI conversation\n/commands list  # List available markdown commands\n/deploy staging # Execute deployment (Firecracker mode)\n/search \"TODO\"  # Execute search command (Local mode)\n/vm list        # VM management with sub-2s boot\n/web get URL    # Web operations\n/file search    # Semantic file operations\n\n# Session search commands (requires repl-full feature):\n/sessions sources          # Detect available session sources\n/sessions import           # Import sessions from Claude Code, Cursor, Aider\n/sessions list             # List imported sessions\n/sessions search \u003cquery\u003e   # Full-text search across sessions\n/sessions stats            # Show session statistics\n/sessions concepts \u003cterm\u003e  # Knowledge graph concept search\n/sessions related \u003cid\u003e     # Find related sessions\n/sessions timeline         # Timeline visualization\n/sessions export           # Export to JSON/Markdown\n```\n\nFor detailed documentation, see [TUI Usage Guide](docs/tui-usage.md) and [Auto-Update System](docs/autoupdate.md).\n\n### Session Search\n\nSearch across AI coding assistant history from Claude Code, Cursor, and Aider sessions:\n\n```bash\n# Install with session search support\ncargo install terraphim_agent --features repl-full\n\n# Launch REPL (offline-capable)\nterraphim-agent repl\n\n# In REPL:\n/sessions sources          # Detect available session sources (e.g., 419 Claude Code sessions)\n/sessions import           # Import sessions from all sources\n/sessions list             # List imported sessions with ID, source, title, message count\n/sessions search \"rust\"    # Full-text search across sessions\n/sessions stats            # Show statistics (total sessions, messages, breakdown by source)\n/sessions concepts \"async\" # Knowledge graph concept search\n/sessions related \u003cid\u003e     # Find related sessions by shared concepts\n/sessions timeline         # Timeline visualization grouped by day/week/month\n/sessions export           # Export to JSON or Markdown\n```\n\n**Supported Sources:**\n- Claude Code (`~/.claude/projects/`)\n- Cursor IDE sessions\n- Aider git-based conversation logs\n\n## Terminology\n\nWhen configuring or working on Terraphim, you will encounter the following\nterms and concepts:\n\n- **Haystack**: A data source that Terraphim can search through. For example, this\n  could be a folder on your computer, a Notion workspace, or your email account.\n- **Knowledge Graph**: A structured graph of information created from a\n  haystack, where nodes represent entities and edges represent relationships\n  between them.\n- **Profile**: An endpoint for persisting user data (e.g. Amazon S3, sled, or\n  rocksdb).\n- **Role**: A role is a set of settings that define the default behavior of the\n  AI assistant. For example, a developer role will search for code-related\n  content, while a \"father\" role might search for parenting-related content. Each\n  Terraphim role has its own separate knowledge graph that contains relevant\n  concepts, with all synonyms.\n- **Rolegraph**: A structure for ingesting documents into Terraphim. It is a knowledge\n  graph that uses a scoring function (an Aho-Corasick automata build from the\n  knowledge graph) for ranking results.\n\n## Why \"Terraphim\"?\n\nThe term is originally taken from the [Relict series][relict] of science fiction\nnovels by [Vasiliy Golovachev](https://en.wikipedia.org/wiki/Vasili_Golovachov).\nTerraphim is an artificial intelligence living inside a spacesuit (part of an\nexocortex), or inside your house or vehicle, and it is designed to help you with\nyour tasks. You can carry it around with you.\nSimilar entities now common in science fiction, for example Destiny 2 has entity called [Ghost][ghost].\n\n\nOr in Star Wars Jedi Survivor there is an AI assistant [BD-1][bd-1].\n\nThe compactness and mobility of such AI assistant drives the [[Design Decisions]] of Terraphim.\n\n[bd-1]: https://starwars.fandom.com/wiki/BD-1\n[ghost]: https://www.destinypedia.com/Ghost\n[relict]: https://www.goodreads.com/en/book/show/196710046\n\nTerraphim is a trademark registered in the UK, US and internationally (WIPO). All other trademarks mentioned above are the property of their respective owners.\n\n## 🔒 Validation Framework\n\nTerraphim includes a comprehensive validation system that ensures security, quality, and compliance across all AI operations.\n\n### 🛡️ Runtime Validation Hooks\n\n**Two-Stage Security Flow**:\n1. **Guard Stage**: Blocks dangerous operations (e.g., `git commit --no-verify`)\n2. **Replacement Stage**: Enhances commands using knowledge graph intelligence\n\n**Hook Coverage**:\n- **Pre/Post LLM**: Validates AI inputs/outputs for safety and quality\n- **Pre/Post Tool**: Secures code execution in VM environments\n- **Claude Code Integration**: Seamless workflow validation with guard+replacement\n\n**Configuration**: `~/.config/terraphim/runtime-validation.toml`\n```toml\n[hooks]\nenabled = true\nfail_open = true          # Development mode\n\n[guard]\nstrict_mode = false        # Balance security vs. productivity\n\n[llm_hooks]\nenabled = true\nrequire_human_review = false\n\n[tool_hooks]\nenabled = true\nvm_isolation = true\n```\n\n### 📋 Release Validation\n\nComprehensive release testing and validation system:\n- **Multi-Platform Testing**: Windows, macOS, Linux validation\n- **Security Scanning**: Automated vulnerability assessment\n- **Performance Benchmarking**: CI/CD integrated performance tests\n- **Installation Testing**: Package installation verification\n- **Functional Testing**: End-to-end feature validation\n\n**Usage**:\n```bash\n# Run complete release validation\nterraphim-validation validate --version v1.5.0\n\n# Run specific validation categories\nterraphim-validation validate --categories security,performance\n\n# Generate validation report\nterraphim-validation status --report-format json\n```\n\n**Documentation**: See [Runtime Validation Hooks](.docs/runtime-validation-hooks.md) for detailed implementation guide.\n\n### Development with Validation\n\nDuring development, hooks operate in fail-open mode to avoid blocking workflows:\n```bash\n# Development configuration\nexport TERRAPHIM_RUNTIME_VALIDATION_HOOKS=true\nexport TERRAPHIM_FAIL_OPEN=true\nexport TERRAPHIM_GUARD_STAGE=true\nexport TERRAPHIM_REPLACEMENT_STAGE=true\n```\n\n## Configuration\n\n### Storage Backends\n\nTerraphim supports multiple storage backends for different deployment scenarios:\n\n#### Local Development (Default)\nThe system uses local storage backends by default, requiring no additional configuration:\n- **Memory**: In-memory storage for testing\n- **DashMap**: High-performance concurrent storage\n- **SQLite**: Local database storage\n- **ReDB**: Embedded key-value database\n\n#### Cloud Storage (Optional)\nFor production deployments, you can optionally enable cloud storage:\n\n##### AWS S3 Configuration\nTo use AWS S3 storage, set the following environment variables:\n```bash\nexport AWS_ACCESS_KEY_ID=\"your-access-key\"\nexport AWS_SECRET_ACCESS_KEY=\"your-secret-key\"\nexport TERRAPHIM_PROFILE_S3_REGION=\"us-east-1\"\nexport TERRAPHIM_PROFILE_S3_ENDPOINT=\"https://s3.amazonaws.com/\"\n```\n\n**Note**: AWS credentials are completely optional. The system will automatically fall back to local storage if AWS credentials are not available, ensuring local development works without any cloud dependencies.\n\n### Environment Variables\n- `TERRAPHIM_SETTINGS_PATH`: Override the settings file path\n- `TERRAPHIM_DATA_PATH`: Set the data directory location\n- `LOG_LEVEL`: Set logging verbosity (debug, info, warn, error)\n\n## Installation Methods\n\n### For End Users\n\n#### Homebrew (macOS/Linux)\n```bash\nbrew install terraphim/terraphim-ai/terraphim-ai\n```\nThis installs the server, terminal agent, and desktop app (macOS only).\n\n#### Debian/Ubuntu\n```bash\n# Download from GitHub releases\nsudo dpkg -i terraphim-server_*.deb\nsudo dpkg -i terraphim-agent_*.deb\nsudo dpkg -i terraphim-ai-desktop_*.deb\n```\n\n#### Docker\n```bash\ndocker run ghcr.io/terraphim/terraphim-server:latest\n```\n\n#### Direct Download\nDownload pre-built binaries from [GitHub Releases](https://github.com/terraphim/terraphim-ai/releases).\n\n### Development Setup\n\nFor development, see our comprehensive [Development Setup Guide](docs/src/development-setup.md) which covers:\n- Code quality tools and pre-commit hooks\n- Multiple installation options (no Python required!)\n- IDE integration and troubleshooting\n\n## Claude Code Integration\n\nTerraphim provides seamless integration with Claude Code through hooks, skills, and the terraphim-agent CLI.\n\n### Quick Setup (User-Level)\n\n**Step 1: Install terraphim-agent**\n```bash\n# macOS ARM64 (Apple Silicon)\ngh release download --repo terraphim/terraphim-ai \\\n  --pattern \"terraphim-agent-aarch64-apple-darwin\" --dir /tmp\nchmod +x /tmp/terraphim-agent-aarch64-apple-darwin\nmv /tmp/terraphim-agent-aarch64-apple-darwin ~/.cargo/bin/terraphim-agent\n\n# macOS x86_64 (Intel)\ngh release download --repo terraphim/terraphim-ai \\\n  --pattern \"terraphim-agent-x86_64-apple-darwin\" --dir /tmp\nchmod +x /tmp/terraphim-agent-x86_64-apple-darwin\nmv /tmp/terraphim-agent-x86_64-apple-darwin ~/.cargo/bin/terraphim-agent\n\n# Linux x86_64\ngh release download --repo terraphim/terraphim-ai \\\n  --pattern \"terraphim-agent-x86_64-unknown-linux-gnu\" --dir /tmp\nchmod +x /tmp/terraphim-agent-x86_64-unknown-linux-gnu\nmv /tmp/terraphim-agent-x86_64-unknown-linux-gnu ~/.cargo/bin/terraphim-agent\n```\n\n**Note:** For full functionality including `hook`, `guard`, and session search commands, install with features:\n```bash\ncargo install terraphim_agent --features repl-full\n```\n\n**Step 2: Install Claude Code Skills Plugin**\n```bash\nclaude plugin marketplace add terraphim/terraphim-skills\nclaude plugin install terraphim-engineering-skills@terraphim-skills\n```\n\n**Step 3: Configure User-Level Hooks**\n\nAdd to `~/.claude/settings.local.json`:\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [{\n      \"matcher\": \"Bash\",\n      \"hooks\": [{\n        \"type\": \"command\",\n        \"command\": \"~/.claude/hooks/pre_tool_use.sh\"\n      }]\n    }]\n  }\n}\n```\n\nCreate `~/.claude/hooks/pre_tool_use.sh`:\n```bash\n#!/bin/bash\nset -euo pipefail\nINPUT=$(cat)\nTOOL_NAME=$(echo \"$INPUT\" | jq -r '.tool_name // empty')\nCOMMAND=$(echo \"$INPUT\" | jq -r '.tool_input.command // empty')\n\n[ \"$TOOL_NAME\" != \"Bash\" ] \u0026\u0026 exit 0\n[ -z \"$COMMAND\" ] \u0026\u0026 exit 0\n\nAGENT=\"$HOME/.cargo/bin/terraphim-agent\"\n[ ! -x \"$AGENT\" ] \u0026\u0026 exit 0\n\n# Git Safety Guard - block destructive commands\nGUARD=$($AGENT guard --json \u003c\u003c\u003c \"$COMMAND\" 2\u003e/dev/null || echo '{\"decision\":\"allow\"}')\nif echo \"$GUARD\" | jq -e '.decision == \"block\"' \u003e/dev/null 2\u003e\u00261; then\n    REASON=$(echo \"$GUARD\" | jq -r '.reason')\n    echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"BLOCKED: '\"$REASON\"'\"}}'\n    exit 0\nfi\n\n# Knowledge graph replacement\ncd ~/.config/terraphim 2\u003e/dev/null \u0026\u0026 $AGENT hook --hook-type pre-tool-use --json \u003c\u003c\u003c \"$INPUT\" 2\u003e/dev/null\n```\n\n```bash\nmkdir -p ~/.claude/hooks \u0026\u0026 chmod +x ~/.claude/hooks/pre_tool_use.sh\n```\n\n**Step 4: Set Up Knowledge Graph**\n```bash\nmkdir -p ~/.config/terraphim/docs/src/kg\n\ncat \u003e ~/.config/terraphim/docs/src/kg/bun_install.md \u003c\u003c 'EOF'\n# bun install\nsynonyms:: npm install, yarn install, pnpm install\nEOF\n```\n\n### Features\n\n| Feature | Command | Description |\n|---------|---------|-------------|\n| **Git Safety Guard** | `terraphim-agent guard` | Blocks destructive commands (git reset --hard, rm -rf, etc.) |\n| **Text Replacement** | `terraphim-agent replace` | Knowledge graph-based text substitution |\n| **Hook Integration** | `terraphim-agent hook` | Claude Code PreToolUse/PostToolUse hooks |\n\n### Verification\n```bash\n# Test guard\necho \"git reset --hard\" | terraphim-agent guard --json\n# {\"decision\":\"block\",\"reason\":\"git reset --hard destroys uncommitted changes...\"}\n\n# Test replacement\ncd ~/.config/terraphim \u0026\u0026 echo \"npm install\" | terraphim-agent replace\n# bun install\n```\n\n📖 **Full Documentation**: [terraphim-skills README](https://github.com/terraphim/terraphim-skills)\n\n### 🔄 Text Replacement (Hooks \u0026 Skills)\n\nUse Terraphim's knowledge graph capabilities to automatically replace text patterns in your development workflow:\n\n**Claude Code Hooks** - Automatic, transparent replacements:\n```bash\n# Example: Automatically replace npm with bun\necho \"npm install\" | terraphim-agent replace\n# Output: bun install\n```\n\n**Claude Skills** - Context-aware, conversational assistance:\n- Works across all Claude platforms\n- Provides explanations and reasoning\n- Progressive disclosure of functionality\n\n**Examples:**\n- Package manager enforcement (npm/yarn/pnpm -\u003e bun)\n- Attribution replacement (Claude Code -\u003e Terraphim AI)\n- Custom domain-specific replacements\n\n📖 **Complete Guide**: [examples/TERRAPHIM_CLAUDE_INTEGRATION.md](examples/TERRAPHIM_CLAUDE_INTEGRATION.md)\n\n### 📊 Codebase Quality Evaluation\n\nEvaluate whether AI agents (Claude Code, GitHub Copilot, autonomous agents) improve or deteriorate your codebase using deterministic, knowledge graph-based assessment:\n\n**Key Features:**\n- **Deterministic**: Aho-Corasick automata for consistent scoring\n- **Privacy-First**: All evaluation runs locally\n- **Multi-Dimensional**: Security, performance, quality perspectives\n- **CI/CD Ready**: Automated quality gates with exit codes\n\n**Quick Start:**\n```bash\ncd examples/codebase-evaluation\n./scripts/evaluate-ai-agent.sh /path/to/codebase\n\n# Generates verdict:\n# ✅ IMPROVEMENT: The AI agent improved the codebase quality.\n# - Improved metrics: 3\n# - Deteriorated metrics: 0\n```\n\n**Evaluation Metrics:**\n- Clippy warnings, anti-patterns, TODO counts\n- Knowledge graph density and semantic matches\n- Test pass rates and code coverage\n- Custom domain-specific patterns\n\n**Use Cases:**\n1. Evaluate PRs from AI agents before merge\n2. Continuous quality monitoring in CI/CD pipelines\n3. Historical trend analysis across evaluations\n4. Multi-role evaluation (security + performance + quality)\n\n📖 **Complete Documentation**: [examples/codebase-evaluation/](examples/codebase-evaluation/)\n\n**Example GitHub Actions Integration:**\n```yaml\n- name: Baseline evaluation\n  run: ./scripts/baseline-evaluation.sh ${{ github.workspace }}\n- name: Apply AI changes\n  run: # Your AI agent step\n- name: Post-change evaluation\n  run: ./scripts/post-evaluation.sh ${{ github.workspace }}\n- name: Generate verdict (fails on deterioration)\n  run: ./scripts/compare-evaluations.sh\n```\n\n## Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. **Read our guides**:\n   - [Contributing guide](CONTRIBUTING.md)\n   - [Development setup](docs/src/development-setup.md)\n\n2. **Set up your environment**:\n   ```bash\n   git clone https://github.com/terraphim/terraphim-ai.git\n   cd terraphim-ai\n   ./scripts/install-hooks.sh  # Sets up code quality tools\n   ```\n\n3. **Code quality standards**:\n   - All commits must follow [Conventional Commits](https://www.conventionalcommits.org/)\n   - Rust code is automatically formatted with `cargo fmt`\n   - JavaScript/TypeScript uses [Biome](https://biomejs.dev/) for linting and formatting\n   - No secrets or large files allowed in commits\n\n4. **Make your changes**:\n   - Create a feature branch: `git checkout -b feat/your-feature`\n   - Make your changes with proper tests\n   - Commit with conventional format: `git commit -m \"feat: add amazing feature\"`\n   - Push and create a Pull Request\n\n### Dependency Management\n\n**Important**: Some dependencies are pinned to specific versions to ensure compatibility:\n\n- `wiremock = \"0.6.4\"` - Version 0.6.5 uses unstable Rust features requiring nightly compiler\n- `schemars = \"0.8.22\"` - Version 1.0+ introduces breaking API changes\n- `thiserror = \"1.0.x\"` - Version 2.0+ requires code migration for breaking changes\n\nThese constraints are enforced in `.github/dependabot.yml` to prevent automatic updates that would break CI. Future upgrades require manual code migration work.\n\n### Contributors are awesome\n\u003ca href=\"https://github.com/terraphim/terraphim-ai/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=terraphim/terraphim-ai\" /\u003e\n\u003c/a\u003e\n\n\n\n## License\n\nThis project is licensed under the [Apache license](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterraphim%2Fterraphim-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fterraphim%2Fterraphim-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fterraphim%2Fterraphim-ai/lists"}