Skip to content
LocalForgeLocalForge

Documentation

LocalForge Docs

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

Introduction

LocalForge is a 3-layer Rust + CoreML + LLM 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 three 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 via MLX: semantic code review in ~5-8s. Advisory only — never blocks commits.

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-1.5B model weights in your HuggingFace cache (Layer 3, 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, detects Qwen in your HuggingFace cache, and installs 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 LLM

Qwen2.5-Coder-1.5B runs locally via MLX and performs semantic code review across the staged diff. It reports SQL injection, XSS, command injection, dead code, unhandled errors, and logic bugs with severity labels (HIGH / MEDIUM / LOW). 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

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 and Qwen model if found.

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 three 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 via MLX entirely in local memory. No network calls are made.

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. Commits still pass through Layers 1 and 2.

Will it slow down my commits?

Layer 1 is under 1ms. Layer 2 is ~200ms on the ANE. Layer 3 runs asynchronously after a clean Layer 1 + 2 pass — it doesn't hold the commit. You only wait if Layers 1 or 2 find something.

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.