---
title: Forge AI
created: 2026-04-28
updated: 2026-04-28
type: concept
tags: [concept, ai, tools, cli]
sources: [../raw/articles/forge/]
confidence: high
---

# Forge AI

Forge AI (ForgeCode) is a CLI-based AI coding harness — a competitor to Claude Code with first-class support for many AI providers. It works with cloud models, open-weight models, and local models.

**Website:** https://forgecode.dev

## Agents

Forge provides three built-in agents:

| Agent | Access | Purpose |
|-------|--------|---------|
| **muse** | read + write | Planning and analysis — reviews impact, plans changes |
| **forge** | read + write | Implementation — makes changes, fixes bugs (default) |
| **sage** | read | Research — used internally by muse/forge for codebase understanding |

Typical workflow: use `muse` to plan, switch to `forge` to implement.

Switch agents with `:agent`, `:muse`, `:forge`.

## Custom Agents

Create agents as markdown files with YAML frontmatter in `.forge/agents/` (project) or `~/forge/agents/` (global).

```yaml
---
id: my-agent
title: My Agent
description: Brief description
tools: [read, search, shell]
model: claude-sonnet-4
provider: anthropic
temperature: 0.1
---
System prompt here.
```

Tools: read, write, patch, shell, search, fetch, remove, undo, or `"*"` for all.

## Custom Commands

Repeatable workflows as slash commands in `.forge/commands/`:

```markdown
---
name: check
description: Runs lint and tests before commit
---
Run `lint` and `test`, fix any issues found.
<lint>cargo clippy --fix</lint>
<test>cargo test</test>
```

Invoke with `:check` in the Forge chat.

## MCP Integration

Connect external tools via `.mcp.json`:

```json
{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}
```

Manage with `forge mcp import`, `forge mcp list`, `forge mcp remove`, `forge mcp reload`.

## Environment Variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `FORGE_TERM` | on | Terminal context capture — passes command history to the model |
| `FORGE_TERM_MAX_COMMANDS` | 5 | History buffer size |
| `FORGE_CONFIG` | `~/forge/` | Config directory (for dotfiles repos) |
| `FORGE_BIN` | `forge` | Binary path (for local builds or version switching) |

## $FORGE_TERM

On by default. The Zsh plugin tracks what commands you run, whether they succeeded, and passes that to ForgeCode on every `:` invocation. Means `forge fix it` already knows what failed — no need to narrate.

Disable per-session: `export FORGE_TERM=false`

## Forge Services

Optional backend for enhanced capabilities: context engine (semantic search), tool-call guardrails, and skill engine. Enable with `:login` → select ForgeServices.

Index project with `:sync`, check status with `:sync-status`.

## Setup

```bash
# 1. Install
curl -fsSL https://forgecode.dev/cli | sh

# 2. Zsh plugin
forge zsh setup

# 3. Login to provider
:login

# 4. Pick model
:model

# 5. First prompt
: Hi!
```

Requires: Nerd Font, Zsh.

## Skills

ForgeCode skills are markdown files (`.forge/skills/`) that provide reusable workflows. Similar to custom commands but more powerful — skills can use templating and conditional logic.

## Configuration Files

| File | Purpose |
|------|---------|
| `.forge.toml` | Main config ( ForgeConfig dir) |
| `.mcp.json` | MCP server definitions |
| `.forge/agents/` | Custom agent definitions |
| `.forge/commands/` | Custom slash commands |
| `.forge/skills/` | Reusable skill workflows |
| `AGENTS.md` | Project-wide rules for all agents |

## Related

- [[opencode-cluster]] — OpenCode cluster setup in this homelab
- [[ai-applications]] — AI application stack on ubuntu
- [[hermes-gateway]] — Hermes gateway used for model routing