Installation

Prerequisites

Before installing Forge, make sure you have:

Node.js (v18 or higher)

# 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

Git

# Check if Git is installed
git --version

Forge uses Git worktrees for isolation, so Git is required.

LLM API Keys

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

Install Forge as a project dependency:

npm install --save-dev @automagik/forge

Add to your package.json scripts:

{
  "scripts": {
    "forge": "forge"
  }
}

Run with:

npm run forge

Run Forge without installing:

npx automagik-forge

Great for trying it out or one-time use!

Clone and build from source:

# Clone the repository
git clone https://github.com/namastexlabs/automagik-forge.git
cd automagik-forge

# Install dependencies
npm install

# Build
npm run build

# Link globally
npm link

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

Command not found: forge

If you installed globally but get “command not found”:

Check NPM global bin path:
npm config get prefix

Add to your PATH (add to ~/.bashrc or ~/.zshrc):

export PATH="$PATH:$(npm config get prefix)/bin"

Reload your shell:
source ~/.bashrc # or ~/.zshrc

Permission denied errors

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

Git worktree errors

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

Getting Started

Learn

Configuration

Reference

Troubleshooting

Prerequisites

Installation Methods

Configuration

Verify Installation

Troubleshooting

Next Steps

Quick Start

Introduction

​Prerequisites

​Installation Methods

​Configuration

​Verify Installation

​Troubleshooting

​Next Steps

Quick Start

Introduction

Prerequisites

Installation Methods

Configuration

Verify Installation

Troubleshooting

Next Steps