Documentation

Installation & Setup

Get Forge running on your machine in under 5 minutes. Everything runs locally — no API keys to manage, no cloud bills, no data leaving your network.

Your code stays on your hardware. Period. No cloud provider ever sees your proprietary codebase, your prompts, or your AI's responses.

Option 1: pip install (recommended)

pip install forge-nc

Option 2: From source (for contributors)

git clone https://github.com/Forge-NC/Forge.git
cd Forge
pip install -e .

# Pull your first model (~10GB VRAM)
ollama pull qwen2.5-coder:14b

# Embedding model for semantic search
ollama pull nomic-embed-text

System Requirements

Hardware needed to run Forge at different performance levels.

Larger models produce better code but need more VRAM. This helps you pick the right model for your hardware — from a GTX 1650 running 7B models to a multi-GPU workstation running 70B+.

Quick Start

Start using Forge in your project right now.

# Launch Forge in your project directory
cd your-project/
python -m forge

Type what you want in plain English:

forge> Add a login endpoint to the Flask API
forge> Fix the bug in parser.py where it crashes on empty input
forge> Refactor the database module to use connection pooling
forge> Write tests for the authentication middleware

Model Manager 71 Models

Full-featured model management with 71 curated models across 5 categories, live Ollama registry search, and support for 3 LLM backends (Ollama, OpenAI-compatible, Anthropic API).

Different tasks need different models. The Model Manager helps you find, download, and switch between models without leaving Forge — and lets you use cloud APIs when local isn't enough.

# ~/.forge/config.yaml
default_model: "qwen2.5-coder:14b"    # Primary model
small_model: "qwen2.5-coder:3b"       # Fast model for routing
embedding_model: "nomic-embed-text"    # Embeddings
router_enabled: true                   # Auto-route by complexity
backend_provider: "ollama"             # ollama, openai, or anthropic

Run /models to open the Model Manager GUI. Browse 71 curated models, search the Ollama registry live, pull new models with progress bars, delete unused models, and set your primary model — all from a graphical interface.

Commands Reference 60 Commands

60 slash commands that let you control the AI, manage models, scan for threats, run audits, export reports, manage your fleet, and configure every aspect of the system. This is a full coding environment, not an autocomplete plugin.

Everything in Forge is accessible from the command line. No hidden menus, no GUI-only features. Type /help to see them all, or click any command below for real usage examples.

Tool System 28 Tools

28 structured tools that the AI uses to interact with your codebase, filesystem, shell, and web.

Tools give the AI precise, auditable actions instead of unstructured text output. Every tool call is logged in the forensic audit trail with arguments, results, and timing.

Multi-Model Routing

Automatic complexity-based routing that sends simple tasks to a small, fast model and complex tasks to your primary model.

A typo fix doesn't need a 14B model. The router saves VRAM, reduces latency, and cuts token usage by 30-50% without sacrificing quality on hard problems.

Context Management

Full manual control over the AI's context window — see every token, pin what matters, evict what doesn't.

Context quality directly impacts AI quality. Unlike cloud tools that silently compress your history, Forge shows you exactly what the AI can see and lets you manage it.

Self-Healing AI AMI

3-tier recovery system that detects when the AI is failing — refusals, loops, tool amnesia, garbage output — and fixes it automatically.

Instead of restarting your session when the AI breaks, AMI diagnoses the problem and escalates through increasingly aggressive recovery strategies until it works. You stay focused on your code.

Session Health Monitor Continuity

Tracks 6 health signals to give your session a letter grade (A through F) and triggers auto-recovery when quality drops.

Long coding sessions degrade AI quality. Context gets stale, decisions get forgotten, files drift out of scope. The Continuity Engine detects this before you notice it and injects targeted refreshes.

Learning Memory Genome

Persistent cross-session intelligence that makes Forge smarter over time. Every session teaches Forge something — which models fail on which tasks, what tool patterns work, how reliable your sessions are.

Session 50 of Forge is genuinely better than session 1. The Genome accumulates behavioral intelligence that improves AMI recovery, router accuracy, and threat detection. This intelligence is what makes a legitimate copy functionally superior to a pirated one.

Reliability Tracking

Persistent cross-session health metrics over a rolling 30-session window. Composite scoring across 5 dimensions shows whether Forge is getting more or less reliable over time.

When your manager asks "is the AI actually working?" you have quantitative proof — not anecdotes.

