README.md

---
license: apache-2.0
tags:
  - agent
  - coding-agent
  - cli
  - llm
  - tool-use
---

> **This is a source mirror.** This Hugging Face repository is not a model checkpoint — it's a read-only mirror of the [`tailcallhq/forgecode`](https://github.com/tailcallhq/forgecode) GitHub repository, Tailcall's terminal coding agent (a single musl binary). It is hosted here for visibility on the Hub; the canonical repository, issue tracker, and pull requests all live on GitHub. Please file issues and contribute there, not here.

<h1 align="center">⚒️ Forge: AI-Enhanced Terminal Development Environment</h1>
<p align="center">A comprehensive coding agent that integrates AI capabilities with your development environment</p>

<p align="center"><code>curl -fsSL https://forgecode.dev/cli | sh</code></p>

[![CI Status](https://img.shields.io/github/actions/workflow/status/tailcallhq/forgecode/ci.yml?style=for-the-badge)](https://github.com/tailcallhq/forgecode/actions)
[![GitHub Release](https://img.shields.io/github/v/release/tailcallhq/forgecode?style=for-the-badge)](https://github.com/tailcallhq/forgecode/releases)
[![Discord](https://img.shields.io/discord/1044859667798568962?style=for-the-badge&cacheSeconds=120&logo=discord)](https://discord.gg/kRZBPpkgwq)
[![CLA assistant](https://cla-assistant.io/readme/badge/tailcallhq/forgecode?style=for-the-badge)](https://cla-assistant.io/tailcallhq/forgecode)

![Code-Forge Demo](https://assets.antinomy.ai/images/forge_demo_2x.gif)

---

<details>
<summary><strong>Table&nbsp;of&nbsp;Contents</strong></summary>

- [Quickstart](#quickstart)
- [Usage Examples](#usage-examples)
- [Why Forge?](#why-forge)
- [How Forge Works: Three Modes](#how-forge-works-three-modes)
  - [Interactive Mode (TUI)](#interactive-mode-tui)
  - [One-Shot CLI Mode](#one-shot-cli-mode)
  - [ZSH Plugin Mode (`:` prefix)](#zsh-plugin-mode--prefix)
- [ZSH Plugin: The `:` Prefix System](#zsh-plugin-the--prefix-system)
  - [Agents](#agents)
  - [Sending Prompts](#sending-prompts)
  - [Attaching Files](#attaching-files)
  - [Conversation Management](#conversation-management)
  - [Git Integration](#git-integration)
  - [Shell Command Tools](#shell-command-tools)
  - [Session & Configuration](#session--configuration)
  - [Skills](#skills)
  - [Customizing Agent Behavior](#customizing-agent-behavior)
  - [Semantic Search (Workspace)](#semantic-search-workspace)
  - [Quick Reference: All `:` Commands](#quick-reference-all--commands)
- [Command-Line Options](#command-line-options)
- [Advanced Configuration](#advanced-configuration)
  - [Provider Configuration](#provider-configuration)
    - [Managing Provider Credentials](#managing-provider-credentials)
    - [Deprecated: Environment Variables](#deprecated-environment-variables)
  - [forge.yaml Configuration Options](#forgeyaml-configuration-options)
  - [Environment Variables](#environment-variables)
  - [MCP Configuration](#mcp-configuration)
  - [Example Use Cases](#example-use-cases)
  - [Usage in Multi-Agent Workflows](#usage-in-multi-agent-workflows)
- [Documentation](#documentation)
- [Community](#community)
- [Support Us](#support-us)

</details>

---

## Quickstart

To get started with Forge, run the command below:

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

On first run, Forge will guide you through setting up your AI provider credentials using the interactive login flow. Alternatively, you can configure providers beforehand:

```bash
# Configure your provider credentials interactively
forge provider login

# Then start Forge
forge
```
That's it! Forge is now ready to assist you with your development tasks.

## Usage Examples

Forge can be used in different ways depending on your needs. Here are some common usage patterns:

<details>
<summary><strong>Code Understanding</strong></summary>

```
> Can you explain how the authentication system works in this codebase?
```

Forge will analyze your project's structure, identify authentication-related files, and provide a detailed explanation of the authentication flow, including the relationships between different components.

</details>

<details>
<summary><strong>Implementing New Features</strong></summary>

```
> I need to add a dark mode toggle to our React application. How should I approach this?
```

Forge will suggest the best approach based on your current codebase, explain the steps needed, and even scaffold the necessary components and styles for you.

</details>

<details>
<summary><strong>Debugging Assistance</strong></summary>

```
> I'm getting this error: "TypeError: Cannot read property 'map' of undefined". What might be causing it?
```

Forge will analyze the error, suggest potential causes based on your code, and propose different solutions to fix the issue.

</details>

<details>
<summary><strong>Code Reviews</strong></summary>

```
> Please review the code in src/components/UserProfile.js and suggest improvements
```

Forge will analyze the code, identify potential issues, and suggest improvements for readability, performance, security, and maintainability.

</details>

<details>
<summary><strong>Learning New Technologies</strong></summary>

```
> I want to integrate GraphQL into this Express application. Can you explain how to get started?
```

Forge will provide a tailored tutorial on integrating GraphQL with Express, using your specific project structure as context.

</details>

<details>
<summary><strong>Database Schema Design</strong></summary>

```
> I need to design a database schema for a blog with users, posts, comments, and categories
```

Forge will suggest an appropriate schema design, including tables/collections, relationships, indexes, and constraints based on your project's existing database technology.

</details>

<details>
<summary><strong>Refactoring Legacy Code</strong></summary>

```
> Help me refactor this class-based component to use React Hooks
```

Forge can help modernize your codebase by walking you through refactoring steps and implementing them with your approval.

</details>

<details>
<summary><strong>Git Operations</strong></summary>

```
> I need to merge branch 'feature/user-profile' into main but there are conflicts
```

Forge can guide you through resolving git conflicts, explaining the differences and suggesting the best way to reconcile them.

</details>

## Why Forge?

Forge is designed for developers who want to enhance their workflow with AI assistance while maintaining full control over their development environment.

- **Zero configuration** - Just add your API key and you're ready to go
- **Seamless integration** - Works right in your terminal, where you already work
- **Multi-provider support** - Use OpenAI, Anthropic, or other LLM providers
- **Secure by design** - Restricted shell mode limits file system access and prevents unintended changes
- **Open-source** - Transparent, extensible, and community-driven

Forge helps you code faster, solve complex problems, and learn new technologies without leaving your terminal.

---

## How Forge Works: Three Modes

Forge has three distinct ways to use it. Understanding this distinction upfront will save you confusion.

### Interactive Mode (TUI)

Running `forge` with no arguments starts the interactive terminal UI, a persistent session where you type prompts and the AI responds in a conversational loop. This is the primary way to do multi-step work.

```bash
forge                              # Start a new interactive session
forge conversation resume <id>     # Resume a specific saved conversation in interactive mode
forge --conversation-id <id>       # Same: resume conversation by ID
forge --agent <agent-id>           # Start interactive session with a specific agent
forge -C /path/to/project          # Start in a specific directory
forge --sandbox experiment-name    # Create an isolated git worktree + branch, then start there
```

Once inside interactive mode, type your prompt and press Enter. Forge reads files, writes patches, runs commands, and maintains context across the whole session.

### One-Shot CLI Mode

Pass `-p` (or `--prompt`) to run a single prompt and exit. Forge does the work and returns to your shell. Useful for scripts, piping output, or quick tasks.

```bash
forge -p "Explain the purpose of src/main.rs"
forge -p "Add error handling to the parse() function in lib.rs"
echo "What does this do?" | forge    # Pipe input as the prompt
forge commit                         # Generate an AI commit message and commit (exits when done)
forge commit --preview               # Generate commit message, print it, then exit
forge suggest "find large log files" # Translate natural language to a shell command, then exit
```

> **Note:** `forge conversation resume <id>` opens the interactive TUI. It does **not** just print a message and exit. If you run it and see the cursor waiting, you are inside the interactive session. Type your prompt or press `Ctrl+C` to exit.

### ZSH Plugin Mode (`:` prefix)

Install the ZSH plugin once with `forge setup`, then use `:` commands directly at your shell prompt without ever typing `forge`. This is the fastest mode for day-to-day development: send prompts, switch conversations, commit, and suggest commands without leaving your shell.

```zsh
: refactor the auth module      # Send a prompt to the active agent
:commit                         # AI-powered git commit
:suggest "find large log files" # Translate description → shell command in your buffer
:conversation                   # Browse saved conversations with interactive picker
```

See the full [ZSH Plugin reference below](#zsh-plugin-the--prefix-system) for all commands and aliases.

---

## ZSH Plugin: The `:` Prefix System

When you install the ZSH plugin (`forge setup`), you get a `:` prefix command system at your shell prompt. This is the fastest way to use Forge during normal development; you never leave your shell.

**How it works:** Lines starting with `:` are intercepted before the shell sees them and routed to Forge. Everything else runs normally.

```zsh
: <prompt>         # Send a prompt to the active agent
:sage <prompt>     # Send a prompt to a specific agent by name (sage, muse, forge, or any custom agent)
:agent <name>      # Switch the active agent; opens interactive picker if no name given
```

### Agents

Forge ships with three built-in agents, each with a different role:

| Agent | Alias | Purpose | Modifies files? |
|---|---|---|---|
| `forge` | (default) | Implementation: builds features, fixes bugs, and runs tests | Yes |
| `sage` | `:ask` | Research: maps architecture, traces data flow, and reads code | No |
| `muse` | `:plan` | Planning: analyzes structure and writes implementation plans to `plans/` | No |

### Sending Prompts

```zsh
: refactor the auth module to use the new middleware
:sage how does the caching layer work?    # sage = read-only research agent
:muse design a deployment strategy        # muse = planning agent (writes to plans/)
:ask how does X work?                     # alias for :sage
:plan create a migration plan             # alias for :muse
```

The agent context persists. Typing `:sage` alone (no prompt text) switches the active agent to sage for all subsequent `: <prompt>` commands.

### Attaching Files

Type `@` in a prompt, then press Tab to fuzzy-search and select files. The path is inserted as `@[filename]` and attached as context to the AI.

```zsh
: review this code @[src/auth.rs] @[tests/auth_test.rs]
```

### Conversation Management

Forge saves every conversation. You can switch between them like switching directories.

```zsh
:new                      # Start a fresh conversation (saves current for :conversation -)
:new <initial prompt>     # Start a new conversation and immediately send a prompt
:conversation             # Open interactive picker: browse and switch conversations with preview
:conversation <id>        # Switch directly to a conversation by ID
:conversation -           # Toggle between current and previous conversation (like cd -)
:clone                    # Branch the current conversation (try a different direction)
:clone <id>               # Clone a specific conversation by ID
:rename <name>            # Rename the current conversation
:conversation-rename      # Rename a conversation via interactive picker
:retry                    # Retry the last prompt (useful if the AI misunderstood)
:copy                     # Copy the last AI response to clipboard as markdown
:dump                     # Export conversation as JSON
:dump html                # Export conversation as formatted HTML
:compact                  # Manually compact context to free up token budget
```

### Git Integration

```zsh
:commit                   # AI reads your diff, writes a commit message, and commits immediately
:commit <context>         # Same, but pass extra context: :commit fix typo in readme
:commit-preview           # AI generates the message and puts "git commit -m '...'" in your buffer
                          # so you can review/edit the message before pressing Enter
```

### Shell Command Tools

```zsh
:suggest <description>    # Translate natural language to a shell command and put it in your buffer
:edit                     # Open $EDITOR to compose a complex multi-line prompt, then send it
```

### Session & Configuration

Some commands change settings for the current session only. Others persist to your config file (`~/forge/.forge.toml`). The distinction matters:

```zsh
# Session-only (reset when you close the terminal; not saved to config)
:model <model-id>              # Change model for this session only
:reasoning-effort <level>      # Set reasoning effort: none/minimal/low/medium/high/xhigh/max
:agent <id>                    # Switch active agent for this session

# Persistent (saved to config file)
:config-model <model-id>       # Set default model globally  (alias: :cm)
:config-provider               # Switch provider globally    (alias: :provider, :p)
:config-reasoning-effort <lvl> # Set default reasoning effort globally (alias: :cre)
:config-commit-model <id>      # Set model used for :commit  (alias: :ccm)
:config-suggest-model <id>     # Set model used for :suggest (alias: :csm)
:config-reload                 # Reset session overrides back to global config (alias: :cr)

# View & edit config
:info                          # Show current session info (model, agent, conversation ID)
:config                        # Display effective resolved configuration in TOML format
:config-edit                   # Open config file in $EDITOR (alias: :ce)
:tools                         # List available tools for the current agent
:skill                         # List available skills
```

### Skills

Skills are reusable workflows the AI can invoke as tools. Forge ships three built-in skills:

- **`create-skill`**: scaffold a new custom skill
- **`execute-plan`**: execute a plan file from `plans/`
- **`github-pr-description`**: generate a PR description from your diff

Use `:skill` to list available skills. The AI invokes them automatically when relevant, or you can ask explicitly: `: generate a PR description using the github-pr-description skill`.

**Custom skills** live in `SKILL.md` files with YAML front-matter. Precedence (highest first):

| Location | Path | Scope |
|---|---|---|
| Project-local | `.forge/skills/<name>/SKILL.md` | This project only |
| Global | `~/forge/skills/<name>/SKILL.md` | All projects |
| Built-in | Embedded in binary | Always available |

Project-local skills override global ones, which override built-in ones. To scaffold a new skill, ask: `: create a new skill`.

### Customizing Agent Behavior

**`AGENTS.md`:** Create this file in your project root (or `~/forge/AGENTS.md` globally) to give all agents persistent instructions such as coding conventions, commit message style, and things to avoid. Forge reads it automatically at the start of every conversation.

**Custom agents:** Place a `.md` file with YAML front-matter in `.forge/agents/` (project) or `~/forge/agents/` (global) to define additional agents with their own models, tools, and system prompts. Project-local agents override global ones. The built-in agent files in `crates/forge_repo/src/agents/` are good examples of the format.

**Custom commands:** Place YAML files in `.forge/commands/` (project) or `~/forge/commands/` (global) to define shortcut commands available via `:commandname`. Commands can also be defined inline in `forge.yaml` under the `commands:` key.

### Semantic Search (Workspace)

```zsh
:sync                     # Index your codebase for semantic search
:workspace-init           # Initialize workspace for indexing
:workspace-status         # Show indexing status
:workspace-info           # Show workspace details
```

After running `:sync`, the AI can search your codebase by meaning rather than exact text matches. Indexing sends file content to the workspace server, which defaults to `https://api.forgecode.dev`. Set `FORGE_WORKSPACE_SERVER_URL` to override this if self-hosting.

### Quick Reference: All `:` Commands


| Command | Alias | What it does |
|---|---|---|
| `: <prompt>` | | Send prompt to active agent |
| `:new` | `:n` | Start new conversation |
| `:conversation` | `:c` | Browse/switch conversations (interactive picker) |
| `:conversation -` | | Toggle to previous conversation |
| `:clone` | | Branch current conversation |
| `:rename <name>` | `:rn` | Rename current conversation |
| `:conversation-rename` | | Rename conversation (interactive picker) |
| `:retry` | `:r` | Retry last prompt |
| `:copy` | | Copy last response to clipboard |
| `:dump` | `:d` | Export conversation as JSON |
| `:compact` | | Compact context |
| `:commit` | | AI commit (immediate) |
| `:commit-preview` | | AI commit (review first) |
| `:suggest <desc>` | `:s` | Translate natural language to command |
| `:edit` | `:ed` | Compose prompt in $EDITOR |
| `:sage <prompt>` | `:ask` | Q&A / code understanding agent |
| `:muse <prompt>` | `:plan` | Planning agent |
| `:agent <name>` | `:a` | Switch active agent (interactive picker if no name given) |
| `:model <id>` | `:m` | Set model for this session only |
| `:config-model <id>` | `:cm` | Set default model (persistent) |
| `:reasoning-effort <lvl>` | `:re` | Set reasoning effort for session |
| `:config-reload` | `:cr` | Reset session overrides to global config |
| `:info` | `:i` | Show session info |
| `:sync` | `:workspace-sync` | Index codebase for semantic search |
| `:tools` | `:t` | List available tools |
| `:skill` | | List available skills |
| `:login` | `:provider-login` | Login to a provider |
| `:logout` | | Logout from a provider |
| `:keyboard-shortcuts` | `:kb` | Show keyboard shortcuts |
| `:doctor` | | Run shell environment diagnostics |

---

## Command-Line Options

Here's a quick reference of Forge's command-line options:

| Option                              | Description                                                              |
| ----------------------------------- | ------------------------------------------------------------------------ |
| `-p, --prompt <PROMPT>`             | Direct prompt to process without entering interactive mode               |
| `-e, --event <EVENT>`               | Dispatch an event to the workflow in JSON format                         |
| `--conversation <CONVERSATION>`     | Path to a JSON file containing the conversation to execute               |
| `--conversation-id <ID>`            | Resume or continue an existing conversation by ID                        |
| `--agent <AGENT>`                   | Agent ID to use for this session                                         |
| `-C, --directory <DIR>`             | Change to this directory before starting                                 |
| `--sandbox <NAME>`                  | Create an isolated git worktree + branch for safe experimentation        |
| `--verbose`                         | Enable verbose logging output                                            |
| `-h, --help`                        | Print help information                                                   |
| `-V, --version`                     | Print version                                                            |

### Subcommands

```bash
# Conversations
forge conversation list                  # List all saved conversations
forge conversation resume <id>           # Resume a conversation in interactive mode
forge conversation new                   # Create a new conversation ID (prints it)
forge conversation dump <id>             # Export conversation as JSON
forge conversation compact <id>          # Compact conversation context
forge conversation retry <id>            # Retry last message
forge conversation clone <id>            # Clone a conversation
forge conversation rename <id> <name>    # Rename a conversation
forge conversation delete <id>           # Delete a conversation permanently
forge conversation info <id>             # Show conversation details
forge conversation stats <id>            # Show token usage statistics
forge conversation show <id>             # Show last assistant message

# Commits
forge commit                             # Generate AI commit message and commit
forge commit --preview                   # Generate commit message only (prints it)
forge commit fix the auth bug            # Pass extra context for the commit message

# Shell command suggestion
forge suggest "list files by size"       # Translate description to a shell command

# Providers
forge provider login                     # Add or update provider credentials (interactive)
forge provider logout                    # Remove provider credentials
forge list provider                      # List supported providers

# Models & agents
forge list model                         # List available models
forge list agent                         # List available agents

# Workspace / semantic search
forge workspace sync                     # Index current directory for semantic search
forge workspace init                     # Initialize workspace
forge workspace status                   # Show indexing status
forge workspace query <text>             # Query the semantic index

# MCP servers
forge mcp list                           # List configured MCP servers
forge mcp import                         # Add a server from JSON
forge mcp show                           # Show server configuration
forge mcp remove                         # Remove a server
forge mcp reload                         # Reload all servers and rebuild caches

# Other
forge info                               # Show config, active model, environment
forge list tool --agent <id>             # List tools for a specific agent
forge doctor                             # Run shell environment diagnostics
forge update                             # Update forge to the latest version
forge setup                              # Install ZSH plugin (updates .zshrc)
```

## Advanced Configuration

### Provider Configuration

Forge supports multiple AI providers. The recommended way to configure providers is using the interactive login command:

```bash
forge provider login
```

This will:

1. Show you a list of available providers
2. Guide you through entering the required credentials

#### Managing Provider Credentials

```bash
# Login to a provider (add or update credentials)
forge provider login

# Remove provider credentials
forge provider logout

# List supported providers
forge provider list
```

#### Deprecated: Environment Variables

> **⚠️ DEPRECATED**: Using `.env` files for provider configuration is deprecated and will be removed in a future version. Please use `forge provider login` instead.

For backward compatibility, Forge still supports environment variables. On first run, any credentials found in environment variables will be automatically migrated to file-based storage.

<details>
<summary><strong>Legacy Environment Variable Setup (Deprecated)</strong></summary>

<details>
<summary><strong>OpenRouter</strong></summary>

```bash
# .env
OPENROUTER_API_KEY=<your_openrouter_api_key>
```

</details>

<details>
<summary><strong>Requesty</strong></summary>

```bash
# .env
REQUESTY_API_KEY=<your_requesty_api_key>
```

</details>

<details>
<summary><strong>x-ai</strong></summary>

```bash
# .env
XAI_API_KEY=<your_xai_api_key>
```

</details>

<details>
<summary><strong>z.ai</strong></summary>

```bash
# .env
ZAI_API_KEY=<your_zai_api_key>

# Or for coding plan subscription
ZAI_CODING_API_KEY=<your_zai_coding_api_key>
```

</details>

<details>
<summary><strong>Cerebras</strong></summary>

```bash
# .env
CEREBRAS_API_KEY=<your_cerebras_api_key>
```

</details>

<details>
<summary><strong>Neuralwatt</strong></summary>

```bash
# .env
NEURALWATT_API_KEY=<your_neuralwatt_api_key>
```

</details>

<details>
<summary><strong>OrcaRouter</strong></summary>

```bash
# .env
ORCAROUTER_API_KEY=<your_orcarouter_api_key>
```

</details>

<details>
<summary><strong>Meta</strong></summary>

```bash
# .env
META_API_KEY=<your_meta_model_api_key>
```

```yaml
# forge.yaml
model: muse-spark-1.1
```

</details>

<details>
<summary><strong>IO Intelligence</strong></summary>

```bash
# .env
IO_INTELLIGENCE_API_KEY=<your_io_intelligence_api_key>
```

```yaml
# forge.yaml
model: meta-llama/Llama-3.3-70B-Instruct
```

</details>

<details>
<summary><strong>OpenAI</strong></summary>

```bash
# .env
OPENAI_API_KEY=<your_openai_api_key>
```

```yaml
# forge.yaml
model: o3-mini-high
```

</details>

<details>
<summary><strong>Anthropic</strong></summary>

```bash
# .env
ANTHROPIC_API_KEY=<your_anthropic_api_key>
```

```yaml
# forge.yaml
model: claude-3.7-sonnet
```

</details>

<details>
<summary><strong>Google Vertex AI</strong></summary>

**Setup Instructions:**

1. **Install Google Cloud CLI** and authenticate:

   ```bash
   gcloud auth login
   gcloud config set project YOUR_PROJECT_ID
   ```

2. **Get your authentication token**:

   ```bash
   gcloud auth print-access-token
   ```

3. **Use the token when logging in via Forge**:

   ```bash
   forge provider login
   # Select Google Vertex AI and enter your credentials
   ```

**Legacy `.env` setup:**

```bash
# .env
PROJECT_ID=<your_project_id>
LOCATION=<your_location>
VERTEX_AI_AUTH_TOKEN=<your_auth_token>
```

```yaml
# forge.yaml
model: google/gemini-2.5-pro
```

**Available Models:**
- Claude models: `claude-sonnet-4@20250514`
- Gemini models: `gemini-2.5-pro`, `gemini-2.0-flash`

Use the `/model` command in Forge CLI to see all available models.

</details>

<details>
<summary><strong>OpenAI-Compatible Providers</strong></summary>

```bash
# .env
OPENAI_API_KEY=<your_provider_api_key>
OPENAI_URL=<your_provider_url>
```

```yaml
# forge.yaml
model: <provider-specific-model>
```

</details>

<details>
<summary><strong>Groq</strong></summary>

```bash
# .env
OPENAI_API_KEY=<your_groq_api_key>
OPENAI_URL=https://api.groq.com/openai/v1
```

```yaml
# forge.yaml
model: deepseek-r1-distill-llama-70b
```

</details>

<details>
<summary><strong>Amazon Bedrock</strong></summary>

To use Amazon Bedrock models with Forge, you'll need to first set up the [Bedrock Access Gateway](https://github.com/aws-samples/bedrock-access-gateway):

1. **Set up Bedrock Access Gateway**:

   - Follow the deployment steps in the [Bedrock Access Gateway repo](https://github.com/aws-samples/bedrock-access-gateway)
   - Create your own API key in Secrets Manager
   - Deploy the CloudFormation stack
   - Note your API Base URL from the CloudFormation outputs

2. **Configure in Forge**:

   ```bash
   forge provider login
   # Select OpenAI-compatible provider and enter your Bedrock Gateway details
   ```

**Legacy `.env` setup:**

```bash
# .env
OPENAI_API_KEY=<your_bedrock_gateway_api_key>
OPENAI_URL=<your_bedrock_gateway_base_url>
```

```yaml
# forge.yaml
model: anthropic.claude-3-opus
```

</details>

<details>
<summary><strong>ForgeCode Services</strong></summary>

```bash
# .env
FORGE_API_KEY=<your_forge_api_key>
```

```yaml
# forge.yaml
model: claude-3.7-sonnet
```

</details>

</details>

---

### forge.yaml Configuration Options

### Environment Variables

Forge supports several environment variables for advanced configuration and fine-tuning. These can be set in your `.env` file or system environment.

<details>
<summary><strong>Retry Configuration</strong></summary>

Control how Forge handles retry logic for failed requests:

```bash
# .env
FORGE_RETRY_INITIAL_BACKOFF_MS=1000    # Initial backoff time in milliseconds (default: 1000)
FORGE_RETRY_BACKOFF_FACTOR=2           # Multiplier for backoff time (default: 2)
FORGE_RETRY_MAX_ATTEMPTS=3             # Maximum retry attempts (default: 3)
FORGE_SUPPRESS_RETRY_ERRORS=false      # Suppress retry error messages (default: false)
FORGE_RETRY_STATUS_CODES=429,500,502   # HTTP status codes to retry (default: 429,500,502,503,504)
```

</details>

<details>
<summary><strong>HTTP Configuration</strong></summary>

Fine-tune HTTP client behavior for API requests:

```bash
# .env
FORGE_HTTP_CONNECT_TIMEOUT=30              # Connection timeout in seconds (default: 30)
FORGE_HTTP_READ_TIMEOUT=900                # Read timeout in seconds (default: 900)
FORGE_HTTP_POOL_IDLE_TIMEOUT=90            # Pool idle timeout in seconds (default: 90)
FORGE_HTTP_POOL_MAX_IDLE_PER_HOST=5        # Max idle connections per host (default: 5)
FORGE_HTTP_MAX_REDIRECTS=10                # Maximum redirects to follow (default: 10)
FORGE_HTTP_USE_HICKORY=false               # Use Hickory DNS resolver (default: false)
FORGE_HTTP_TLS_BACKEND=default             # TLS backend: "default" or "rustls" (default: "default")
FORGE_HTTP_MIN_TLS_VERSION=1.2             # Minimum TLS version: "1.0", "1.1", "1.2", "1.3"
FORGE_HTTP_MAX_TLS_VERSION=1.3             # Maximum TLS version: "1.0", "1.1", "1.2", "1.3"
FORGE_HTTP_ADAPTIVE_WINDOW=true            # Enable HTTP/2 adaptive window (default: true)
FORGE_HTTP_KEEP_ALIVE_INTERVAL=60          # Keep-alive interval in seconds (default: 60, use "none"/"disabled" to disable)
FORGE_HTTP_KEEP_ALIVE_TIMEOUT=10           # Keep-alive timeout in seconds (default: 10)
FORGE_HTTP_KEEP_ALIVE_WHILE_IDLE=true      # Keep-alive while idle (default: true)
FORGE_HTTP_ACCEPT_INVALID_CERTS=false      # Accept invalid certificates (default: false) - USE WITH CAUTION
FORGE_HTTP_ROOT_CERT_PATHS=/path/to/cert1.pem,/path/to/cert2.crt  # Paths to root certificate files (PEM, CRT, CER format), multiple paths separated by commas
```

> **⚠️ Security Warning**: Setting `FORGE_HTTP_ACCEPT_INVALID_CERTS=true` disables SSL/TLS certificate verification, which can expose you to man-in-the-middle attacks. Only use this in development environments or when you fully trust the network and endpoints.

</details>

<details>
<summary><strong>API Configuration</strong></summary>

Override default API endpoints and provider/model settings:

```bash
# .env
FORGE_API_URL=https://api.forgecode.dev  # Custom Forge API URL (default: https://api.forgecode.dev)
FORGE_WORKSPACE_SERVER_URL=http://localhost:8080  # URL for the indexing server (default: https://api.forgecode.dev/)
```

</details>

<details>
<summary><strong>Tool Configuration</strong></summary>

Configuring the tool calls settings:

```bash
# .env
FORGE_TOOL_TIMEOUT=300         # Maximum execution time in seconds for a tool before it is terminated to prevent hanging the session. (default: 300)
FORGE_MAX_IMAGE_SIZE=10485760  # Maximum image file size in bytes for read_image operations (default: 10485760 - 10 MB)
FORGE_DUMP_AUTO_OPEN=false     # Automatically open dump files in browser (default: false)
FORGE_DEBUG_REQUESTS=/path/to/debug/requests.json  # Write debug HTTP request files to specified path (supports absolute and relative paths)
```

</details>

<details>
<summary><strong>ZSH Plugin Configuration</strong></summary>

Configure the ZSH plugin behavior:

```bash
# .env
FORGE_BIN=forge                    # Command to use for forge operations (default: "forge")
```

The `FORGE_BIN` environment variable allows you to customize the command used by the ZSH plugin when transforming `:` prefixed commands. If not set, it defaults to `"forge"`.

</details>

<details>
<summary><strong>Display Configuration</strong></summary>

Configure display options for the Forge UI and ZSH theme:

```bash
# .env
FORGE_CURRENCY_SYMBOL="$"         # Currency symbol for cost display in ZSH theme (default: "$")
FORGE_CURRENCY_CONVERSION_RATE=1.0  # Conversion rate for currency display (default: 1.0)
NERD_FONT=1                       # Enable Nerd Font icons in ZSH theme (default: auto-detected, set to "1" or "true" to enable, "0" or "false" to disable)
USE_NERD_FONT=1                   # Alternative variable for enabling Nerd Font icons (same behavior as NERD_FONT)
```

The `FORGE_CURRENCY_SYMBOL` and `FORGE_CURRENCY_CONVERSION_RATE` variables control how costs are displayed in the ZSH theme right prompt. Use these to customize the currency display for your region or preferred currency.

</details>

<details>
<summary><strong>System Configuration</strong></summary>

System-level environment variables (usually set automatically):

```bash
# .env
FORGE_CONFIG=/custom/config/dir        # Base directory for all Forge config files (default: ~/.forge)
FORGE_MAX_SEARCH_RESULT_BYTES=10240   # Maximum bytes for search results (default: 10240 - 10 KB)
FORGE_HISTORY_FILE=/path/to/history    # Custom path for Forge history file (default: uses system default location)
FORGE_BANNER="Your custom banner text" # Custom banner text to display on startup (default: Forge ASCII art)
FORGE_MAX_CONVERSATIONS=100            # Maximum number of conversations to show in list (default: 100)
FORGE_MAX_LINE_LENGTH=2000             # Maximum characters per line for file read operations (default: 2000)
FORGE_STDOUT_MAX_LINE_LENGTH=2000      # Maximum characters per line for shell output (default: 2000)
SHELL=/bin/zsh                         # Shell to use for command execution (Unix/Linux/macOS)
COMSPEC=cmd.exe                        # Command processor to use (Windows)
```

</details>

<details>
<summary><strong>Semantic Search Configuration</strong></summary>

Configure semantic search behavior for code understanding:

```bash
# .env
FORGE_SEM_SEARCH_LIMIT=200            # Maximum number of results to return from initial vector search (default: 200)
FORGE_SEM_SEARCH_TOP_K=20             # Top-k parameter for relevance filtering during semantic search (default: 20)
```

</details>

<details>
<summary><strong>Logging Configuration</strong></summary>

Configure logging verbosity and output:

```bash
# .env
FORGE_LOG=forge=info                  # Log filter level (default: forge=debug when tracking disabled, forge=info when tracking enabled)
```

The `FORGE_LOG` variable controls the logging level for Forge's internal operations using the standard tracing filter syntax. Common values:
- `forge=error` - Only errors
- `forge=warn` - Warnings and errors
- `forge=info` - Informational messages (default when tracking enabled)
- `forge=debug` - Debug information (default when tracking disabled)
- `forge=trace` - Detailed tracing

</details>

<details>
<summary><strong>Tracking Configuration</strong></summary>

Control tracking of user-identifying metadata in telemetry events:

```bash
# .env
FORGE_TRACKER=false                   # Disable tracking enrichment metadata (default: true)
```

The `FORGE_TRACKER` variable controls whether tracking enrichment metadata is included in telemetry events.

</details>

The `forge.yaml` file supports several advanced configuration options that let you customize Forge's behavior.

<details>
<summary><strong>Custom Rules</strong></summary>

Add your own guidelines that all agents should follow when generating responses.

```yaml
# forge.yaml
custom_rules: |
  1. Always add comprehensive error handling to any code you write.
  2. Include unit tests for all new functions.
  3. Follow our team's naming convention: camelCase for variables, PascalCase for classes.
```

</details>

<details>
<summary><strong>Commands</strong></summary>

Define custom commands as shortcuts for repetitive prompts:

```yaml
# forge.yaml
commands:
  - name: "refactor"
    description: "Refactor selected code"
    prompt: "Please refactor this code to improve readability and performance"
```

</details>

<details>
<summary><strong>Model</strong></summary>

Specify the default AI model to use for all agents in the workflow.

```yaml
# forge.yaml
model: "claude-3.7-sonnet"
```

</details>

<details>
<summary><strong>Max Walker Depth</strong></summary>

Control how deeply Forge traverses your project directory structure when gathering context.

```yaml
# forge.yaml
max_walker_depth: 3 # Limit directory traversal to 3 levels deep
```

</details>

<details>
<summary><strong>Temperature</strong></summary>

Adjust the creativity and randomness in AI responses. Lower values (0.0-0.3) produce more focused, deterministic outputs, while higher values (0.7-2.0) generate more diverse and creative results.

```yaml
# forge.yaml
temperature: 0.7 # Balanced creativity and focus
```

</details>
<details>
<summary><strong>Tool Max Failure Limit</strong></summary>

Control how many times a tool can fail before Forge forces completion to prevent infinite retry loops. This helps avoid situations where an agent gets stuck repeatedly trying the same failing operation.

```yaml
# forge.yaml
max_tool_failure_per_turn: 3 # Allow up to 3 failures per tool before forcing completion
```

Set to a higher value if you want more retry attempts, or lower if you want faster failure detection.

</details>

<details>
<summary><strong>Max Requests Per Turn</strong></summary>

Limit the maximum number of requests an agent can make in a single conversation turn. This prevents runaway conversations and helps control API usage and costs.

```yaml
# forge.yaml
max_requests_per_turn: 50 # Allow up to 50 requests per turn
```

When this limit is reached, Forge will:

- Ask you if you wish to continue
- If you respond with 'Yes', it will continue the conversation
- If you respond with 'No', it will end the conversation

</details>

---

<details>
<summary><strong>Model Context Protocol (MCP)</strong></summary>

The MCP feature allows AI agents to communicate with external tools and services. This implementation follows Anthropic's [Model Context Protocol](https://docs.anthropic.com/en/docs/claude-code/tutorials#set-up-model-context-protocol-mcp) design.

### MCP Configuration

Configure MCP servers using the CLI:

```bash
# List all MCP servers
forge mcp list

# Import a server from JSON
forge mcp import

# Show server configuration details
forge mcp show

# Remove a server
forge mcp remove

# Reload servers and rebuild caches
forge mcp reload
```

Or manually create a `.mcp.json` file with the following structure:

```json
{
  "mcpServers": {
    "server_name": {
      "command": "command_to_execute",
      "args": ["arg1", "arg2"],
      "env": { "ENV_VAR": "value" }
    },
    "another_server": {
      "url": "http://localhost:3000/events"
    }
  }
}
```

MCP configurations are read from two locations (project-local takes precedence):

1. **Project-local:** `.mcp.json` in your project directory
2. **Global:** `~/forge/.mcp.json`

### Example Use Cases

MCP can be used for various integrations:

- Web browser automation
- External API interactions
- Tool integration
- Custom service connections

### Usage in Multi-Agent Workflows

MCP tools can be used as part of multi-agent workflows, allowing specialized agents to interact with external systems as part of a collaborative problem-solving approach.

</details>

---

## Documentation

For comprehensive documentation on all features and capabilities, please visit the [documentation site](https://github.com/tailcallhq/forgecode/tree/main/docs).

---

## Installation

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

# Package managers
nix run github:tailcallhq/forgecode # for latest dev branch
```

---

## Community

Join our vibrant Discord community to connect with other Forge users and contributors, get help with your projects, share ideas, and provide feedback!

[![Discord](https://img.shields.io/discord/1044859667798568962?style=for-the-badge&cacheSeconds=120&logo=discord)](https://discord.gg/kRZBPpkgwq)

---

## Support Us

Your support drives Forge's continued evolution! By starring our GitHub repository, you:

- Help others discover this powerful tool 🔍
- Motivate our development team 💪
- Enable us to prioritize new features 🛠️
- Strengthen our open-source community 🌱