Reload servers and rebuild caches

forge mcp reload

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

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

Installation

```bash

Quickstart

To get started with Forge, run the command below:

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

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>

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>

---

Configure your provider credentials interactively

forge provider login

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 ```

Command-Line Options

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

Advanced Configuration

Provider Configuration

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

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

.env

OPENROUTER_API_KEY=<your_openrouter_api_key>

</details>

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

.env

REQUESTY_API_KEY=<your_requesty_api_key>

</details>

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

.env

XAI_API_KEY=<your_xai_api_key>

</details>

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

.env

ZAI_API_KEY=<your_zai_api_key>

.env

CEREBRAS_API_KEY=<your_cerebras_api_key>

</details>

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

.env

IO_INTELLIGENCE_API_KEY=<your_io_intelligence_api_key>

.env

OPENAI_API_KEY=<your_openai_api_key>

.env

ANTHROPIC_API_KEY=<your_anthropic_api_key>

.env

PROJECT_ID=<your_project_id> LOCATION=<your_location> VERTEX_AI_AUTH_TOKEN=<your_auth_token>

.env

OPENAI_API_KEY=<your_provider_api_key> OPENAI_URL=<your_provider_url>

.env

OPENAI_API_KEY=<your_groq_api_key> OPENAI_URL=https://api.groq.com/openai/v1

.env

OPENAI_API_KEY=<your_bedrock_gateway_api_key> OPENAI_URL=<your_bedrock_gateway_base_url>

.env

FORGE_API_KEY=<your_forge_api_key>

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:

.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:

.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:

.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:

.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:

.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):

.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:

.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:

.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:

.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.

MCP Configuration

Configure MCP servers using the CLI:

```bash

Show server configuration details

forge mcp show

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.

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.

Quick Reference: All `:` Commands

---

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.

: 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 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.

: <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

Git Integration

: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

Package managers

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

---