Clx

CI License: MPL-2.0 Claude Code Ready

Note: Currently supports macOS (Apple Silicon / ARM64) only.

Intelligent command validation and context persistence for coding agents. CLX supports Claude Code, Codex CLI, and Cursor (see Supported Hosts for what each host can and cannot enforce).

Features

• Command Validation - Two-layer validation system:

  • Layer 0: Fast deterministic whitelist/blacklist rules (~1ms)
  • Layer 1: LLM-based risk assessment via Ollama (~100-300ms)

• Context Persistence - SQLite-based storage with semantic search:

  • Automatic snapshots before context compression
  • Vector embeddings for semantic recall
  • Session history and analytics

• Auto-Recall - Automatic context injection on every prompt:

  • Hybrid search: semantic (sqlite-vec) + FTS5 full-text
  • Relevant past sessions injected as additionalContext
  • Configurable thresholds, timeouts, and result limits
  • Graceful degradation: Ollama down → FTS5 fallback → orchestrator-only

• User Learning - Adapts to your workflow:

  • Tracks approved/denied commands
  • Auto-generates rules based on usage patterns

• MCP Tools - the host agent can access (Claude Code, Codex CLI, Cursor):

  • clx_recall - Search historical context
  • clx_remember - Explicitly save information
  • clx_checkpoint - Create manual snapshots
  • clx_rules - Manage validation rules
  • clx_session_info - Get current session details
  • clx_credentials - Manage stored provider credentials
  • clx_stats - Report usage and storage statistics

Supported Hosts

CLX installs into three coding-agent hosts. MCP tools and instructions injection work fully on all three; command gating differs by host because each host exposes a different hook surface.

Host	Command gating	Instructions injection	MCP tools
Claude Code	Full CLI gating: PreToolUse allow / deny / ask enforced on every tool call	~/.claude/CLAUDE.md	Full (7 tools)
Codex CLI	Interactive-only, best-effort guardrail: allow / deny in interactive Codex sessions; no ask channel	~/.codex/AGENTS.md (with AGENTS.override.md fallback)	Full (7 tools)
Cursor	IDE agent and cloud agents only: beforeShellExecution / beforeMCPExecution with failClosed: true; the local cursor-agent CLI runs no hooks	<repo>/.cursor/rules/clx.mdc	Full (7 tools)

