clx MCP server
2026년 10월 31일 커밋Claude Code 및 Cursor와 같은 코딩 에이전트를 위해 지능형 명령 검증, SQLite 기반 컨텍스트 유지, 시맨틱 검색 기능을 제공합니다.
다른 이름 blackaxgit/clx
- 스타
- 1
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 10월 31일
- 라이선스
- MPL-2.0
clx MCP란?
Claude Code 및 Cursor와 같은 코딩 에이전트를 위해 지능형 명령 검증, SQLite 기반 컨텍스트 유지, 시맨틱 검색 기능을 제공합니다.
프로젝트 README에서 생성된 요약
clx MCP server 정보
Claude Code, Codex CLI 또는 Cursor를 사용하는 개발자는 지능형 명령 검증 및 지속성 메모리를 통해 코딩 에이전트의 기능을 강화할 수 있습니다. 이 도구는 2단계 시스템을 통해 셸 명령을 확인하여 환경을 보호하는 확장 레이어 역할을 합니다. 즉각적인 필터링을 위한 빠른 결정론적 규칙과 잠재적으로 위험한 작업에 대한 심층 분석을 위한 Ollama 기반 위험 평가를 함께 사용합니다.
보안 외에도 SQLite 데이터베이스를 사용하여 세션 간에 컨텍스트를 유지하는 방법을 제공합니다. 컨텍스트 압축 전에 자동으로 스냅샷을 생성하며, 시맨틱 검색을 위해 벡터 임베딩을 사용합니다. 이를 통해 에이전트는 clx_recall 및 clx_remember와 같은 도구를 사용하여 관련 있는 과거 정보를 회상할 수 있습니다. 이 시스템은 Apple Silicon을 사용하는 macOS 사용자를 위해 설계되었으며, 로컬 LLM 기반 검증 및 임베딩 작업을 처리하기 위해 Ollama가 필요합니다.
통합은 호스트 에이전트가 규칙을 관리하고, 세션 통계를 확인하며, 자격 증명을 처리할 수 있도록 하는 MCP 도구를 통해 이루어집니다. 이 서버는 시맨틱 회상과 FTS5 전문 검색을 결합한 하이브리드 검색을 지원하여 로컬 LLM 서비스를 사용할 수 없는 경우에도 정보에 접근할 수 있도록 보장합니다.
활용 사례
- 1셸 명령 안전성 검증보안 규칙을 기반으로 특정 터미널 명령을 실행해도 안전한지 에이전트에게 확인하도록 요청합니다.
- 2과거 코딩 컨텍스트 검색시맨틱 검색을 사용하여 이전 코딩 세션에서 정보를 찾도록 에이전트에게 지시합니다.
- 3중요 세션 데이터 수동 저장향후 참조를 위해 특정 정보를 명시적으로 저장하도록 에이전트에게 명령합니다.
- 4수동 상태 스냅샷 생성컨텍스트 압축 중 데이터 손실을 방지하기 위해 현재 세션 상태의 체크포인트를 요청합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
구성
RUST_LOG
| 이름 | 설명 | 유형 |
|---|---|---|
| RUST_LOG | — |
자동 검사
2026년 11월 15일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능blackaxgit/clx is public and reachablegithub.com/blackaxgit/clx ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)MPL-2.0spdx.org/licenses/MPL-2.0.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-10-31github.com/blackaxgit/clx ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기CLX - Coding-Agent Extension Layer
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 contextclx_remember- Explicitly save informationclx_checkpoint- Create manual snapshotsclx_rules- Manage validation rulesclx_session_info- Get current session detailsclx_credentials- Manage stored provider credentialsclx_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
clx MCP 질문
지원되는 운영 체제는 무엇인가요?
현재 clx는 macOS(Apple Silicon / ARM64)만 지원합니다.
명령 검증은 어떻게 작동하나요?
빠른 결정론적 화이트리스트/블랙리스트 규칙 레이어와 Ollama를 통한 LLM 기반 위험 평가 레이어의 2단계 시스템을 사용합니다.
어떤 코딩 에이전트에서 clx를 사용할 수 있나요?
Claude Code, Codex CLI, Cursor를 지원합니다.