{"id":49570992,"url":"https://github.com/keradd/crux","last_synced_at":"2026-05-03T14:01:44.531Z","repository":{"id":355390344,"uuid":"1227916400","full_name":"Keradd/crux","owner":"Keradd","description":"Compression Runtime for Universal eXecution — token-optimization runtime for AI coding agents (Rust, single binary, 10 layers, local-first)","archived":false,"fork":false,"pushed_at":"2026-05-03T12:24:32.000Z","size":284,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-03T12:28:37.723Z","etag":null,"topics":["ai-agents","cli","llm","mcp","rust","sqlite","token-optimization","tree-sitter"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Keradd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","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-05-03T10:43:48.000Z","updated_at":"2026-05-03T12:23:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Keradd/crux","commit_stats":null,"previous_names":["keradd/crux"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Keradd/crux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Keradd%2Fcrux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Keradd%2Fcrux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Keradd%2Fcrux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Keradd%2Fcrux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Keradd","download_url":"https://codeload.github.com/Keradd/crux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Keradd%2Fcrux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32571456,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"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-agents","cli","llm","mcp","rust","sqlite","token-optimization","tree-sitter"],"created_at":"2026-05-03T14:01:36.363Z","updated_at":"2026-05-03T14:01:44.517Z","avatar_url":"https://github.com/Keradd.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CRUX\n\n[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)\n[![Rust 1.85+](https://img.shields.io/badge/rust-1.85%2B-orange.svg)](https://www.rust-lang.org)\n[![Tests](https://img.shields.io/badge/tests-289%20passing-brightgreen.svg)](#testing)\n[![CI](https://github.com/Keradd/crux/actions/workflows/ci.yml/badge.svg)](https://github.com/Keradd/crux/actions/workflows/ci.yml)\n\n\u003e **Compression Runtime for Universal eXecution.**\n\u003e One Rust binary. One SQLite database. Ten layers. Local-first. Zero telemetry.\n\nCRUX is a token-optimization runtime that sits between an AI coding agent\n(Claude Code, Cursor, Cline, Continue, Aider, …) and the agent's tools\n(Read, Edit, Bash, MCP servers). It reduces token usage by 60–95 % across\nreal workloads without degrading task quality, by attacking every layer\nwhere tokens are wasted: prose verbosity, tool-call bloat, redundant file\nreads, missing structure, lost context, and quality decay.\n\n---\n\n## Why CRUX\n\n| Pain point | CRUX layer | Mechanism |\n|---|---|---|\n| Verbose model output | **L1** profiles | Compressed-output skills + project-tuned style guides |\n| Bloated MCP tool descriptions | **L2** shrinker | Stdio JSON-RPC proxy that rewrites `tools/list` |\n| Long, noisy bash output | **L3** bash filter | TOML pipeline (8 stages) + 5 built-in filters |\n| Re-reading the same file | **L4** read cache | mtime + range cache, LCS delta, `.contextignore` |\n| Whole-file reads to find a symbol | **L5** AST graph | Tree-sitter graph with cross-file call resolution |\n| Grep-only code search | **L6** hybrid search | BM25 (porter + trigram) + dense vectors + RRF |\n| Unsafe code execution | **L7** sandbox | Subprocess + rlimits + landlock + seccomp (opt-in) |\n| Lost context across sessions | **L8** memory | FTS5 + decay-ranked observations |\n| Quality / loop drift | **L9** coach | Score, loop detect, CLAUDE.md drift |\n| Inconsistent project setup | **L10** setup | `crux init` scaffold + profile templates |\n\nAll ten layers are independent and opt-in via TOML.\n\n---\n\n## Install\n\n### One-shot installer (recommended)\n\n```bash\n# From a checkout of the repo — builds release + installs to ~/.local/bin\n# + auto-registers CRUX as an MCP server in every detected agent\n# + runs the first-time L5 index and L6 reindex in your CWD.\nbash scripts/install.sh\n\n# System scope (puts `crux` in /usr/local/bin; uses sudo if needed):\nbash scripts/install.sh --system\n\n# Skip bootstrap (just build + install the binary):\nbash scripts/install.sh --no-bootstrap\n\n# Install but don't touch any agent config:\nbash scripts/install.sh --no-agents\n```\n\nAfter that, `crux --version` should work and every installed agent\n(Claude Code / Desktop, Cursor, Windsurf, Cline, Zed) already has CRUX\nwired up as an MCP server pointed at the current directory.\n\n### Prebuilt binaries\n\nEach tagged release ships statically-linked binaries on the\n[GitHub Releases](https://github.com/Keradd/crux/releases) page for:\n\n- Linux x86_64 (`gnu` + `musl`)\n- Linux aarch64 (`gnu` + `musl`)\n- macOS x86_64 + aarch64 (Apple Silicon)\n- Windows x86_64\n\nEach archive ships with a `.sha256` checksum next to it.\n\n```bash\n# Linux x86_64 (gnu) example — replace TAG with the latest release tag.\nTAG=v0.2.0\ncurl -L -o crux.tar.gz \\\n  \"https://github.com/Keradd/crux/releases/download/${TAG}/crux-${TAG}-x86_64-unknown-linux-gnu.tar.gz\"\ntar -xzf crux.tar.gz\nsudo install crux /usr/local/bin/\ncrux --help\n```\n\n### From source\n\n```bash\ngit clone https://github.com/Keradd/crux.git\ncd crux\ncargo build --release\n# binary at ./target/release/crux (~11 MB stripped on Linux x86_64)\n```\n\n### Requirements (source builds)\n\n- Rust **1.85+**\n- SQLite is bundled via `rusqlite` — no system dependency.\n- Optional: `--features crux-l7-sandbox/seccomp` enables Linux seccomp BPF\n  syscall filtering (requires kernel ≥ 3.5).\n\n---\n\n## Activate inside your AI agent\n\nAfter `crux --version` works, register CRUX with your agent in one command:\n\n```bash\ncrux setup                  # auto-detect every supported agent on this machine\ncrux setup claude-code      # specific agent\ncrux setup --list           # show what's supported\ncrux setup --dry-run        # preview without writing anything\n```\n\n| Agent | What `crux setup` writes |\n|---|---|\n| **Claude Code** | `mcpServers.crux` + `PreToolUse(Read)` / `PostToolUse(Edit\\|Write\\|MultiEdit)` hooks + `/crux` slash-command (`~/.claude/commands/crux.md`) |\n| **Claude Desktop** | `mcpServers.crux` in `claude_desktop_config.json` (OS-canonical path) |\n| **Cursor** | `~/.cursor/mcp.json` |\n| **Windsurf** (Cascade) | `~/.codeium/windsurf/mcp_config.json` |\n| **Cline** (VS Code) | `cline_mcp_settings.json` in VS Code's `globalStorage` |\n| **Zed** | `context_servers.crux` in `~/.config/zed/settings.json` |\n| **OpenClaw** | `mcp.servers.crux` in `~/.openclaw/openclaw.json` (honors `$OPENCLAW_CONFIG_PATH`) |\n| **Hermes Agent** | `mcp_servers.crux` in `~/.hermes/config.yaml` (native YAML) |\n\n`crux setup` is idempotent: re-running it is a no-op once the entries exist.\nUse `--scope project` to write per-project configs instead of per-user, and\n`--no-hooks` / `--no-skill` to opt out of the Claude Code extras.\n\nAfter setup, restart your agent (or run `claude mcp list` for Claude Code)\nand the eleven CRUX MCP tools will be available — `crux_search`,\n`crux_find_symbol`, `crux_impact`, `crux_remember`, `crux_recall`,\n`crux_read`, `crux_execute`, and friends.\n\n---\n\n## Quick start\n\n```bash\n# ── One-line bootstrap (recommended) ────────────────────────────────\n# Scaffold project + register CRUX in every detected agent (with\n# CRUX_PROJECT=\u003ccwd\u003e pinned in each MCP env) + run first-time L5\n# AST index and L6 hybrid-search reindex.\ncrux init --non-interactive --setup-agents --index\n\n# The three concerns can also be run one at a time:\ncrux init --non-interactive --profile coding\ncrux setup                  # auto-detect every supported agent\ncrux index \u0026\u0026 crux reindex  # first-time AST + chunk build\n\n# L3 — filter bash output (git/cargo/npm/jest/generic, all TOML-defined)\ncrux bash git status\n\n# L5 — AST graph (Merkle-incremental; second run is a near no-op)\ncrux index\ncrux find ReadCacheManager\ncrux impact crates::crux-l4-readcache::src::delta::compute_delta --depth 3\n\n# L6 — hybrid search (BM25 + dense + RRF + fuzzy fallback)\ncrux reindex\ncrux search \"delta cache\" --kind code --limit 5\n\n# L7 — sandboxed code execution\ncrux execute --runtime python -c 'print(2+2)'\ncrux execute --runtime bash   -c 'sleep 5' --timeout 1     # exits 124\ncrux execute --runtime bash   -c 'ulimit -v' --isolate hard\n\n# L8 — persistent memory (FTS5 + decay)\ncrux remember --kind decision --title \"Use Pinia\" --content \"...\"\ncrux recall Pinia\n\n# L9 — quality coach\ncrux audit\ncrux coach drift\n\n# MCP server (11 tools, stdio JSON-RPC)\ncrux mcp\ncrux mcp-shrink npx @modelcontextprotocol/server-filesystem /some/path\n```\n\n`CRUX_HOME` overrides the default `~/.crux` data directory.\n`CRUX_PROJECT` overrides project-root detection.\n\n---\n\n## MCP tools\n\nRun `crux mcp` to expose CRUX over stdio JSON-RPC. The server advertises\nthe following tools:\n\n| Tool | Layer | Purpose |\n|---|---|---|\n| `crux_remember` / `crux_recall` | L8 | Persist \u0026 search observations |\n| `crux_read` | L4 | Cache-aware file reads with delta replies |\n| `crux_bash_filter` | L3 | Apply L3 filter to a `(command, output)` pair |\n| `crux_audit` | L9 | Health snapshot + telemetry summary |\n| `crux_find_symbol` / `crux_get_symbol_source` | L5 | Symbol lookup |\n| `crux_query_graph` / `crux_impact` | L5 | Callers / callees / blast radius |\n| `crux_search` | L6 | Hybrid BM25 + dense + RRF over indexed chunks |\n| `crux_execute` | L7 | Run python / bash / node snippets in the sandbox |\n\n---\n\n## Workspace layout\n\n```\ncrux/\n├── Cargo.toml                 # workspace manifest\n├── crates/\n│   ├── crux-core/             # config, db, errors, paths, telemetry, merkle\n│   ├── crux-l3-bash/          # TOML filter pipeline + 5 built-in filters\n│   ├── crux-l4-readcache/     # read cache + LCS delta + .contextignore\n│   ├── crux-l5-ast/           # tree-sitter AST graph (Rust/Python/TS/JS)\n│   ├── crux-l6-search/        # hybrid BM25 + dense + RRF + Merkle sync\n│   ├── crux-l7-sandbox/       # subprocess + rlimits + landlock + seccomp\n│   ├── crux-l8-memory/        # observations + decay engine + FTS5\n│   ├── crux-l9-coach/         # quality score + loop detect + drift\n│   ├── crux-l10-setup/        # `crux init` + profile templates\n│   ├── crux-mcp/              # MCP stdio JSON-RPC server + L2 shrinker\n│   └── crux-cli/              # `crux` binary (clap-based CLI)\n├── docs/\n│   └── ARCHITECTURE.md        # full architecture specification\n├── CHANGELOG.md\n├── CONTRIBUTING.md\n├── LICENSE-MIT\n└── LICENSE-APACHE\n```\n\n---\n\n## Documentation\n\n- **[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)** — full design specification:\n  goals, tech stack, data model, per-layer internals, security model,\n  performance targets, roadmap.\n- **[`CHANGELOG.md`](CHANGELOG.md)** — release-notable changes.\n- **[`CONTRIBUTING.md`](CONTRIBUTING.md)** — coding conventions, test\n  policy, PR checklist.\n\n---\n\n## Testing\n\n```bash\ncargo test                                          # 289 passing / 0 failed\ncargo test --features crux-l7-sandbox/seccomp       # 299 passing / 0 failed (Linux)\ncargo bench                                         # criterion benchmarks (L4, L5, L6)\n```\n\nInline TOML goldens for L3 filters live in\n`crates/crux-l3-bash/filters/*.toml` under `[[tests]]` and run via the\nstandard `cargo test` invocation.\n\n---\n\n## License\n\nDual-licensed under either of\n\n- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or\n  \u003chttp://www.apache.org/licenses/LICENSE-2.0\u003e)\n- MIT license ([LICENSE-MIT](LICENSE-MIT) or\n  \u003chttp://opensource.org/licenses/MIT\u003e)\n\nat your option.\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally\nsubmitted for inclusion in the work by you, as defined in the\nApache-2.0 license, shall be dual-licensed as above, without any\nadditional terms or conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeradd%2Fcrux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkeradd%2Fcrux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeradd%2Fcrux/lists"}