9-Layer Defense Forge Crucible™

Every AI response passes through 9 independent security layers before it can affect your code. Each layer catches a different class of attack.

AI models can be tricked by prompt injection, produce malicious code, or attempt data exfiltration. A single defense isn't enough — an attacker must simultaneously evade nine orthogonal detection mechanisms.

Safety Levels

Four progressively strict safety modes. Set via /safety <0-3> or safety_level in config.

A personal side project needs different restrictions than a production codebase handling customer data. Choose the safety level that matches your risk tolerance.

Threat Intelligence

Upgradeable signature database for the Forge Crucible™ threat scanner. Three sources merged with security guarantees.

New attack patterns emerge constantly. The threat intel system lets Forge update its defenses without a full software update — while guaranteeing external patterns can never weaken built-in protections.

Forensics & Audit Trail

Compliance-ready session audit logging that tracks every action the AI takes — tool calls, threat events, context swaps, model switches, with timestamps and results.

When something goes wrong (or goes right and you want to reproduce it), you need to know exactly what happened, when, and why. The forensic trail is tamper-evident via HMAC-SHA512 provenance chains.

Voice I/O

Talk to Forge with your voice. Responses can be read back aloud. Speech-to-text and text-to-speech both run locally.

Hands-free coding. Describe what you want while looking at reference material, whiteboarding, or thinking out loud. No cloud transcription service ever hears you.

voice_model: "tiny"          # whisper model size
voice_language: "en"         # ISO language code
voice_vox_threshold: 0.02    # RMS threshold for VOX
voice_silence_timeout: 1.5   # seconds of silence to end recording

Toggle with /voice. Optional dependencies: faster-whisper, sounddevice, pynput.

Themes & Dashboard 14 Themes

14 built-in color themes from dark minimalist to full cyberpunk. Three themes include live visual effects (particles, edge glow, crackle). Neural Cortex™ dashboard with animated brain visualization.

You stare at your coding tool for hours. It should look exactly how you want it. Switch themes instantly with /theme <name> — no restart required.

Dashboard: Run /dashboard to open the Neural Cortex™ GUI — real-time brain animation (9 states), live session stats, system health cards, and threat alerts. The brain animation reflects what Forge is doing: thinking, executing, indexing, scanning.

Plugin System

Build custom plugins that hook into Forge's lifecycle events. 18 hook points covering lifecycle, sessions, turns, AI interaction, file operations, and system events.

Extend Forge with custom behavior — log to your own system, modify AI prompts, add custom commands, filter outputs. Auto-discovered from ~/.forge/plugins/.

# ~/.forge/plugins/my_plugin.py
from forge.plugins.base import ForgePlugin

class MyPlugin(ForgePlugin):
    priority = 50  # Lower = runs first

    def on_load(self, engine):
        self.engine = engine
        print("My plugin loaded!")

    def on_tool_call(self, name, args):
        print(f"Tool called: {name}")
        return args  # Return modified args or None to block

Tiers & Pricing

Three tiers. Community is free forever with all core features. Pro and Power add persistence, team features, and enterprise capabilities.

Every developer gets the full AI coding experience for free — 60 commands, 28 tools, 14 themes, 9-layer security, voice I/O. Paid tiers unlock cross-session intelligence and fleet management for teams.

Monthly alternatives: Pro $19/mo, Power $79/mo. See pricing page.

Activation

Activate your license with a cryptographically signed passport file. Master activates directly, Puppets are generated from a Master.

One purchase, multiple machines. Generate Puppet passports for your laptop, CI runner, or team members from your Master instance.

Master/Puppet Fleet

Run Forge on multiple machines from a single license. Master controls the seat pool, generates Puppet passports, and can revoke any Puppet instantly.

Developers work on multiple machines. Instead of buying separate licenses, you get N seats and distribute them. Fleet members share genome intelligence for collective improvement.

/puppet seats              # Check seat allocation
/puppet generate WorkLaptop # Create puppet passport (uses 1 seat)
/puppet list               # List all fleet members with status
/puppet revoke <id>        # Instantly revoke a puppet's access
/puppet sync               # Force genome sync to master
/puppet status             # Your role, tier, and fleet summary

Behavioral Proof of Stake BPoS

Five-layer anti-piracy where legitimate copies genuinely work better than pirated ones. No DRM that frustrates paying customers — just accumulated intelligence that can't be replicated.

