LLM Configuration - Automagik Suite Documentation

Overview

Forge supports 8 AI coding agents out of the box. Each agent needs proper configuration before use.

BYOL Architecture: Forge uses a “Bring Your Own LLM” model - you provide API keys, Forge handles orchestration.

Supported AI Agents

Agent	Type	Setup Required
Claude Code	API	Anthropic API key
Claude Code Router	API	Any LLM API key (agnostic)
Cursor CLI	CLI	Cursor account
Gemini	API	Google AI API key
OpenAI Codex	API	OpenAI API key
Amp	API	Sourcegraph token
OpenCode	Local	Model weights
Qwen Code	Local	Model weights

Configuration File

Forge stores LLM configuration in .forge/config.json:

.forge/config.json

{
  "llms": {
    "claude": {
      "apiKey": "sk-ant-...",
      "model": "claude-3-5-sonnet-20241022",
      "maxTokens": 4096
    },
    "gemini": {
      "apiKey": "AIza...",
      "model": "gemini-2.0-flash-exp"
    },
    "openai": {
      "apiKey": "sk-...",
      "model": "gpt-4-turbo",
      "organization": "org-..."
    }
  },
  "worktrees": {
    "enabled": true,
    "basePath": "./.forge/worktrees"
  }
}

Never commit .forge/config.json! Add it to .gitignore immediately:

echo ".forge/" >> .gitignore

Claude Code Setup

Get Your API Key

Create Anthropic Account

Go to console.anthropic.com

Generate API Key

Navigate to API Keys → Create Key

Configure Forge

{
  "llms": {
    "claude": {
      "apiKey": "sk-ant-api03-...",
      "model": "claude-3-5-sonnet-20241022",
      "maxTokens": 8192
    }
  }
}

Available Models

Model	Context	Best For
`claude-3-5-sonnet-20241022`	200K	General coding (recommended)
`claude-3-opus-20240229`	200K	Complex refactoring
`claude-3-haiku-20240307`	200K	Fast iterations

Advanced Configuration

{
  "llms": {
    "claude": {
      "apiKey": "sk-ant-...",
      "model": "claude-3-5-sonnet-20241022",
      "maxTokens": 8192,
      "temperature": 0.7,
      "timeout": 60000,
      "retries": 3
    }
  }
}

Claude Code Router Setup

Claude Code Router is LLM-agnostic - use any model with an OpenAI-compatible API!

Configuration

{
  "llms": {
    "claude-router": {
      "apiKey": "your-api-key",
      "baseUrl": "https://api.openai.com/v1",  // Or any compatible endpoint
      "model": "gpt-4-turbo",
      "provider": "openai"  // openai, anthropic, custom
    }
  }
}

Supported Providers

OpenAI
Anthropic
Local (Ollama)
Custom

{
  "claude-router": {
    "apiKey": "sk-...",
    "baseUrl": "https://api.openai.com/v1",
    "model": "gpt-4-turbo",
    "provider": "openai"
  }
}

Gemini Setup

Get Your API Key

Go to Google AI Studio

Visit aistudio.google.com

Get API Key

Click “Get API Key” → Create API key

Configure Forge

{
  "llms": {
    "gemini": {
      "apiKey": "AIza...",
      "model": "gemini-2.0-flash-exp"
    }
  }
}

Available Models

Model	Context	Best For
`gemini-2.0-flash-exp`	1M	Fast iterations (recommended)
`gemini-1.5-pro`	2M	Large codebases
`gemini-1.5-flash`	1M	Quick tasks

Cursor CLI Setup

Cursor CLI is separate from the Cursor IDE. You can use it independently!

Installation

# Install Cursor CLI
npm install -g @cursor/cli

# Authenticate
cursor auth login

Configuration

{
  "llms": {
    "cursor": {
      "enabled": true,
      "model": "claude-3.5-sonnet",
      "workingDirectory": "."
    }
  }
}

Cursor CLI respects your Cursor account subscription - no additional API keys needed!

OpenAI Codex Setup

Get Your API Key

Create OpenAI Account

Go to platform.openai.com

Generate API Key

Navigate to API Keys → Create new secret key

Configure Forge

{
  "llms": {
    "openai": {
      "apiKey": "sk-...",
      "model": "gpt-4-turbo",
      "organization": "org-..."  // Optional
    }
  }
}

Available Models

Model	Context	Best For
`gpt-4-turbo`	128K	General coding
`gpt-4`	8K	Legacy tasks
`gpt-3.5-turbo`	16K	Simple tasks

