{"id":47611864,"url":"https://github.com/blackaxgit/clx","last_synced_at":"2026-05-03T01:11:25.917Z","repository":{"id":341451522,"uuid":"1169773708","full_name":"blackaxgit/clx","owner":"blackaxgit","description":"🛡️ Rust CLI extension for Claude Code — LLM-powered command validation, SQLite context persistence \u0026 MCP tools. Two-layer safety (rules + Ollama), vector semantic search, and user-adaptive learning.","archived":false,"fork":false,"pushed_at":"2026-03-26T03:43:57.000Z","size":278,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T22:57:46.096Z","etag":null,"topics":["ai","claude-code","cli","command-validation","context-persistence","developer-tools","hooks","llm","mcp","mcp-server","ollama","rust","security","sqlite","vector-search"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blackaxgit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":null,"dco":null,"cla":null}},"created_at":"2026-03-01T07:25:52.000Z","updated_at":"2026-03-26T03:44:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/blackaxgit/clx","commit_stats":null,"previous_names":["blackaxgit/clx"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/blackaxgit/clx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackaxgit%2Fclx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackaxgit%2Fclx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackaxgit%2Fclx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackaxgit%2Fclx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blackaxgit","download_url":"https://codeload.github.com/blackaxgit/clx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackaxgit%2Fclx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291665,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"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","claude-code","cli","command-validation","context-persistence","developer-tools","hooks","llm","mcp","mcp-server","ollama","rust","security","sqlite","vector-search"],"created_at":"2026-04-01T20:31:37.507Z","updated_at":"2026-04-01T20:31:38.041Z","avatar_url":"https://github.com/blackaxgit.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CLX - Claude Code Extension\n\n[![CI](https://github.com/blackaxgit/clx/actions/workflows/ci.yml/badge.svg)](https://github.com/blackaxgit/clx/actions/workflows/ci.yml)\n[![License: MPL-2.0](https://img.shields.io/badge/License-MPL_2.0-brightgreen.svg)](https://mozilla.org/MPL/2.0/)\n[![Claude Code Ready](https://img.shields.io/badge/Claude_Code-Auto_Install_Ready-blueviolet?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgdmlld0JveD0iMCAwIDE2IDE2Ij48dGV4dCB4PSIwIiB5PSIxMyIgZm9udC1zaXplPSIxNCI+8J+UpTwvdGV4dD48L3N2Zz4=)](#install-with-claude-code)\n\n\u003e **Note:** Currently supports macOS (ARM64 and Intel) only.\n\nIntelligent command validation and context persistence for Claude Code.\n\n## Features\n\n- **Command Validation** - Two-layer validation system:\n  - Layer 0: Fast deterministic whitelist/blacklist rules (~1ms)\n  - Layer 1: LLM-based risk assessment via Ollama (~100-300ms)\n\n- **Context Persistence** - SQLite-based storage with semantic search:\n  - Automatic snapshots before context compression\n  - Vector embeddings for semantic recall\n  - Session history and analytics\n\n- **Auto-Recall** - Automatic context injection on every prompt:\n  - Hybrid search: semantic (sqlite-vec) + FTS5 full-text\n  - Relevant past sessions injected as `additionalContext`\n  - Configurable thresholds, timeouts, and result limits\n  - Graceful degradation: Ollama down → FTS5 fallback → orchestrator-only\n\n- **User Learning** - Adapts to your workflow:\n  - Tracks approved/denied commands\n  - Auto-generates rules based on usage patterns\n\n- **MCP Tools** - Claude can access:\n  - `clx_recall` - Search historical context\n  - `clx_remember` - Explicitly save information\n  - `clx_checkpoint` - Create manual snapshots\n  - `clx_rules` - Manage validation rules\n\n## Quick Install\n\n### macOS (Homebrew)\n\n```bash\nbrew tap blackaxgit/clx\nbrew install clx\n```\n\nThis installs `clx`, `clx-hook`, and `clx-mcp`. To update:\n\n```bash\nbrew update \u0026\u0026 brew upgrade clx\n```\n\n## Install with Claude Code\n\n\u003e Let Claude handle the entire setup. You just need macOS, [Ollama](https://ollama.com), and [Rust](https://rustup.rs/) installed.\n\n**1.** Make sure Ollama is running:\n\n```bash\nollama serve\n```\n\n**2.** Paste this into Claude Code:\n\n```\nInstall CLX from https://github.com/blackaxgit/clx:\n1. Clone the repo and build: git clone https://github.com/blackaxgit/clx.git /tmp/clx \u0026\u0026 cd /tmp/clx \u0026\u0026 cargo build --release\n2. Run the installer: ./target/release/clx install\n3. Pull Ollama models: ollama pull qwen3:1.7b \u0026\u0026 ollama pull qwen3-embedding:0.6b\n4. Add to PATH: echo 'export PATH=\"$HOME/.clx/bin:$PATH\"' \u003e\u003e ~/.zshrc\n5. Tell me to restart Claude Code when done\n```\n\n**3.** Restart Claude Code.\n\n**Done.** Hooks are validating commands, context is being persisted, and MCP tools are available.\n\n### One-line install (alternative)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/blackaxgit/clx/main/install.sh | bash\n```\n\n---\n\n## Manual Install\n\n\u003e Full control over every step. Requires macOS (ARM64), Rust 1.85+, and Ollama.\n\n**1. Install prerequisites:**\n\n```bash\n# Rust (if not installed)\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n\n# Ollama (if not installed) — or download from https://ollama.com\nbrew install ollama\nollama serve   # start the server\n```\n\n**2. Build and install CLX:**\n\n```bash\ngit clone https://github.com/blackaxgit/clx.git\ncd clx\ncargo build --release\n./target/release/clx install\n```\n\n**3. Pull the required Ollama models:**\n\n```bash\nollama pull qwen3:1.7b\nollama pull qwen3-embedding:0.6b\n```\n\n**4. Add CLX to your PATH:**\n\n```bash\necho 'export PATH=\"$HOME/.clx/bin:$PATH\"' \u003e\u003e ~/.zshrc\nsource ~/.zshrc\n```\n\n**5. Restart Claude Code**, then verify:\n\n```bash\nclx dashboard\n```\n\nYou should see the interactive dashboard with session history and system status.\n\nSee [INSTALL.md](INSTALL.md) for troubleshooting.\n\n## Usage\n\n### CLI Commands\n\n```bash\n# Check status\nclx dashboard\n\n# Search context\nclx recall \"authentication bug\"\n\n# View/edit configuration\nclx config\nclx config edit\n\n# Manage rules\nclx rules list\nclx rules allow \"npm install *\"\nclx rules deny \"rm -rf /\"\n\n# Check system health\nclx health              # Colored table output\nclx health --json       # Structured JSON output\n\n# Generate shell completions (v0.2+)\nclx completions bash \u003e ~/.clx-completion.bash\nclx completions zsh \u003e ~/.clx-completion.zsh\n\n# Manage embeddings (v0.2+)\nclx embeddings status        # Check model and dimensions\nclx embeddings rebuild       # Rebuild for model migration\n\n# Uninstall\nclx uninstall\nclx uninstall --purge  # Also removes ~/.clx\n```\n\n### Configuration\n\nEdit `~/.clx/config.yaml`:\n\n```yaml\nvalidator:\n  enabled: true\n  layer1_enabled: true        # LLM validation\n  layer1_timeout_ms: 30000\n  default_decision: \"ask\"     # allow, deny, ask\n\ncontext:\n  enabled: true\n  auto_snapshot: true\n\nollama:\n  host: \"http://127.0.0.1:11434\"\n  model: \"qwen3:1.7b\"\n  embedding_model: \"qwen3-embedding:0.6b\"\n  timeout_ms: 60000\n\nuser_learning:\n  enabled: true\n  auto_whitelist_threshold: 3   # Auto-add after N allows\n  auto_blacklist_threshold: 2   # Auto-block after N denies\n\nlogging:\n  level: \"info\"\n  file: \"~/.clx/logs/clx.log\"\n\nauto_recall:\n  enabled: true\n  max_results: 3              # Top-K results to inject\n  similarity_threshold: 0.35  # Min relevance score (0.0-1.0)\n  max_context_chars: 1000     # Max chars for recall context\n  timeout_ms: 500             # Recall timeout per prompt\n  fallback_to_fts: true       # Use FTS5 if semantic fails\n  include_key_facts: true     # Include key facts in context\n  min_prompt_len: 10          # Skip recall for short prompts\n```\n\n### Custom Rules\n\nEdit `~/.clx/rules/default.yaml`:\n\n```yaml\nwhitelist:\n  - pattern: \"Bash(npm:test*)\"\n    description: \"Allow npm test commands\"\n  - pattern: \"Bash(cargo:build*)\"\n    description: \"Allow cargo build\"\n\nblacklist:\n  - pattern: \"Bash(rm:-rf /*)\"\n    description: \"Block recursive delete from root\"\n  - pattern: \"Bash(curl:*|bash)\"\n    description: \"Block pipe to shell\"\n```\n\n### Custom LLM Prompt\n\nEdit `~/.clx/prompts/validator.txt` to customize risk assessment.\n\n## How It Works\n\n### Command Validation Flow\n\n```\nClaude requests command\n        ↓\nPreToolUse hook fires\n        ↓\nLayer 0: Check whitelist/blacklist\n    ├─ Match whitelist → Allow\n    ├─ Match blacklist → Deny\n    └─ Unknown → Continue\n        ↓\nLayer 1: Ollama risk assessment\n    ├─ Score 1-3 → Allow\n    ├─ Score 4-7 → Ask user\n    └─ Score 8-10 → Deny\n        ↓\nUser confirms (if Ask)\n        ↓\nCommand executes\n        ↓\nPostToolUse logs result\n```\n\n### Context Persistence Flow\n\n```\nPreCompact hook fires (before compression)\n        ↓\nRead transcript from JSONL file\n        ↓\nGenerate summary via Ollama\n        ↓\nStore snapshot in SQLite\n        ↓\nGenerate embedding for search\n        ↓\nContext available via clx_recall\n```\n\n## Project Structure\n\n```\nclx/\n├── crates/\n│   ├── clx-core/       # Core library\n│   │   └── src/\n│   │       ├── config.rs      # Configuration management\n│   │       ├── storage/       # SQLite storage (sessions, snapshots, rules)\n│   │       ├── policy/        # Command validation (L0 rules + L1 LLM)\n│   │       ├── recall.rs      # Hybrid search engine (semantic + FTS5)\n│   │       ├── ollama.rs      # Ollama client\n│   │       └── embeddings.rs  # Vector search\n│   ├── clx-hook/       # Hook handler binary\n│   ├── clx-mcp/        # MCP server binary\n│   └── clx/            # CLI binary + dashboard\n├── scripts/            # Docker compose, service management, packaging\n├── install.sh          # Build-from-source installer\n├── INSTALL.md          # Installation guide\n└── CONTRIBUTING.md     # Contribution guide\n```\n\n## Development\n\n```bash\n# Build\ncargo build\n\n# Test\ncargo test\n\n# Run with verbose logging\nRUST_LOG=debug ./target/debug/clx dashboard\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.\n\n## License\n\nMPL-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackaxgit%2Fclx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblackaxgit%2Fclx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackaxgit%2Fclx/lists"}