Documentation

LocalForge Docs

Everything you need to install, configure, and understand LocalForge.

Introduction

LocalForge is a 4-layer Rust + CoreML + LLM + static analysis pipeline that reviews every commit before git does — entirely on Apple Silicon. No cloud. No API keys. Nothing leaves your Mac.

When you run git commit, a pre-commit hook fires LocalForge synchronously. The commit is held until all layers complete or one of the blocking layers raises an issue.

Layer 1 — Rust AST regex: catches hardcoded secrets in under 1ms. Hard block.
Layer 2 — CoreML classifier on the Apple Neural Engine: statistical risk scoring in ~200ms. Hard block.
Layer 3 — Qwen2.5-Coder-7B via MLX: semantic code review in ~5-8s. 0.982 precision. Advisory only — never blocks commits.
Layer 3.5 — Deterministic static analysis (bandit, pylint, ESLint, go vet, staticcheck, cargo clippy) running alongside the LLM. Advisory only.

Requirements

macOS 14 (Sonoma) or later
Apple Silicon — M1, M2, M3, or M4 (required for CoreML / ANE)
Rust toolchain (for building from source)
Python 3.10+ with coremltools (for building the CoreML model from source)
Qwen2.5-Coder-7B model weights — auto-downloaded by localforge --install (Layer 3, optional; falls back to 1.5B if already present)
Static analysis tools: bandit, pylint, ESLint, go vet, staticcheck, cargo clippy — auto-installed by localforge --install (Layer 3.5, optional)

Installation

Binary (recommended)

Download the latest .dmg from the Download page, open it, and drag LocalForge.app to your Applications folder. Then run the hook installer in any git repo:

bash

localforge --install

This copies the binary to ~/.localforge/bin/, adds it to your shell PATH, installs the CoreML model, auto-downloads Qwen2.5-Coder-7B (falling back to 1.5B if already present), installs all available static analysis tools, and wires the pre-commit hook (v4).

To protect a specific repo: localforge --install /path/to/repo

From source

bash

# 1. Clone
git clone https://github.com/stalzkie/local-forge.git
cd local-forge

# 2. Build the Rust binary
cargo build --release

# 3. Build the CoreML model
python3 coreml/build_model.py

# 4. Install the hook into your repo
./scripts/install_hook.sh /path/to/your/repo

How It Works

When git commit is run, the pre-commit hook extracts the staged diff and passes it through all three layers in sequence.

Layer 1 — Rust Regex

26 regex patterns compiled at binary startup match against the staged diff in under 1ms. Patterns cover 13 providers: AWS, GCP, Azure, Stripe, GitHub, Slack, Twilio, SendGrid, npm, PyPI, HuggingFace, Anthropic, and OpenAI. If any pattern matches, the commit is hard-blocked immediately.

[LocalForge] BLOCKED — secret detected: AWS Access Key ID
[LocalForge] Commit BLOCKED — a secret was detected in the staged diff.
[LocalForge] To suppress a false positive, add the file path to .localforgeignore

Layer 2 — CoreML / ANE

A binary classifier trained on 297 samples across 11 languages runs on the Apple Neural Engine. It outputs a risk score between 0 and 1. Scores above the threshold (default 0.5) hard-block the commit.

[LocalForge] Layer 2 score: 0.789 — commit blocked.
[LocalForge] Layer 2 score: 0.214 — clean.

Layer 3 — Qwen 7B LLM

Qwen2.5-Coder-7B runs locally via MLX and performs semantic code review across the staged diff. Upgraded from the 1.5B model in v2.1.3 — precision jumps from 0.649 to 0.982 and false positives drop from 40 to 1 on the 145-diff eval corpus.

Commits with no risky additions (refactors, deletions, whitespace) skip the model entirely via the clean-diff fast path. A post-inference filter suppresses known-safe patterns (parameterised queries, list-form subprocess calls, type-annotated variables) before writing the report. Layer 3 is advisory-only — it never blocks a commit.

[LocalForge] Qwen [MEDIUM] SQL injection risk detected
[LocalForge]   [SECURITY] Finding 1: sql_injection — String interpolation in raw SQL query.
[LocalForge]   Fix: use parameterised queries or an ORM
[LocalForge]   Full report: ~/.localforge/advisory_log/commit_...txt

Layer 3.5 — Static Analysis

Deterministic AST-level tools run alongside the LLM for categories that require more than pattern matching. Results are merged into the same advisory report. All tools are installed automatically by localforge --install.

