# Clx

> 🛡️ Rust CLI extension for Claude Code — LLM-powered command validation, SQLite context persistence & MCP tools. Two-layer safety (rules + Ollama), vector semantic search, and user-adaptive learning.

- **Type:** MCP server
- **Install:** `agentstack add mcp-blackaxgit-clx`
- **Verified:** Pending review
- **Seller:** [blackaxgit](https://agentstack.voostack.com/s/blackaxgit)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MPL-2.0
- **Upstream author:** [blackaxgit](https://github.com/blackaxgit)
- **Source:** https://github.com/blackaxgit/clx

## Install

```sh
agentstack add mcp-blackaxgit-clx
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# CLX - Coding-Agent Extension Layer

[](https://github.com/blackaxgit/clx/actions/workflows/ci.yml)
[](https://mozilla.org/MPL/2.0/)
[](#install-with-claude-code)

> **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](#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 | `/.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)

```bash
brew tap blackaxgit/clx
brew install clx
```

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

```bash
brew update && brew upgrade clx
```

## Install with Claude Code

> Let Claude handle the entire setup. You just need macOS, [Ollama](https://ollama.com), and [Rust](https://rustup.rs/) installed.

**1.** Make sure Ollama is running:

```bash
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:**

```bash
# 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:**

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

**3. Pull the required Ollama models:**

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

**4. Add CLX to your PATH:**

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

**5. Restart Claude Code**, then verify:

```bash
clx dashboard
```

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

See [INSTALL.md](INSTALL.md) for troubleshooting.

## Usage

### CLI Commands

```bash
# 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`:

```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`:

```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

```bash
# Build
cargo build

# Test
cargo test

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

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

## License

MPL-2.0

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [blackaxgit](https://github.com/blackaxgit)
- **Source:** [blackaxgit/clx](https://github.com/blackaxgit/clx)
- **License:** MPL-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-blackaxgit-clx
- Seller: https://agentstack.voostack.com/s/blackaxgit
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.