AI Coding Agent Setup

Updated on Oct 2, 2026

Forge delegates workflow execution to an external AI coding agent. Forge composes the prompt, runs the agent CLI in headless mode, and captures its output. This page shows you how to install one supported agent, select it in .forge/config/agents.toml, and verify that Forge can use it.

Warning: Forge runs agents in autonomous mode. The agent can execute commands and modify files without asking for approval. Run Forge in a sandbox or development container, and review changes before you accept or push them.

Supported agents

Agent ID	Agent	Default command	Models
`claude_code`	Claude Code CLI	`claude`	Claude models
`github_copilot`	GitHub Copilot CLI	`copilot`	GitHub and BYOK models
`opencode`	OpenCode CLI	`opencode`	BYOK models

Use the exact agent ID in agents.toml and with --agent. Agent IDs are case-sensitive and use underscores.

Forge does not provide the agent, its subscription, or its credentials, and there is no separate Forge API key. Authentication goes through the agent.

Prerequisites

Forge is installed and frg is in your PATH. See Installation.
You have a valid Telerik license. See Licensing.
The agent CLI is installed and authenticated for the same user that runs Forge.
You run Forge in an isolated development environment.

Install an agent

Install only the agent your project uses. Follow the vendor's documentation for account and subscription requirements.

GitHub Copilot Claude Code OpenCode

Install the CLI with npm (requires Node.js 22 or later), WinGet on Windows, or Homebrew on macOS and Linux:

bash

npm install -g @github/copilot

powershell

winget install GitHub.Copilot

bash

brew install --cask copilot-cli

Verify the executable:

bash

copilot --version

Authenticate. Run copilot once and use the /login slash command. For non-interactive environments such as CI, set COPILOT_GITHUB_TOKEN (or GH_TOKEN / GITHUB_TOKEN) to a fine-grained personal access token with the Copilot Requests permission:

bash

export COPILOT_GITHUB_TOKEN="<fine-grained-token>"

Forge discovers copilot in PATH and handles npm wrapper scripts on Windows automatically. The GitHub CLI extension (gh copilot) is not supported. See Use a custom agent command.

Install the CLI with the native installer (recommended; it doesn't need Node.js):

bash

curl -fsSL https://claude.ai/install.sh | bash

powershell

irm https://claude.ai/install.ps1 | iex

Alternatives: brew install --cask claude-code, winget install Anthropic.ClaudeCode, or npm install -g @anthropic-ai/claude-code (requires Node.js 22 or later). Then verify the executable:

bash

claude --version

Authenticate Claude Code. For API-key authentication, set ANTHROPIC_API_KEY in the environment that runs Forge:

bash

export ANTHROPIC_API_KEY="your-anthropic-api-key"

powershell

$env:ANTHROPIC_API_KEY = "your-anthropic-api-key"

Do not commit the key or put it in a Forge configuration file.

Test a headless request:

bash

claude -p "hello"

Forge runs Claude Code with the agent's own --dangerously-skip-permissions flag, so the agent does not stop for tool-approval prompts. This is why you must run Forge in an isolated environment.

Install OpenCode with its official installer:

bash

curl -fsSL https://opencode.ai/install | sh
opencode --version

Complete OpenCode's provider authentication flow, then test a request:

bash

opencode run hello

Select the default agent

Generate agents.toml from the repository root:

bash

frg config init --agent claude_code

Replace claude_code with github_copilot or opencode as needed. With no --models option, Forge generates the stable model profile. For the other profiles and the models each one sets, see Model profiles.

If .forge/config/agents.toml already exists, Forge keeps it and prints Skipping agent configuration generation. Add --force to replace it.

The minimum manual configuration is:

toml

schema_version = "1.0.0"

[agent]
default = "claude_code"

schema_version and agent.default are required.

Warning: Forge does not reject an unknown default value. frg config validate reports the file as valid, and Forge falls back to GitHub Copilot. Check the spelling of the agent ID if frg status reports a different agent than you expect.

Forge can also load agents.toml from user or system locations. See Hierarchical Configuration.

Override the agent for one command

Every workflow command accepts -a, --agent <NAME>:

bash

frg code review --agent opencode

The configured default does not change.

Use a custom agent command

Forge runs the default command for each agent unless you set command in the agent's table:

toml

[agent.opencode]
command = "/opt/opencode/bin/opencode"

Use an executable name that is in PATH, or an absolute path. On Windows, escape backslashes or use forward slashes:

toml

[agent.github_copilot]
command = "C:/Program Files/GitHub Copilot CLI/copilot.exe"

Forge rejects these values during validation:

Value	Error
`command = ""`	`Empty command string for agent '<id>'. Remove the field or provide a valid command.`
A command with shell operators, such as `&&`	`Invalid command '<command>' for agent '<id>': contains shell operators`
`command = "gh"` for GitHub Copilot	`'command = "gh"' is not supported.` The `gh copilot` wrapper has Windows command-line length limitations that cause failures with complex prompts.

Agent settings reference

Put these optional settings in [agent.<agent_id>]:

Setting	Purpose	Details
`command`	Replaces the default executable name or path.	Use a custom agent command
`model`	Default model passed to the agent. `targets` and `operations` tables override it.	AI Model Selection
`prompt_format`	`xml`, `markdown`, or `md`. If you omit it, Forge picks the format from the model name.	Prompt Formats
`custom_agent`	Default custom agent (persona) inside the agent CLI. The `custom_agents` and `custom_agent_operations` tables override it.	Custom Agent Configurations

Verify the setup

Validate the agent configuration:

bash

frg config validate --file .forge/config/agents.toml

Validation reports errors, such as an invalid command, and non-blocking warnings, such as a model name that fails Forge's structural checks. The agent CLI determines whether a structurally valid model name is available.

Check agent installation and authentication:

bash

frg status --verbose

Example output (abbreviated):

text

ℹ Coding Agent: Claude Code CLI (installation check: 330.65ms)
Status: authenticated (auth check: 2.35ms)

The authentication check sends a short prompt through the agent CLI. If the status shows not installed or (not authenticated), see Agent Troubleshooting.

Run a low-risk workflow in an isolated checkout:

bash

frg code review

Run Forge in CI/CD

Forge asks for beta acknowledgement interactively. In a pipeline without a terminal, Forge stops with Beta acknowledgement is required to use Forge. unless you set FORGE_ACCEPT_BETA_RISK:

yaml

# GitHub Actions
jobs:
 review:
 runs-on: ubuntu-latest
 env:
 FORGE_ACCEPT_BETA_RISK: "1"
 steps:
 - uses: actions/checkout@v7
 - run: frg code review

Set the variable in the same job or stage that runs Forge, and make sure the agent is authenticated in that environment. For other variables that affect agents in CI, such as the retry settings, see Environment Variables.