Python — bandit (security), pylint (dead code, unused imports)
JavaScript / TypeScript — ESLint (no-unused-vars, no-eval)
Go — go vet, staticcheck
Rust — cargo clippy (suspicious, correctness, perf, dead_code)

[LocalForge] L3.5 [bandit] B608 SQL injection via string format — models/user.py:42
[LocalForge] L3.5 [pylint]  W0611 unused import os — api/routes.py:3
[LocalForge] L3.5 [clippy]  suspicious use of unwrap() — src/parser.rs:88

macOS App

The SwiftUI app provides a live window into every commit across all protected repos.

Monitor tab — streams real-time events from ~/.localforge/hook.log as layers run. Shows INFO, L1, L2, L3, OK, ERR, and ADV entries with color coding.
Repos tab — lists all registered repos with hook status: Active, Outdated, or Missing. One-click upgrade and Scan Folder to discover new repos automatically.

Commands & Flags

localforge --install [path]

Install the pre-commit hook into the specified repo (defaults to the current directory). Sets up ~/.localforge/, copies the binary, installs CoreML model, auto-downloads Qwen2.5-Coder-7B (falls back to 1.5B if already present), and installs all available static analysis tools.

localforge --install-org

Generate a portable team setup script (localforge-team-setup.sh). Share it in your setup docs or Makefile for one-command team-wide installation.

localforge --scan [path]

Run all three layers against a repo without making a commit. Useful for auditing existing code.

localforge --monitor

Start the monitor process which watches hook.log and streams events to the macOS app. Also starts the MCP server on port 7777.

localforge --export-report [out]

Bundle all advisory reports from ~/.localforge/advisory_log/ into a single compliance export file.

localforge --list-repos

List all repos currently registered with LocalForge and their hook status.

localforge --upgrade-hooks

Upgrade the pre-commit hook in all registered repos to the latest version.

localforge --remove [path]

Remove the LocalForge pre-commit hook from the specified repo.

MCP Server

LocalForge exposes a JSON-RPC 2.0 server on port 7777 that any MCP-compatible client — Cursor, VS Code, or a custom tool — can query to retrieve scan results from your editor.

Start the server:

bash

localforge --monitor

The MCP server starts automatically alongside the monitor process. It listens on localhost:7777 and is compliant with the MCP spec (JSON-RPC 2.0).

To connect Cursor: add LocalForge as an MCP provider pointing to http://localhost:7777.

.localforgeignore

Place a .localforgeignore file in the root of your repo to suppress false positives. Each line is a file path pattern excluded from all three layers.

bash

# .localforgeignore
tests/fixtures/bad_credential.py
config/test_keys.json
**/*.test.ts

Only use .localforgeignore for test fixtures and known false positives. Suppressing real production files defeats the purpose of the pipeline.

Compliance Export

All Layer 3 advisory reports are written to ~/.localforge/advisory_log/ as structured text files. Export them into a single compliance bundle:

bash

localforge --export-report ./compliance-export.txt

Each report contains the commit hash, timestamp, Qwen model version, severity, summary, and individual findings with fix suggestions. Suitable for SOC 2 audit trails or internal security reviews.

FAQ

Does anything leave my machine?

No. All four layers run entirely on-device. Layer 1 is pure Rust regex. Layer 2 runs on the Apple Neural Engine. Layer 3 runs Qwen2.5-Coder-7B via MLX entirely in local memory. Layer 3.5 runs local static analysis tools. No network calls are made during a scan.

Can I disable Layer 3 if I don't have a Qwen model?

Yes. If no Qwen model is found during install, Layer 3 is automatically skipped. localforge --install will auto-download the 7B model, but if you skip that step, commits still pass through Layers 1, 2, and 3.5.

Will it slow down my commits?

Layer 1 is under 1ms. Layer 2 is ~200ms on the ANE. Layer 3 uses a clean-diff fast path — commits with only refactors, deletions, or whitespace changes skip the 7B model entirely. You only wait the full ~5-8s if the diff has risky additions.

What if I get a false positive?

Add the file path to .localforgeignore in your repo root. This excludes that file from all three layers.

Does it work with GitHub Actions or CI?

LocalForge is a pre-commit hook — it runs locally before a push. It's not designed for CI pipelines, though the --scan flag can be run independently.

What languages does Layer 3 support?

Python, Rust, TypeScript, JavaScript, Go, Java, C, C++, Ruby, Swift, and Kotlin. Layer 3.5 static analysis covers Python, JavaScript/TypeScript, Go, and Rust with dedicated tools for each.