Skip to main content

​
Prerequisites

Before installing Forge, make sure you have: 
# Check your Node.js version
node --version

# Should output v18.0.0 or higher
If you need to install or upgrade Node.js:
  • macOS: brew install node
  • Ubuntu/Debian: sudo apt install nodejs npm
  • Windows: Download from nodejs.org
# Check if Git is installed
git --version
Forge uses Git worktrees for isolation, so Git is required.
You’ll need API keys for the LLMs you want to use:
  • Claude: Anthropic API key
  • Gemini: Google AI API key
  • OpenAI: OpenAI API key
  • Others as needed

​
Installation Methods

  • NPM (Global)
  • NPM (Project)
  • NPX (No Install)
  • From Source
Install Forge globally to use it from anywhere:
npm install -g automagik-forge
Verify installation:
forge --version

​
Configuration

After installation, configure Forge with your LLM API keys: 
# Initialize Forge in your project
forge init

# This creates a .forge/ directory with configuration
Set up your API keys in .forge/config.json: 
{
  "llms": {
    "claude": {
      "apiKey": "your-anthropic-api-key",
      "model": "claude-3-5-sonnet-20241022"
    },
    "gemini": {
      "apiKey": "your-google-api-key",
      "model": "gemini-2.0-flash-exp"
    }
  }
}
Security Tip: Never commit .forge/config.json to version control! Add it to .gitignore.

​
Verify Installation

Test that everything is working: 
# Check version
forge --version

# Get help
forge --help

# Initialize a project (if not done yet)
forge init
You should see output similar to: 
automagik-forge v1.0.0

Forge initialized successfully!
Configuration saved to .forge/config.json

​
Troubleshooting

If you installed globally but get “command not found”:
  1. Check NPM global bin path: 
    npm config get prefix
  2. Add to your PATH (add to ~/.bashrc or ~/.zshrc): 
    export PATH="$PATH:$(npm config get prefix)/bin"
  3. Reload your shell: 
    source ~/.bashrc  # or ~/.zshrc
On macOS/Linux, you might need sudo for global installs:
sudo npm install -g automagik-forge
Or configure NPM to use a different directory (recommended):
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
Make sure you’re in a Git repository:
git init  # If not already a Git repo
Forge requires Git to create isolated worktrees.

​
Next Steps

Quick Start

Create your first AI-powered task

Introduction

Learn more about Forge