Codex caveat: Command validation is a guardrail, not a complete enforcement boundary (OpenAI's wording); it applies to interactive Codex sessions, not codex exec automation, and ask is mapped to deny pending Codex ask support.

Cursor caveat: Command gating fires in the IDE agent and cloud agents only; the cursor-agent local CLI does not run hooks.

Quick Install

macOS (Homebrew)

brew tap blackaxgit/clx
brew install clx

This installs clx, clx-hook, and clx-mcp. To update:

brew update && brew upgrade clx

Install with Claude Code

Let Claude handle the entire setup. You just need macOS, Ollama, and Rust installed.

1. Make sure Ollama is running:

ollama serve

2. Paste this into Claude Code:

Install CLX from https://github.com/blackaxgit/clx:
1. Clone the repo and build: git clone https://github.com/blackaxgit/clx.git /tmp/clx && cd /tmp/clx && cargo build --release
2. Run the installer: ./target/release/clx install
3. Pull Ollama models: ollama pull qwen3:1.7b && ollama pull qwen3-embedding:0.6b
4. Add to PATH: echo 'export PATH="$HOME/.clx/bin:$PATH"' >> ~/.zshrc
5. Tell me to restart Claude Code when done

3. Restart Claude Code.

Done. Hooks are validating commands, context is being persisted, and MCP tools are available.

---

Manual Install

Full control over every step. Requires macOS (ARM64), Rust 1.85+, and Ollama.

1. Install prerequisites:

# Rust (if not installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Ollama (if not installed) — or download from https://ollama.com
brew install ollama
ollama serve   # start the server

2. Build and install CLX:

git clone https://github.com/blackaxgit/clx.git
cd clx
cargo build --release
./target/release/clx install

3. Pull the required Ollama models:

ollama pull qwen3:1.7b
ollama pull qwen3-embedding:0.6b

4. Add CLX to your PATH:

echo 'export PATH="$HOME/.clx/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

5. Restart Claude Code, then verify:

clx dashboard

You should see the interactive dashboard with session history and system status.

See INSTALL.md for troubleshooting.

Usage

CLI Commands

# Check status
clx dashboard

# Search context
clx recall "authentication bug"

# View/edit configuration
clx config
clx config edit

# Manage rules
clx rules list
clx rules allow "npm install *"
clx rules deny "rm -rf /"

# Check system health
clx health              # Colored table output
clx health --json       # Structured JSON output

# Generate shell completions (v0.2+)
clx completions bash > ~/.clx-completion.bash
clx completions zsh > ~/.clx-completion.zsh

# Manage embeddings (v0.2+)
clx embeddings status        # Check model and dimensions
clx embeddings rebuild       # Rebuild for model migration

# Uninstall
clx uninstall
clx uninstall --purge  # Also removes ~/.clx

Configuration

Edit ~/.clx/config.yaml:

validator:
  enabled: true
  layer0_enabled: true        # deterministic policy (rule-based)
  layer1_enabled: true        # LLM validation
  layer1_timeout_ms: 30000
  default_decision: "ask"     # allow, deny, ask
  # If both layer0_enabled and layer1_enabled are false (with enabled: true),
  # every command resolves to "ask"; to disable validation entirely set
  # enabled: false. Both layer toggles are also overridable via
  # CLX_VALIDATOR_LAYER0_ENABLED / CLX_VALIDATOR_LAYER1_ENABLED env vars;
  # disabling a layer emits a per-event SHA-256 fingerprint to
  # tracing::warn!; tamper-evident only when an external append-only sink
  # captures the anchor (SQLite alone is not tamper-evident because a
  # same-uid attacker can rewrite the database file).

context:
  enabled: true
  auto_snapshot: true

ollama:
  host: "http://127.0.0.1:11434"
  model: "qwen3:1.7b"
  embedding_model: "qwen3-embedding:0.6b"
  timeout_ms: 60000

user_learning:
  enabled: true
  auto_whitelist_threshold: 3   # Auto-add after N allows
  auto_blacklist_threshold: 2   # Auto-block after N denies

logging:
  level: "info"
  file: "~/.clx/logs/clx.log"

auto_recall:
  enabled: true
  max_results: 3              # Top-K results to inject
  similarity_threshold: 0.35  # Min relevance score (0.0-1.0)
  max_context_chars: 1000     # Max chars for recall context
  timeout_ms: 500             # Recall timeout per prompt
  fallback_to_fts: true       # Use FTS5 if semantic fails
  include_key_facts: true     # Include key facts in context
  min_prompt_len: 10          # Skip recall for short prompts

Custom Rules

Edit ~/.clx/rules/default.yaml:

whitelist:
  - pattern: "Bash(npm:test*)"
    description: "Allow npm test commands"
  - pattern: "Bash(cargo:build*)"
    description: "Allow cargo build"

blacklist:
  - pattern: "Bash(rm:-rf /*)"
    description: "Block recursive delete from root"
  - pattern: "Bash(curl:*|bash)"
    description: "Block pipe to shell"

Custom LLM Prompt

Edit ~/.clx/prompts/validator.txt to customize risk assessment.

How It Works

Command Validation Flow

Claude requests command
        ↓
PreToolUse hook fires
        ↓
Layer 0: Check whitelist/blacklist
    ├─ Match whitelist → Allow
    ├─ Match blacklist → Deny
    └─ Unknown → Continue
        ↓
Layer 1: Ollama risk assessment
    ├─ Score 1-3 → Allow
    ├─ Score 4-7 → Ask user
    └─ Score 8-10 → Deny
        ↓
User confirms (if Ask)
        ↓
Command executes
        ↓
PostToolUse logs result

Context Persistence Flow

PreCompact hook fires (before compression)
        ↓
Read transcript from JSONL file
        ↓
Generate summary via Ollama
        ↓
Store snapshot in SQLite
        ↓
Generate embedding for search
        ↓
Context available via clx_recall

Project Structure

clx/
├── crates/
│   ├── clx-core/       # Core library
│   │   └── src/
│   │       ├── config/        # Configuration management
│   │       ├── storage/       # SQLite storage (sessions, snapshots, rules)
│   │       ├── policy/        # Command validation (L0 rules + L1 LLM)
│   │       ├── recall/        # Hybrid search engine (semantic + FTS5)
│   │       ├── llm.rs         # LLM client (Ollama + Azure OpenAI)
│   │       └── embeddings.rs  # Vector search
│   ├── clx-hook/       # Hook handler binary (host abstraction in host/)
│   ├── clx-mcp/        # MCP server binary
│   └── clx/            # CLI binary + dashboard (codex/, cursor/ installers)
├── scripts/            # Docker compose, service management, packaging
├── INSTALL.md          # Installation guide
└── CONTRIBUTING.md     # Contribution guide

Development

# Build
cargo build

# Test
cargo test

# Run with verbose logging
RUST_LOG=debug ./target/debug/clx dashboard

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MPL-2.0