// documentation

FixGuard Documentation

Safe Code Evolution. Zero Guesswork.

Table of Contents

  1. Core Principles
  2. Requirements
  3. Installation
  4. Commands
  5. Features
  6. AI Provider Setup
  7. Configuration
  8. CI/CD Integration
  9. Troubleshooting

Core Principles

Principle Description
AI has zero authority Tools and tests are the judges, not AI
Every change is verifiable Backed by real linters, scanners, tests
Every change is reversible Git-based snapshots for instant rollback
Every action is logged Immutable, timestamped run logs
If uncertain → report Never guess, always report

Requirements

System Requirements

Requirement Version Notes
Node.js 18+ Required for CLI
npm 9+ Package manager
Python 3.9+ For analyzers (optional)
Git 2.0+ For snapshots

Optional Dependencies

Tool Purpose Auto-detected
ESLint JavaScript/TypeScript analysis ✓
Ruff Python analysis ✓
Bandit Python security scanning ✓
Jest/Vitest/Mocha JavaScript testing ✓
pytest Python testing ✓

Installation

From npm (Recommended)

npm install -g fixguard

From Source

# Clone the repository
git clone https://github.com/your-org/fixguard.git
cd fixguard

# Install dependencies
npm install

# Build
npm run build

# Link globally
npm link

# Verify installation
fixguard --version

Verify Installation

fixguard --help

Expected output:

Usage: fixguard [options] [command]

A verifiable, local-first system for safe code evolution

Commands:
  scan [options] <path>        Analyze and optionally fix code issues
  heal [options] <path>        AI-powered test generation and fix loop
  report [options] <path>      Generate analysis reports
  rollback [options] <run-id>  Rollback changes from a specific run
  help [command]               display help for command

Commands

fixguard scan

Analyze code for issues with optional auto-fixing.

# Read-only analysis (default)
fixguard scan .

# Auto-fix low-risk issues
fixguard scan . --auto-fix

# Guided refactor (propose all changes)
fixguard scan . --mode=guided-refactor

# CI mode (strict, exits 1 on errors)
fixguard scan . --ci

Options

Flag Description Default
--auto-fix Apply low-risk fixes automatically off
--mode <mode> observe, safe-fix, guided-refactor, ci observe
--ci CI mode: strict, non-interactive off
--config <path> Custom configuration file -
-v, --verbose Show detailed output off
-q, --quiet Suppress non-essential output off

Execution Modes

Mode Description Auto-Fix Interactive
observe Read-only analysis ✗ ✓
safe-fix Apply low-risk fixes ✓ ✓
guided-refactor Propose all changes ✓ (approval) ✓
ci Strict, non-interactive ✗ ✗

fixguard heal

AI-powered test generation and fix loop.

# Use Ollama (local, free - default)
fixguard heal .

# Use OpenAI
fixguard heal . --ai-provider=openai

# Use Groq (free cloud)
fixguard heal . --ai-provider=groq

# Limit iterations
fixguard heal . --max-iterations=3

# Dry run (preview only)
fixguard heal . --dry-run

Options

Flag Description Default
--max-iterations <n> Maximum fix attempts 5
--ai-provider <name> ollama, openai, anthropic, groq ollama
--model <model> AI model name codellama
--dry-run Preview without applying off

How It Works

1. Create safety snapshot
2. Run existing tests
3. For each failure → AI generates fix
4. Apply fix
5. Re-run tests
6. Repeat until pass or max iterations
7. Show summary

fixguard report

Generate analysis reports.

# Markdown report (default)
fixguard report .

# JSON report
fixguard report . --format=json

# SARIF report (for GitHub/GitLab)
fixguard report . --format=sarif

# Custom output path
fixguard report . --output=./reports/scan.md

Options

Flag Description Default
--format <fmt> markdown, json, sarif markdown
--output <path> Output file path stdout
--run-id <id> Report for specific run latest

fixguard rollback

Revert changes from a specific run.

# Rollback by run ID
fixguard rollback abc123

# Preview what would be restored
fixguard rollback abc123 --dry-run

Run IDs are shown after each scan/heal operation.

Features

Multi-Language Support