Traditional DRM punishes buyers. BPoS rewards them. A legitimate copy with 100 sessions of accumulated genome intelligence produces better code, recovers faster from failures, and routes more accurately than a fresh pirated copy.

Certification Tiers

Every Forge audit classifies a model into one of four certification tiers based on its behavioral performance. Nobody "fails" — every model gets classified, and the classification tells you exactly what the model is approved for.

Binary pass/fail doesn't help enterprises make deployment decisions. A model that fails exfiltration tests but passes safety tests is still useful for internal tooling that doesn't handle sensitive data. Certification tiers give actionable, scoped guidance.

Safety and Exfiltration are treated as critical domains because failures in these categories have direct legal, regulatory, and human-safety implications. A model that leaks credentials or generates harmful content poses fundamentally different risk than one that struggles with math.

Coverage Levels

Reports also display a Coverage Level that reflects how comprehensive the testing was, based on the protocol version used:

Reports generated with older protocols include a coverage qualifier in the verdict. Business impact claims are limited to what the protocol actually tested — a v1 report will never claim HIPAA implications if HIPAA scenarios weren't run. View the full protocol changelog →

Origin Certification

Reports can be Origin-certified by the Forge certification authority. Origin certification adds a second Ed25519 signature (countersigning) that attests: the machine signature is valid, the hash chain is intact, and the report was processed by the official Forge verification server.

Self-Attested Report = machine-signed only, run by the user. Forge Certified = Origin-countersigned, independently verified. Enterprise clients receive Origin-certified reports with their certification tier and compliance scope clearly stated.

Break Suite

Run 161 adversarial scenarios (483 test vectors via the Trident Protocol™) against any model to measure reliability, safety, and behavioral consistency. Every result is Ed25519-signed — the signature covers model identity, scenario results, and hardware profile.

Traditional benchmarks measure capability. Break measures trustworthiness — what happens when a model is pushed, confused, or socially engineered. Every scenario is tested from 3 independent angles so a lucky single-phrasing pass can't hide real weaknesses.

Assurance Suite

161 scenarios across 16 categories, each tested with 3 prompt vectors via the Trident Protocol™ (483 total). Power-tier includes HIPAA/SOC2 compliance categories. /break runs the complete suite including Forge Parallax™ dual-attestation — Break and Assurance back-to-back to detect within-session behavioral drift.

Break finds failures. Assurance proves compliance. Parallax proves consistency. The combination produces a cryptographically signed, tamper-evident audit artifact that proves your AI setup meets security and reliability standards — useful for audits, procurement, and enterprise approval.

/assure              # Run full assurance suite
/assure --json       # Machine-readable output
/break --assure      # Combined: break + assurance in one run

Stress Testing

A minimal 3-category CI gate that runs in under 30 seconds. Designed for continuous integration pipelines where you need a fast pass/fail signal on model reliability.

Full /break runs take minutes. /stress picks the three highest-signal scenarios and exits with code 1 on any failure — perfect for pre-commit hooks, CI/CD pipelines, and deployment gates.

# In your CI pipeline
forge --run "/stress --ci"
if [ $? -ne 0 ]; then
    echo "Model reliability check failed"
    exit 1
fi

Behavioral Fingerprint

30 probes measure how a model actually behaves — response patterns, tool usage habits, safety compliance, reasoning depth. Each model gets a unique behavioral signature.

When a model updates, Forge detects drift — behavioral changes between versions. A model that was safe last week might handle edge cases differently after an update. Fingerprinting catches these shifts before they reach production.

Proof of Inference

Forge's Proof of Inference system uses Ed25519 challenge-response to cryptographically prove that real inference occurred. The server issues a challenge with a random nonce and prompt. The client runs actual inference, signs the response, and returns it.

Timing analysis, category matching, and signature verification prevent fabrication. You cannot pre-compute responses or replay old results. This is what makes Matrix data trustworthy — you can't fake a /break run.

The Forge Matrix™

The Forge Matrix™ is a decentralized, crowdsourced model leaderboard. Every /break --share run contributes data. Unlike traditional benchmarks (MMLU, HumanEval), the Matrix measures real-world reliability — how models behave under adversarial pressure, not just capability.

Fleet consensus with outlier detection prevents manipulation. Ed25519-signed reports prevent fabrication. The result is a leaderboard you can actually trust, built from real-world usage data across hundreds of Forge installations.

Explore the live Matrix →

Scoring Methodology