Open Source Agents

OpenCode (Local)

# Download model
ollama pull opencode

# Configure Forge

{
  "llms": {
    "opencode": {
      "enabled": true,
      "model": "opencode:latest",
      "endpoint": "http://localhost:11434"
    }
  }
}

Qwen Code (Local)

# Download model
ollama pull qwen2.5-coder:32b

# Configure Forge

{
  "llms": {
    "qwen": {
      "enabled": true,
      "model": "qwen2.5-coder:32b",
      "endpoint": "http://localhost:11434"
    }
  }
}

Configuration Best Practices

Start Simple

Begin with one agent (Claude or Gemini), add more later

Test Each Agent

Create a test task to verify configuration

Secure API Keys

Never commit .forge/config.json to version control

Monitor Usage

Track API costs per agent to optimize spending

Validation

Test your configuration:

# Start Forge
forge start

# Create test task
forge task create \
  --title "Test configuration" \
  --description "Print 'Hello from Forge!'" \
  --llm claude

# Should execute successfully

Troubleshooting

Invalid API key

Symptoms: Authentication errors when running tasksSolutions:

Verify API key is correct (no extra spaces)
Check API key has proper permissions
Ensure API key isn’t expired
Confirm you have credits/quota remaining

Model not found

Symptoms: “Model not available” errorsSolutions:

Check model name spelling (case-sensitive)
Verify model is available in your region
Ensure your API tier has access to the model

Timeout errors

Symptoms: Tasks fail with timeoutSolutions:

Increase timeout value in config
Check network connectivity
Try a faster model (e.g., Haiku, Flash)

Cursor CLI not authenticated

Symptoms: Cursor tasks fail immediatelySolutions:

# Re-authenticate
cursor auth logout
cursor auth login

Cost Optimization

Model Selection Strategy

Use Fast Models for Iteration

Start with fast, cheap models:

Claude Haiku
Gemini Flash
GPT-3.5 Turbo

Use Powerful Models for Complex Tasks

Switch to stronger models for:

Large refactoring
Architecture changes
Critical bug fixes

Compare Results

Run the same task with multiple models to find the sweet spot for each task type

Cost Comparison

Model	Input	Output	Sweet Spot
Claude Haiku	$0.25/MTok	$1.25/MTok	Quick iterations
Gemini Flash	Free tier	Free tier	Experimentation
GPT-3.5 Turbo	$0.50/MTok	$1.50/MTok	Simple tasks
Claude Sonnet	$3/MTok	$15/MTok	General work
GPT-4 Turbo	$10/MTok	$30/MTok	Complex tasks

Advanced: Multiple Configurations

Create environment-specific configs:

# Development
.forge/config.dev.json

# Production
.forge/config.prod.json

# CI/CD
.forge/config.ci.json

Switch between them:

FORGE_CONFIG=.forge/config.prod.json forge start

Next Steps

Create Your First Task

Put your configuration to work

AI Agents Guide

Deep dive into each agent’s capabilities

Environment Variables

Additional configuration options

Getting Started

Learn

Configuration

Reference

Troubleshooting

​Overview

​Supported AI Agents

​Configuration File

​Claude Code Setup

​Get Your API Key

​Available Models

​Advanced Configuration

​Claude Code Router Setup

​Configuration

​Supported Providers

​Gemini Setup

​Get Your API Key

​Available Models

​Cursor CLI Setup

​Installation

​Configuration

​OpenAI Codex Setup

​Get Your API Key

​Available Models

​Open Source Agents

​OpenCode (Local)

​Qwen Code (Local)

​Configuration Best Practices

Start Simple

Test Each Agent

Secure API Keys

Monitor Usage

​Validation

​Troubleshooting

​Cost Optimization

​Model Selection Strategy

​Cost Comparison

​Advanced: Multiple Configurations

​Next Steps

Create Your First Task

AI Agents Guide

Environment Variables

Overview

Supported AI Agents

Configuration File

Claude Code Setup

Get Your API Key

Available Models

Advanced Configuration

Claude Code Router Setup

Configuration

Supported Providers

Gemini Setup

Get Your API Key

Available Models

Cursor CLI Setup

Installation

Configuration

OpenAI Codex Setup

Get Your API Key

Available Models

Open Source Agents

OpenCode (Local)

Qwen Code (Local)

Configuration Best Practices

Validation

Troubleshooting

Cost Optimization

Model Selection Strategy

Cost Comparison

Advanced: Multiple Configurations

Next Steps