🐌 SlugAudit

High-performance, zero-bloat repository intelligence for AI coding agents.

Stop burning 80% of your AI agent's context window on repetitive file scans.
SlugAudit indexes your codebase once, verifies freshness in sub-milliseconds on every keystroke, and arms your AI agent with queryable SQL and Tree-sitter AST tools. Your agent spends zero tokens on file rediscovery and 100% of its context on deep reasoning.

⚡ The Problem: Why AI Code Audits Fail

When you ask an AI coding agent to inspect or audit a codebase, it typically resorts to brute force:

1. It lists directories and reads 40+ entire files looking for symbol definitions and call sites.

2. It burns 100,000+ context tokens before writing a single line of analysis.

3. As the context window fills up, the agent hits compaction, forgets earlier files, hallucinates stale paths, and enters paranoid re-validation loops.

Related MCP server: Code Expert MCP Server

🏗️ How It Works

SlugAudit acts as an invisible, high-speed telemetry and evidence layer between your filesystem and your AI agent over the standard Model Context Protocol (MCP):

graph LR
    subgraph Host ["Your Machine"]
        Repo["Source Code"]
        Watcher["File Watcher (inotify/kqueue)"]
    end

    subgraph SlugAudit ["SlugAudit MCP Engine"]
        TS["Tree-Sitter AST & BLAKE3 Hasher"]
        CAS["Atomic CAS Publishing"]
        DB[("Disposable SQLite Index\n.planning/slugaudit/project.db")]
        Guards["Read-Only Authorizer & Subquery Wrappers"]
    end

    subgraph Agent ["AI Coding Agent"]
        Client["Claude Code · Cursor · Codex · Hermes · Windsurf · Bob · Grok"]
    end

    Repo --> Watcher
    Repo --> TS
    TS --> CAS --> DB
    DB --> Guards --> Client

1. Discovery & Hash: Respects .gitignore and .ignore recursively, walks the repo in milliseconds, and hashes files with BLAKE3.

2. Deep AST Extraction: Runs Tree-sitter across 300+ languages to index functions, methods, imports, call hierarchies, comments, and syntax diagnostics.

3. Atomic CAS Publish: Commits the entire index into an ephemeral SQLite database in .planning/slugaudit/project.db using compare-and-swap (CAS) concurrency control.

4. Sub-millisecond Reconcile: Background watcher detects file edits. Every tool call verifies freshness synchronously before returning results—zero chance of stale data.

5. Precise SQL & AST Tools: The AI agent queries exact facts (files, evidence, revisions) without ever touching the disk.

🎯 The Division of Labor

• SlugAudit gathers facts: indexes, extracts, synchronizes, and searches.

• The AI does the audit: interprets evidence, spots logic bugs, judges security implications, and refactors code.

SlugAudit does not judge code, assign arbitrary "scores", or tell your AI what to think. It provides ground truth so your AI can do real engineering.

🚀 Quick Start

1. Fast Install

# One-line universal installer (Linux x86_64 or builds via cargo):
curl -fsSL https://raw.githubusercontent.com/SlugThugLabs/slugaudit/main/install.sh | bash

# Or build locally from source with Cargo:
cargo install --path .

# Or run the interactive setup menu:
slugaudit menu

2. Connect Your AI Agent (One-Click)

SlugAudit automatically configures your favorite AI coding assistant:

slugaudit connect agy       # Antigravity (agy mcp add)
slugaudit connect gemini    # Gemini CLI (gemini mcp add)
slugaudit connect claude    # Claude Code (~/.claude.json)
slugaudit connect cursor    # Cursor IDE (~/.cursor/mcp.json)
slugaudit connect codex     # Codex CLI (~/.codex/config.toml)
slugaudit connect hermes    # Hermes Agent

(Run slugaudit connect without arguments to auto-detect installed agents interactively from your terminal).

To disconnect: slugaudit disconnect <agent> or pick from slugaudit disconnect.

3. Ask Your Agent Anything

Start a normal session with your agent and ask:

"Audit our authentication flow. Are token expiration checks enforced on every endpoint?"

Your agent will call report, query, and structure in the background—answering with exact line ranges in milliseconds without flooding your context.

🔌 Supported AI Agents & Editors

🛠️ The 7 Native MCP Tools

🎯 Context Optimization: Lean Results vs. Full Output

SlugAudit follows a "Results First, Full Code On-Demand" model to prevent burning the agent's context window while ensuring no data is ever hidden from an audit:

• AST Pattern Search (structure):

  • Multi-File Search: Omit file to search across all files of a given language (optionally filtered by pattern, e.g. "src/**/*.rs"). Defaults to lean 1-line preview snippets (full_text: false, max 120 bytes) with exact start_line/end_line and column coordinates.

  • Single-File Search: Specify file to inspect a targeted file. Defaults to full AST code blocks (full_text: true, up to 1 MiB / 1,000,000 bytes).

  • Explicit Control: The agent can pass "full_text": false for compact coordinate-only sweeps across any scope, or "full_text": true to pull complete code blocks.