Language Static Analysis Security Scan Fix Templates
TypeScript ✓ ESLint ✓ Secrets ✓ 15+ rules
JavaScript ✓ ESLint ✓ Secrets ✓ 15+ rules
Python ✓ Ruff ✓ Bandit ✓ 10+ rules
Go ✓ ✓ ○
Rust ✓ ✓ ○
Java ✓ ✓ ○

Security Hardening (OWASP-Compliant)

  • ✓ Hardcoded secret detection (API keys, passwords)
  • ✓ SQL injection prevention
  • ✓ XSS vulnerability detection
  • ✓ Rate limiting checks
  • ✓ Input validation checks

Supported Fixes

JavaScript/TypeScript

  • no-unused-vars - Remove unused variables
  • semi - Add missing semicolons
  • eqeqeq - Use strict equality (===)
  • prefer-const - Use const instead of let
  • no-var - Use let/const instead of var
  • no-console - Remove console statements
  • no-trailing-spaces - Remove trailing whitespace

Python

  • F401 - Remove unused imports
  • F841 - Remove unused variables
  • E711 - Use is None instead of == None
  • W291 - Remove trailing whitespace
  • W292 - Add newline at end of file

Security

  • secret-detection - Move secrets to environment variables

AI Provider Setup

Option 1: Ollama (Local, Free) - RECOMMENDED

# Step 1: Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Step 2: Start the Ollama server
ollama serve

# Step 3: Pull a model (one-time, ~4GB download)
ollama pull codellama

# Step 4: Use FixGuard
fixguard heal .

Pros: Free, private, no API key needed
Cons: Requires ~4GB disk space, local compute

Option 2: Groq (Cloud, Free Tier) - FAST!

# Step 1: Get FREE API key from https://console.groq.com

# Step 2: Set environment variable
export GROQ_API_KEY=gsk-your-key-here

# Step 3: Use FixGuard with Groq
fixguard heal . --ai-provider=groq

Pros: Free tier, very fast inference
Cons: Requires internet, API key

Option 3: OpenAI (Cloud, Paid)

# Step 1: Get API key from https://platform.openai.com

# Step 2: Set environment variable
export OPENAI_API_KEY=sk-your-key-here

# Step 3: Use FixGuard with OpenAI
fixguard heal . --ai-provider=openai --model=gpt-4

Pros: High quality, GPT-4
Cons: Paid, requires API key

Option 4: Anthropic Claude (Cloud, Paid)

# Step 1: Get API key from https://console.anthropic.com

# Step 2: Set environment variable
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# Step 3: Use FixGuard with Anthropic
fixguard heal . --ai-provider=anthropic

Configuration

Environment Variables

Variable Description
OPENAI_API_KEY OpenAI API key
ANTHROPIC_API_KEY Anthropic API key
GROQ_API_KEY Groq API key
PROOFFIX_DEBUG Enable debug logging

Project Structure

After running FixGuard, your project will have:

your-project/
├── .fixguard/
│   ├── logs/           # Run logs (JSON)
│   ├── snapshots/      # Git snapshots
│   └── reports/        # Generated reports

CI/CD Integration

GitHub Actions

name: FixGuard Scan

on: [push, pull_request]

jobs:
  fixguard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g fixguard
      - run: fixguard scan . --ci

GitLab CI

fixguard:
  image: node:20
  script:
    - npm install -g fixguard
    - fixguard scan . --ci
  artifacts:
    reports:
      sast: .fixguard/reports/sarif.json

Exit Codes

Code Meaning
0 Success, no issues
1 Issues found or error

Troubleshooting

"AI provider not available"

Cause: Ollama is not running or API key not set.

Solution:

# For Ollama
ollama serve

# For cloud providers
export OPENAI_API_KEY=sk-...  # or
export GROQ_API_KEY=gsk-...

"Snapshot not found for run ID"

Cause: Running rollback from wrong directory.

Solution: Run rollback from the same directory where the scan was executed.

"Tests: 0 passed, 0 failed"

Cause: No tests detected in project.

Solution: Add tests using Jest, Mocha, Vitest (JS) or pytest (Python).

ESLint not finding issues

Cause: ESLint not installed in project.

Solution:

npm install --save-dev eslint
npx eslint --init

Links

License

MIT License

Made with 🖤 for developers who value safe, verifiable code evolution.