Forge

Opinionated Git workflows with AI-generated tests

Forge eliminates Git workflow friction by combining opinionated branching, automatic rebasing, and AI-generated tests — so developers ship faster with confidence. Built as a local-first developer platform, Forge simplifies Git branch workflows and automates test generation using AI without requiring cloud infrastructure or CI/CD overhead.

Why Forge Exists

Forge was born from working as an intern in high-velocity environments at Ross Video and Shopify, where shipping at lightning speeds is the norm. The only way to maintain that pace while ensuring code quality is to eliminate the friction points that slow developers down:

• Merge conflicts and rebasing that break flow and require manual resolution
• Forgotten or skipped tests that lead to production bugs
• Broken branches that block deployments and waste hours

Forge addresses these pain points by automating the entire workflow: branch management, rebasing, test generation, and validation — all running locally so you stay in control and move fast. I hated rebasing and making tests so I automated the process.

Who Forge Is For

Forge is designed for:

• Solo developers who want guardrails without heavy CI overhead
• Teams that enforce clean Git histories and test-first workflows
• Hackathon and startup environments where speed + correctness matter
• Developers tired of manually rebasing, writing boilerplate tests, and fixing broken branches

Why Not Just Use Git + Copilot?

Before Forge

• Manually create branches
• Manually rebase and resolve conflicts
• Write tests after the fact (or skip them)
• Forget to push or push broken tests

With Forge

• One command handles rebase + tests + validation
• Tests are generated based on actual diffs
• Branches stay clean and in sync
• Safer commits by default

Non-Goals

Forge intentionally does NOT:

• Replace Git or GitHub
• Auto-merge PRs
• Run in CI/CD (local-first by design)
• Modify production or base branches automatically

Requirements

• Python 3.10+
• Node.js 18+ (for dashboard)
• Git 2.30+
• macOS / Linux (Windows via WSL supported)

Quick Start

1. Install Forge:

   pip install -e .

2. Set up your AI provider API key in a .env file:

   FORGE_PROVIDER=gemini  # or openai
   GOOGLE_API_KEY=your-api-key-here  # for Gemini
   # OR
   # OPENAI_API_KEY=your-api-key-here  # for OpenAI

3. Start the dashboard (all-in-one setup):

   forge run

   Or use the repo-local dev launcher:

   ./dev up

   This automatically:

   • Creates a virtual environment if needed
   • Installs all dependencies (Python + Node.js)
   • Starts the FastAPI backend and React frontend
   • Opens the dashboard in your browser

4. Initialize Forge in your Git repository:

   forge init

5. Start using Forge commands:

   forge --help  # See all available commands

Commands

forge run

Start the Forge dashboard (FastAPI backend + React frontend). Automatically handles setup, dependency installation, and server startup.

forge run                          # Start with default ports
forge run --port 8000 --frontend-port 5173
forge run --skip-setup             # Skip dependency installation
forge run --no-open-browser        # Don't open browser automatically

./dev up

Repo-local developer entrypoint for bringing up Forge in one command.

./dev up
./dev up --no-open-browser
./dev up --port 8100 --frontend-port 5174

It bootstraps or reuses the project virtual environment, installs Python and frontend dependencies, and then starts the same backend + frontend stack as forge run.

forge init

Initialize Forge in the current Git repository. Creates .fg.yml configuration file.

forge init
forge init --base-branch main --test-dir tests/

forge branch

Create a new branch or list all branches.

forge branch                    # List all branches
forge branch feature/my-change  # Create new branch

forge switch

Switch to an existing branch.

forge switch feature/my-change

forge sync

Rebase current branch onto the base branch.

forge sync

forge create-tests

Generate AI-powered tests for changed files.

forge create-tests
forge create-tests --provider gemini --model gemini-2.0-flash-lite
forge create-tests --update  # Regenerate existing tests

forge test

Run existing tests.

forge test

forge submit

Complete workflow: sync, create-tests, test, commit, and push.

forge submit
forge submit --provider gemini --skip-tests

Workflow Example

# Create a feature branch
forge branch feature/my-change

# Make your code changes
# ... edit files ...

# Sync your branch with the base branch
forge sync

# Generate tests for changed files
forge create-tests

# Run tests
forge test

# Submit your branch (sync + create-tests + test + commit + push)
forge submit

Configuration

Forge uses a .fg.yml file in your repository root:

base_branch: main
language: python
test_framework: pytest
test_dir: tests/
include:
  - src/
exclude:
  - venv/
  - node_modules/

# AI Configuration (optional)
ai:
  provider: gemini
  model: gemini-2.0-flash-lite
  temperature: 0.3
  max_tokens: 2048

Configuration priority:

1. CLI flags (highest priority)
2. .fg.yml configuration
3. Environment variables from .env file
4. Defaults

AI Providers

Supported:

• openai: OpenAI GPT models (gpt-4-turbo-preview, gpt-4o-mini, etc.)
• gemini: Google Gemini models (gemini-2.0-flash-lite, etc.)

Set your provider in .env:

FORGE_PROVIDER=gemini
GOOGLE_API_KEY=your-key-here

Dashboard

Forge includes a web-based dashboard for visualizing repository metrics and tracking test generation across multiple repositories.

Features:

• Multi-repository tracking with SQLite database
• Repository and branch visualization
• Commit history and metrics
• Test generation event tracking
• Cross-repo analytics

Start the dashboard:

forge run

The dashboard runs on http://localhost:5173 (frontend) with the API at http://localhost:8000 (backend).

Language Support

Currently Supported:

• Python (pytest)

Coming Soon:

• Go (testing package)
• Java (JUnit)
• Ruby (RSpec)
• TypeScript/JavaScript (Jest, Vitest)
• More languages and frameworks

AI Models Support

Currently Supported:

• Google Gemini (gemini-2.0-flash-lite, etc.)
• OpenAI (gpt-4-turbo, gpt-4o-mini, etc.)

Coming Soon:

• Claude (Anthropic)
• Deepseek
• Other AI models for test generation

Architecture

forge/
├─ cli.py              # CLI interface
├─ core/               # Core functionality
│  ├─ config.py        # Configuration management
│  ├─ git_ops.py       # Git operations
│  └─ diff.py          # Change detection
├─ services/           # Business logic services
│  └─ test_service.py  # AI test generation
├─ ai/                 # AI provider abstraction
│  ├─ base.py          # AIProvider interface
│  ├─ config.py        # AI configuration parsing
│  ├─ openai.py        # OpenAIProvider
│  ├─ gemini.py        # GeminiProvider
│  └─ registry.py      # Provider registry
├─ adapters/           # Language/framework adapters
│  └─ python/
│     └─ pytest_adapter.py
├─ database/           # Database models and utilities
│  ├─ models.py        # SQLAlchemy models
│  ├─ scanner.py       # Repository scanning
│  └─ tracker.py       # Event tracking
├─ backend/            # FastAPI backend
│  └─ app.py           # API endpoints
├─ utils/              # Utility functions
│  ├─ ast_parser.py    # AST parsing for Python
│  └─ validation.py    # Input validation
└─ metadata/           # Metadata management
   └─ branches.py      # Branch metadata

Safety Features

• ✅ Never auto-commits failing tests
• ✅ Never modifies the base branch
• ✅ All Git failures surface clearly
• ✅ Respects .gitignore
• ✅ Aborts on partial failures
• ✅ API keys never stored in config files