• SQL Queries (query):

  • Selective Projection: The agent queries only what it needs (e.g. SELECT path, line_number FROM evidence WHERE ...) to stay lean, or SELECT content when full source text is required.

  • Paging with next_offset: Results are capped at 500 rows and up to 256 MiB+ per page (dynamically scaled to host RAM). When truncated: true, next_offset is provided so the agent can page through the entire dataset without context overflow.

🎛️ Profiles & Adaptive Host Memory

SlugAudit never imposes artificial barriers on codebases. Following the design standards of CodeQL and Semgrep, it dynamically scales resource limits to match the host hardware:

• Adaptive (Default): Automatically detects physical and available host RAM (/proc/meminfo on Linux, sysctl on macOS). Dynamically scales import caches and per-file caps (up to 1 GiB single-file limit, half of available RAM for total project imports).

• Audit: Deep audit mode for massive enterprise repos (256 MiB per-file cap, 32 GiB total import budget, 60s execution budgets).

• Lean: Lightweight mode for resource-constrained environments (32 MiB per-file cap, 2 GiB total import budget, 10s execution budgets).

How to Configure:

1. In-Repo Project Config: Add .planning/slugaudit/config.json to the audited repository:

   {
     "profile": "audit"
   }

2. MCP Tool Control: Agents can select or change profiles on the fly:

   {
     "name": "project_control",
     "arguments": {
       "action": "on",
       "profile": "audit"
     }
   }

3. Environment Overrides: Set SLUGAUDIT_PROFILE=audit or tune granular variables (e.g. SLUGAUDIT_MAX_FILE_BYTES=536870912).

⚡ Performance Benchmarks

Measured on standard development hardware (AMD Ryzen 9 / Linux kernel 6.x):

📖 Query Cookbook & Recipes

Ready-to-run queries for AI agents and security auditors in examples/queries/:

• Auth Attack Surface: Map all authentication, token, and session endpoints in < 2ms.

• Find Unhandled Panics: Pinpoint crash-prone .unwrap(), .expect(), and panic!() calls.

• Syntax Diagnostics: Extract parser errors and syntax issues without running a compiler.

• Rust AST Matcher: Tree-sitter query matching exact function shapes and parameter blocks.

Product boundary

The single end-user product is the slugaudit binary. Users install and configure it with their AI agent, and the binary operates on the user's own projects.

For each enabled user project, SlugAudit owns only this derived-data directory:

<user-project>/.planning/slugaudit/project.db

The surrounding .planning/ directory belongs to the user's project workflow. Its other files are ordinary user project data and may be indexed normally. SlugAudit excludes its own .planning/slugaudit/ directory from discovery.

The database is disposable derived data — delete it and any tool call rebuilds it from source.

Repository scope

See DEVELOPMENT_SCOPE.md for the distinction between this repository's development materials and the runtime behavior of SlugAudit inside a user's project.

Repository Structure & The .planning/ Directory

All architectural blueprints, design decisions, and runtime index data live inside .planning/:

• Source of Truth: .planning/ARCHITECTURE.md is the canonical, authoritative source of truth for the codebase. It details the complete module map, data flow, process lifecycle, security boundaries, and the 10 core architectural invariants governing SlugAudit.

• Design & Planning History: .planning/archive/ preserves historical planning records, architectural decision logs, and dependency inventories.

• Disposable Runtime Cache: .planning/slugaudit/project.db houses the SQLite index and evidence tables. This is derived data that SlugAudit automatically creates and synchronizes—it can be deleted at any time and any tool call will rebuild it from source.

Keeping these artifacts organized inside .planning/ keeps the repository root uncluttered while providing both human developers and AI coding agents a dedicated, structured home for all architecture and design documentation.

Documentation

• Architecture — the authoritative architectural specification (module map, data flow, security model, design FAQ)

• Connection guides — agent-specific setup for Bob, Claude Code, Grok, and Codex

• Archive — historical planning docs, decision log, dependency inventory

Development

Requires Rust 1.97.1+ (edition 2024) on Linux or macOS. Run the same gates CI uses:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --lib --bins --tests --all-features
cargo run --quiet --bin check_source_limits --locked
cargo run --quiet --bin check_docs_drift --locked
cargo run --quiet --bin check_no_duplicates --locked

#![forbid(unsafe_code)] is enforced crate-wide. Zero unsafe in src/.

Structured Logging

Diagnostics log to stderr with ANSI colors disabled by default. For automated log aggregators (e.g. Datadog, Grafana Loki, CloudWatch), set:

export SLUGAUDIT_LOG_FORMAT=json

All stderr events will be formatted as single-line JSON while stdout remains strictly JSON-RPC.

License

SlugAudit is free to use — including for your own commercial software. Use it to develop, audit, test, and maintain whatever you build, and you may sell the software you create with it. Software you make using SlugAudit (and the results it produces) does not become subject to SlugAudit's license just because the tool was used. The only thing you need to contact us about (admin@slugthuglabs.dev) is distributing SlugAudit itself — for example embedding, bundling, redistributing, sublicensing, or selling the tool as part of another product or service. That includes a company wanting to make SlugAudit a branded part of something they sell — we'd love to talk. Internal team and dev use is always free.

See the complete LICENSE for the binding terms.