Skip to content

INSTALL.md

Latest commit

 

History

History
148 lines (104 loc) · 3.41 KB

INSTALL.md

File metadata and controls

148 lines (104 loc) · 3.41 KB

Installing CLX

Prerequisites

  • macOS (ARM64/Apple Silicon recommended)
  • Rust toolchain (edition 2024, rustc 1.85+) — install via rustup: 
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  • Ollama — download from the website or install via Homebrew: 
    brew install ollama

Quick Install

Option 1: Install via Claude Code

Paste this prompt into Claude Code:

Install CLX for me: clone https://github.com/blackaxgit/clx, build with cargo build --release, then run ./target/release/clx install. After that, pull the required Ollama models: ollama pull qwen3:1.7b && ollama pull qwen3-embedding:0.6b. Finally, tell me to restart Claude Code.

Option 2: One-Line Install

curl -fsSL https://raw.githubusercontent.com/blackaxgit/clx/main/install.sh | bash

Option 3: Build from Source

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

Then install the Ollama models:

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

Add to PATH

clx install copies all binaries to ~/.clx/bin/. Add this to your ~/.zshrc (or ~/.bashrc):

export PATH="$HOME/.clx/bin:$PATH"

Then reload your shell:

source ~/.zshrc

What clx install Does

The install command sets up everything CLX needs to work with Claude Code:

  1. Creates ~/.clx/ directory with subdirectories for config, data, logs, rules, and prompts
  2. Copies binaries (clx, clx-hook, clx-mcp) to ~/.clx/bin/
  3. Initializes SQLite database for session storage and context persistence
  4. Configures Claude Code hooks in ~/.claude/settings.json:
    • PreToolUse — validates commands before execution
    • PostToolUse — logs command results
    • PreCompact — snapshots context before compression
    • SessionStart / SessionEnd — tracks session lifecycle
    • SubagentStart — monitors subagent activity
    • UserPromptSubmit — injects context on user prompts
  5. Registers MCP server (clx-mcp) so Claude can use CLX tools
  6. Injects CLX section into ~/.claude/CLAUDE.md with tool documentation

After Installation

  1. Restart Claude Code to load the new hooks and MCP server.
  2. Verify CLX is working:
clx dashboard

This opens an interactive dashboard showing session history, validation stats, and system status.

You should see:

  • Session tracking active (new sessions appear in the dashboard)
  • Ollama status: connected
  • Hook status: all hooks configured

Uninstall

# Remove hooks and MCP config (keeps ~/.clx/ data)
clx uninstall

# Remove everything including data
clx uninstall --purge

Troubleshooting

clx: command not found

Ensure ~/.clx/bin is in your PATH:

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

Ollama not running

# Start Ollama
ollama serve

# Verify it's running
curl http://127.0.0.1:11434/

Missing models

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

Hooks not working

Check that ~/.claude/settings.json contains the CLX hooks:

grep clx ~/.claude/settings.json

If not, re-run clx install.

Permission issues

CLX sets ~/.clx/ to owner-only access (700). If you see permission errors:

chmod -R u+rwX ~/.clx/