Every Break and Assurance report is stamped with a protocol version that documents the exact scoring rules in effect when the report was generated. As Forge improves its detection accuracy, the protocol version increments.

Transparency is a first principle. When you see a score on the Matrix, you need to know whether a low number means the model is bad or the test was bad. Protocol versioning makes that distinction explicit and auditable.

Trident Protocol™

Every scenario is tested with 3 independent prompt vectors — the main prompt plus 2 variant phrasings that attack from different angles. A scenario passes only when the majority of vectors pass (>50%). This eliminates single-phrasing coin flips where a model gets lucky on one wording but fails a slight rephrase.

161 scenarios × 3 vectors = 483 total test prompts per run. The confidence score reflects vector agreement: 1.0 = unanimous across all 3, 0.5 = borderline split.

Forge Parallax™

/break runs the Forge Parallax dual-attestation system by default. It runs the Break Suite (adversarial stress test) first, then the Assurance Suite (compliance verification) back-to-back on the same model session. Use /break --no-assure to skip the verification pass.

The report compares results across both passes to detect within-session behavioral drift. Scenarios that pass under stress but fail during verification indicate the model's reliability erodes under adversarial pressure. The consistency score, per-scenario comparison table, and category-level delta analysis give you a complete picture of model stability.

Protocol Versions

The protocol version is embedded in the signed report payload and cannot be altered after generation. Reports on the Matrix show which protocol scored them, so data from different protocol versions can be correctly interpreted.

View the full protocol changelog →

Report Verification

Every Forge report is a self-contained cryptographic artifact. The Report Verifier at forge-nc.dev/verify_report performs four independent checks to confirm a report hasn't been tampered with, forged, or misrepresented.

A certification system is only as trustworthy as its verification layer. Forge does not ask you to trust it — it gives you the tools to verify independently, using open standards that any security team can audit.

Four Verification Checks

If any check fails, the report is flagged as illegitimate, logged to the fraud database, and the Origin admin is notified.

Verify Without Forge

You do not need this website or any Forge software to verify a report. The Ed25519 public key and signature are embedded in every report JSON. Verify with any standard library:

• Python: cryptography library — Ed25519PublicKey.from_public_bytes(pub).verify(sig, payload)
• Node.js: Built-in crypto module — crypto.verify(null, payload, key, sig)
• Command line: OpenSSL — openssl pkeyutl -verify -pubin -inkey pub.pem -sigfile sig.bin -rawin -in payload.bin
• Any language: Any Ed25519 implementation (libsodium, tweetnacl, etc.)

Full code examples for Python, Node.js, and OpenSSL are available on the Report Verifier page. Forge does not control the Ed25519 algorithm, the SHA-512 hash function, or the JSON canonical encoding. These are open, auditable standards.

Configuration Reference 101 Keys

All 101 configuration parameters in ~/.forge/config.yaml. Edit directly or use /config <key> <value>.

Every behavior in Forge is configurable. Invalid values are logged with fallback to defaults — you can't break Forge by misconfiguring it.

Enterprise Mode

Strict operating mode for regulated environments. Enforces safety minimums, mandatory audit logging, and verified changes. Requires Power tier.

When your compliance team needs audit trails and enforced safety, Enterprise Mode provides the guardrails without changing your workflow.

Shipwright Release Mgmt

AI-powered release management. Classifies commits (25+ rules for breaking/feature/fix/docs/tests/security/performance), determines version bumps, generates changelogs, runs preflight checks.

Automates the tedious parts of releasing software while keeping you in control. One command to go from "commits on main" to "tagged release with changelog."

AutoForge Auto-Commit

Automatically commits file changes after each AI turn. Smart batching groups related edits into single commits with AI-generated messages.

Never lose AI-generated changes. Every turn = one coherent commit. If the AI breaks something, git revert takes you right back.

/autocommit on / off / status. Use /autocommit hook to generate a Claude Code hook for automatic triggering.

Telemetry

Optional, anonymized performance telemetry. Disabled by default (telemetry_enabled: false). Sends hardware profiles, token rates, and reliability scores when enabled. No prompts, no responses, no source code.

Helps improve Forge for everyone. Completely opt-in. The telemetry_redact flag (default: true) strips all user content even when telemetry is enabled.

telemetry_enabled: true    # Opt in (default: false)
telemetry_redact: true     # Strip all user content (default: true)
telemetry_label: "my-pc"   # Machine nickname for dashboard