Forge Code

https://forgecode.dev/docs
Admin
Forge Code is an AI software engineering agent that runs in your terminal, understanding your...
Tokens:21,093
Snippets:341
Trust Score:7.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Quick start MCP import and list

Source: https://forgecode.dev/docs/mcp-integration

Initializes an MCP server configuration and verifies the installation.

```bash
forge mcp import '{  
  "mcpServers": {  
    "playwright": {  
      "command": "npx",  
      "args": ["@playwright/mcp@latest"]  
    }  
  }  
}'  
  
forge mcp list  
```

--------------------------------

### Configure Zsh plugin

Source: https://forgecode.dev/docs

Launches the interactive setup wizard for Zsh integration.

```bash
forge zsh setup
```

--------------------------------

### Verify ForgeCode installation

Source: https://forgecode.dev/docs

Displays the help menu to confirm the binary is correctly installed and accessible.

```bash
forge --help
```

--------------------------------

### Basic Prompt Examples

Source: https://forgecode.dev/docs/zsh-support

Standard prompts sent to the currently active agent.

```zsh
: explain this error message  
: refactor this function to be more readable  
: add error handling to the database connection  
```

--------------------------------

### Basic Project Guidelines Setup

Source: https://forgecode.dev/docs/custom-rules-guide

Define core team standards in the project root using markdown.

```markdown
# Development Guidelines  
  
## Core Standards  
  
- Use TypeScript strict mode  
- Add error handling to all functions  
- Include unit tests for new code  
- Use meaningful variable names  
```

--------------------------------

### Install ForgeCode binary

Source: https://forgecode.dev/docs

Executes the installation script for macOS, Linux, Android, and Windows (WSL/Git Bash).

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

--------------------------------

### Typical MCP import output

Source: https://forgecode.dev/docs/mcp-integration

Example output confirming successful addition of MCP servers.

```text
⏺ Added MCP server 'context7'  
⏺ Added MCP server 'deepwiki'  
⏺ Added MCP server 'playwright'  
```

--------------------------------

### Example prompt output for task

Source: https://forgecode.dev/docs/creating-agents

The resulting message format for an initial task input.

```xml
<task>fix the bug</task>  
<system_date>2026-04-01</system_date>
```

--------------------------------

### Example SKILL.md Content

Source: https://forgecode.dev/docs/skills

A sample markdown file defining a release notes generation workflow.

```markdown
# Generate Release Notes  
  
1. Run `./scripts/get-commits.sh` to collect commits since the last tag  
2. Run `./scripts/categorize.sh` to group them into Features, Bug Fixes, and Breaking Changes  
3. Write the release notes in `CHANGELOG.md` using the output from the scripts  
4. Run `./scripts/validate-changelog.sh` to confirm the format is correct  
```

--------------------------------

### Example prompt output for feedback

Source: https://forgecode.dev/docs/creating-agents

The resulting message format for a follow-up feedback input.

```xml
<feedback>looks good, but also handle the edge case</feedback>  
<system_date>2026-04-01</system_date>
```

--------------------------------

### Run ZSH diagnostic and setup commands

Source: https://forgecode.dev/docs/zsh-support

Use these commands to verify the environment and re-initialize ZSH integration.

```bash
forge zsh doctor # checks your environment and reports problems  
forge zsh setup  # re-runs the ZSH integration setup  
```

--------------------------------

### Minimal Command Example

Source: https://forgecode.dev/docs/commands

A simple command file that provides instructions without specific shell tags.

```markdown
---
name: fixme
description: Looks for all the fixme comments in the code and attempts to fix them
---

Find all the FIXME comments in source-code files and attempt to fix them.
```

--------------------------------

### Complete AGENTS.md Example

Source: https://forgecode.dev/docs/custom-rules

A comprehensive template for defining development rules, project structure, and restrictions in a full-stack application.

```markdown
# Development Guidelines for MyApp  
  
## 📋 Core Development Rules  
  
### Application Runtime  
  
- **NEVER** attempt to run the application - it's already running on port 3000 in watch mode  
- The development server is persistent and handles hot reloading automatically  
- Always assume the application is accessible at `http://localhost:3000`  
  
### Package Management  
  
- **Use**: `npm` or `npx` commands exclusively  
- **Avoid**: `yarn` or `pnpm` - not used in this project  
- Always check `package.json` for available scripts before running commands  
  
### Code Quality Standards  
  
- **TypeScript First**: All code must be type-safe with proper type definitions  
- **Component Architecture**: Follow React functional components with hooks  
- **Responsive Design**: Ensure all UI components work across devices  
- **Error Handling**: Always wrap async operations in try-catch blocks  
  
## 🛠️ Project Structure  
  
```  
├── src/  
│   ├── components/      # Reusable React components  
│   ├── pages/           # Next.js pages  
│   ├── services/        # API calls and business logic  
│   ├── utils/           # Helper functions  
│   └── styles/          # Global styles and themes  
├── public/              # Static assets  
└── tests/               # Test files  
```  
  
## 🎯 Development Focus Areas  
  
### API Integration  
  
- All API calls must go through the `services/` directory  
- Use the custom `apiClient` wrapper for consistent error handling  
- Never hardcode API endpoints - use environment variables  
  
### State Management  
  
- Use React Context for global state  
- Keep component state local when possible  
- Avoid prop drilling - use context or composition  
  
### Testing  
  
- Write unit tests for all utility functions  
- Use React Testing Library for component tests  
- Aim for 80% code coverage on new features  
  
## 🚫 Restrictions & Limitations  
  
### What NOT to do:  
  
- ❌ Run `npm start` or similar server commands (server is already running)  
- ❌ Use `any` type in TypeScript  
- ❌ Create non-responsive components  
- ❌ Skip error handling in async functions  
  
### What TO do:  
  
- ✅ Use existing development server  
- ✅ Write TypeScript-first code with proper types  
- ✅ Follow mobile-first responsive design  
- ✅ Add comprehensive error handling  
- ✅ Write tests for new features  
  
## 📝 Code Style  
  
- Use functional components with hooks (no class components)  
- Prefer `const` over `let`, avoid `var`  
- Use arrow functions for callbacks  
- Keep functions small and focused (max 50 lines)  
- Use meaningful variable names (no single letters except loop counters)  
  
## 🔍 Before Completing Any Task  
  
- [ ] Code is TypeScript compliant with proper types  
- [ ] Components are responsive and accessible  
- [ ] Error handling is implemented  
- [ ] No attempts to restart the development server  
- [ ] Tests are written and passing
```

--------------------------------

### Define Environment-Specific Rules

Source: https://forgecode.dev/docs/custom-rules-guide

Example structure for applying development standards based on the deployment environment.

```markdown
# Development Guidelines  
  
## Environment Standards  
  
### Development Environment  
  
- Include detailed logging and debug information  
- Add comprehensive error messages  
  
### Production Environment  
  
- Use structured logging with correlation IDs  
- Implement graceful error handling  
- Add performance monitoring  
```

--------------------------------

### Install ForgeCode Extension via CLI

Source: https://forgecode.dev/docs/vscode-extension

Use the command line to install the ForgeCode extension directly into VS Code.

```bash
code --install-extension ForgeCode.forge-vscode
```

--------------------------------

### Example Git Ignore Output

Source: https://forgecode.dev/docs/ignoring-files

Sample output showing which file and line number is responsible for ignoring a path.

```text
.gitignore:3:node_modules/    node_modules/package/index.js
```

--------------------------------

### Generating a Skill via Prompt

Source: https://forgecode.dev/docs/skills

Example prompt to instruct ForgeCode to generate a new skill file.

```text
Create a release-notes skill. It should collect all commits since the last tag,  
group them by type — Features, Bug Fixes, Breaking Changes — write the notes to  
the changelog, and run a validation check at the end.  
```

--------------------------------

### Command File Format with XML Tags

Source: https://forgecode.dev/docs/commands

Example of a command file using frontmatter and XML-style tags to define executable shell steps.

```markdown
---
name: check
description: Checks if the code is ready to be committed
---

- Run the `lint` and `test` commands and verify if everything is fine.
  <lint>cargo +nightly fmt --all; cargo +nightly clippy --fix --allow-staged --allow-dirty --workspace</lint>
  <test>cargo insta test --accept --unreferenced=delete</test>
- Fix every issue found in the process
```

--------------------------------

### Configure Agent Tools

Source: https://forgecode.dev/docs/creating-agents

Examples of defining tool access for an agent, ranging from explicit lists to wildcard and glob patterns.

```yaml
tools:
  - read # Read files and directories
  - write # Create and modify files
  - patch # Apply targeted changes
  - shell # Execute shell commands
  - search # Search within files
  - fetch # Retrieve external resources
  - remove # Delete files
  - undo # Reverse previous changes
```

```yaml
tools:
  - "*" # All tools
```

```yaml
tools:
  - read
  - search
  - "mcp_*" # All MCP tools — database, browser, APIs, etc.
```

--------------------------------

### Define File-Specific Standards

Source: https://forgecode.dev/docs/custom-rules-guide

Example structure for applying development standards based on file extensions.

```markdown
# Development Guidelines  
  
## File-Specific Standards  
  
### TypeScript Files (.ts/.tsx)  
  
- Use explicit type annotations  
- Add JSDoc comments for public APIs  
  
### Python Files (.py)  
  
- Use type hints following PEP 484  
- Format with black and sort imports with isort  
  
### SQL Files (.sql)  
  
- Use uppercase for SQL keywords  
- Add comments explaining complex queries  
```

--------------------------------

### Define a basic permissions policy

Source: https://forgecode.dev/docs/permissions

Example policy that allows all reads, requires confirmation for writes, and denies all rm commands.

```yaml
policies:  
  - permission: allow  
    rule:  
      read: "**/*"  
  
  - permission: confirm  
    rule:  
      write: "**/*"  
  
  - permission: deny  
    rule:  
      command: "rm*"  
```

--------------------------------

### Manage Conversations

Source: https://forgecode.dev/docs/zsh-support

Commands to start new sessions or switch between existing conversation histories.

```zsh
:new  
```

```zsh
:new hi what's the time  
```

```zsh
:conversation  
```

```zsh
:conversation -  
```

--------------------------------

### Reference Multiple Files in ForgeCode

Source: https://forgecode.dev/docs/vscode-extension

Use the @[filepath:start:end] syntax to include multiple code references in a single prompt.

```text
: Compare these approaches @[src/utils/oldMethod.js:15:45] @[src/utils/newMethod.js:20:50]  
: Review this component and its styles @[components/Button.tsx] @[styles/button.css:12:34]  
```

--------------------------------

### Define a Security Auditor Agent

Source: https://forgecode.dev/docs/creating-agents

Example of a markdown file with a YAML header defining an agent's identity, description, and tool permissions.

```yaml
---
  
id: security-auditor  
title: Security Auditor  
description: Reviews code for vulnerabilities and recommends fixes  
tools:  
  - read  
  - search  
---
  
You are a security specialist focused on finding and fixing vulnerabilities.  
  
Review code for injection flaws, authentication gaps, insecure data handling, and dependency risks. For every issue found, explain the risk and provide a specific fix with a code example.  
```

--------------------------------

### Define Project Guidelines in AGENTS.md

Source: https://forgecode.dev/docs/custom-rules-guide

Create this file in the project root to establish persistent development principles for the AI.

```markdown
# Development Guidelines  
  
## Core Standards  
  
- Add error handling to all functions  
- Include unit tests for new code  
- Use meaningful variable names  
```

--------------------------------

### Compare manual vs automated context

Source: https://forgecode.dev/docs/forge-term

Demonstrates the difference between manually explaining a failure and using the automated context capture.

```bash
# you have to reconstruct what already happened  
: the build failed with a type error in src/main.rs on line 42 because...
```

```bash
cargo build  # fails  
: fix it     # ForgeCode already knows what failed
```

--------------------------------

### Create Agent Directories

Source: https://forgecode.dev/docs/creating-agents

Commands to initialize the global and project-specific directories where ForgeCode looks for agent definitions.

```bash
# Global  
mkdir -p ~/forge/agents  
  
# Project-specific  
mkdir -p .forge/agents  
```

--------------------------------

### Show MCP server configuration

Source: https://forgecode.dev/docs/mcp-integration

Displays detailed configuration for a specific server.

```bash
forge mcp show <server_name>  
```

--------------------------------

### List MCP servers

Source: https://forgecode.dev/docs/mcp-integration

Displays all currently configured MCP servers.

```bash
forge mcp list  
```

--------------------------------

### Verifying Commands

Source: https://forgecode.dev/docs/commands

Command to list all available custom commands.

```text
:help
```

--------------------------------

### Configure nano as Editor

Source: https://forgecode.dev/docs/editor-configuration

Set the EDITOR variable to nano for prompt composition.

```bash
export EDITOR="nano"  

```

--------------------------------

### List available commands

Source: https://forgecode.dev/docs

Displays all available CLI commands by triggering the tab completion menu.

```bash
: # then press Tab WITHOUT space
```

--------------------------------

### Configure dynamic URL templates

Source: https://forgecode.dev/docs/custom-providers

Uses placeholders in the URL and models fields, populated by environment variables defined in url_param_vars.

```toml
[[providers]]  
id             = "openai_compatible"  
api_key_vars   = "OPENAI_API_KEY"  
url_param_vars = ["OPENAI_URL"]  
response_type  = "OpenAI"  
url            = "{{OPENAI_URL}}/chat/completions"  
models         = "{{OPENAI_URL}}/models"  
auth_methods   = ["api_key"]  
```

--------------------------------

### Execute Implementation from Plan

Source: https://forgecode.dev/docs/plan-and-act-guide

Instructs the ForgeCode agent to implement features based on a previously generated plan file.

```text
: Following the $(@rate-limiting-plan.md) we discussed, implement the Redis-based rate limiter for the /api/auth endpoints first in $(@src/auth).  
```

--------------------------------

### Import MCP server configuration

Source: https://forgecode.dev/docs/mcp-integration

Imports MCP server definitions via a JSON string.

```bash
forge mcp import [OPTIONS] '<json_configuration>'  
```

--------------------------------

### AI Interaction After Project Guidelines

Source: https://forgecode.dev/docs/custom-rules-guide

Demonstrates how the AI automatically applies defined standards to user requests.

```text
User: "Create a function to calculate user age"  
AI: [Creates function with error handling, input validation, and comprehensive tests]  
User: "Perfect!"  
```

--------------------------------

### Migrate existing configuration

Source: https://forgecode.dev/docs/forge-config

Moves the existing configuration directory to a new location and updates the environment variable.

```bash
mv ~/forge ~/.config/forgecode  
export FORGE_CONFIG=~/.config/forgecode  
```

--------------------------------

### Verify Binary Path

Source: https://forgecode.dev/docs/forge-bin

Check the current path and verify the binary version.

```bash
echo $FORGE_BIN          # shows the path you set  
$FORGE_BIN --version     # confirms the binary responds and shows its version
```

--------------------------------

### Select AI model

Source: https://forgecode.dev/docs

Opens an interactive menu to choose the preferred AI model for future prompts.

```bash
:model
```

--------------------------------

### Configure user prompt template

Source: https://forgecode.dev/docs/creating-agents

Define a Handlebars template to wrap user input with context variables.

```yaml
user_prompt: |-
  <{{event.name}}>{{event.value}}</{{event.name}}>  
  <system_date>{{current_date}}</system_date>
```

--------------------------------

### Enable Vi Mode

Source: https://forgecode.dev/docs/shortcuts

Add this command to your ~/.zshrc file to switch from the default Emacs keybindings to Vi mode.

```bash
bindkey -v
```

--------------------------------

### Source ZSH Integration

Source: https://forgecode.dev/docs/forge-bin

The command used by the ZSH plugin to initialize shell integration using the configured binary.

```bash
source <($FORGE_BIN extension zsh)
```

--------------------------------

### Project Structure Visualization

Source: https://forgecode.dev/docs/custom-rules

A visual representation of the project directory layout using a tree structure.

```text
├── src/  
│   ├── components/      # Reusable React components  
│   ├── pages/           # Next.js pages  
│   ├── services/        # API calls and business logic  
│   ├── utils/           # Helper functions  
│   └── styles/          # Global styles and themes  
├── public/              # Static assets  
└── tests/               # Test files
```

--------------------------------

### Define Command File Structure

Source: https://forgecode.dev/docs/commands

Shows the directory structure for custom commands where the filename determines the slash command name.

```text
.forge/  
└── commands/  
    ├── check.md     →  :check  
    └── fixme.md     →  :fixme  
```

--------------------------------

### Reference code with context

Source: https://forgecode.dev/docs/vscode-extension

Use the @ symbol followed by file path, line numbers, and a description to provide specific context to ForgeCode.

```text
@[component.tsx:45:67] this validation logic isn't working with empty strings
```

--------------------------------

### Configure persistent proxy in .env

Source: https://forgecode.dev/docs/proxy-configuration

Define proxy settings in the ~/.env file to apply them exclusively to ForgeCode.

```bash
# ~/.env  
HTTP_PROXY=http://proxy.company.com:8080  
HTTPS_PROXY=http://proxy.company.com:8080  
NO_PROXY=localhost,127.0.0.1,.internal.company.com  
```

--------------------------------

### Node.js/Express API Guidelines

Source: https://forgecode.dev/docs/custom-rules-guide

Standard practices for Node.js and Express APIs, prioritizing async/await, input validation, and dependency injection.

```markdown
# Node.js/Express API Guidelines  
  
## Core Standards  
  
- Use async/await instead of callbacks  
- Add input validation with Joi schemas  
- Include request/response logging  
- Use dependency injection for services  
- Write integration tests for all endpoints  
```

--------------------------------

### Configure FORGE_BIN for Local Builds

Source: https://forgecode.dev/docs/forge-bin

Set the binary path to a local debug build directory.

```bash
export FORGE_BIN=/path/to/forgecode/target/debug/forge
```

--------------------------------

### Configure FORGE_BIN for Multiple Versions

Source: https://forgecode.dev/docs/forge-bin

Set the binary path to a specific version, such as a nightly build.

```bash
export FORGE_BIN=~/bin/forge-nightly
```

--------------------------------

### forge mcp show

Source: https://forgecode.dev/docs/mcp-integration

Displays the full configuration for a specific MCP server.

```APIDOC
## forge mcp show

### Description
Show full configuration for one server, including command or URL, arguments, environment variables, and final resolved config.

### Usage
`forge mcp show <server_name>`

### Options
- **--porcelain** (flag) - Optional - Provides machine-readable output.
```

--------------------------------

### AI Interaction Before Project Guidelines

Source: https://forgecode.dev/docs/custom-rules-guide

Demonstrates the default AI behavior when no specific project guidelines are defined.

```text
User: "Create a function to calculate user age"  
AI: [Creates basic function without error handling or tests]  
User: "Add error handling and tests please"  
AI: [Adds basic validation]  
```

--------------------------------

### Verifying Available Skills

Source: https://forgecode.dev/docs/skills

Chat command to list all currently loaded skills.

```text
:skill  
```

--------------------------------

### Implement feature across files

Source: https://forgecode.dev/docs/vscode-extension

Use this command to apply changes across multiple files simultaneously.

```text
: Add dark mode support to @[src/components/ThemeProvider.tsx:15:45] and update @[src/styles/theme.css:23:67]  
```

--------------------------------

### Python/Django Development Guidelines

Source: https://forgecode.dev/docs/custom-rules-guide

Standard practices for Python and Django projects, focusing on type hints, thin views, and testing with pytest.

```markdown
# Python/Django Development Guidelines  
  
## Core Standards  
  
- Use type hints for all functions  
- Keep views thin, logic in services  
- Use database transactions for multi-model operations  
- Write tests using pytest with factory_boy  
- Follow Django app structure conventions  
```

--------------------------------

### Open Command Completion

Source: https://forgecode.dev/docs/zsh-support

Access the command list by typing the sentinel and pressing TAB.

```zsh
:<TAB>   # opens the full command list  
```

--------------------------------

### Define a command-based MCP server

Source: https://forgecode.dev/docs/mcp-integration

Use this structure to execute a local command as an MCP server with specific arguments and environment variables.

```json
{
  "server_name": {
    "command": "command_to_execute",
    "args": ["arg1", "arg2", "arg3"],
    "env": {
      "ENV_VAR": "value",
      "ANOTHER_VAR": "another_value"
    }
  }
}
```

--------------------------------

### Configure MCP servers manually

Source: https://forgecode.dev/docs/mcp-integration

Define multiple MCP servers in the .mcp.json file using command-based or URL-based configurations.

```json
{
  "mcpServers": {
    "browser_automation": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-browser"],
      "env": {
        "BROWSER_EXECUTABLE": "/usr/bin/chromium-browser"
      }
    },
    "api_service": {
      "command": "python",
      "args": ["-m", "mcp_server", "--port", "3001"],
      "env": {
        "API_KEY": "your_api_key_here",
        "DEBUG": "true"
      }
    },
    "webhook_server": {
      "url": "http://localhost:3000/events"
    }
  }
}
```

--------------------------------

### Open ForgeCode configuration

Source: https://forgecode.dev/docs/forgecode-config

Command to open the global configuration file in the default editor.

```text
:config-edit  
```

--------------------------------

### Manage Project Indexing

Source: https://forgecode.dev/docs/forge-services

Commands to index the project for semantic search and monitor the status of the indexing process.

```text
:sync
```

```text
:sync-status
```

--------------------------------

### Manage ZSH Key Bindings

Source: https://forgecode.dev/docs/shortcuts

Commands to inspect current key bindings, available editor actions, and specific keymap configurations.

```bash
bindkey
```

```bash
zle -al
```

```bash
bindkey -M emacs
```

--------------------------------

### forge mcp list

Source: https://forgecode.dev/docs/mcp-integration

Lists all currently configured MCP servers.

```APIDOC
## forge mcp list

### Description
List configured MCP servers.

### Usage
`forge mcp list`

### Options
- **--porcelain** (flag) - Optional - Provides machine-readable output.
```

--------------------------------

### Enable Google Application Default Credentials

Source: https://forgecode.dev/docs/custom-providers

Set auth_methods to ["google_adc"] to authenticate using Google's default credential chain instead of an API key.

```toml
[[providers]]  
id           = "vertex-custom"  
url          = "https://us-central1-aiplatform.googleapis.com/v1/projects/my-project/locations/us-central1/endpoints/openapi/chat/completions"  
response_type = "Google"  
auth_methods = ["google_adc"]  
```

--------------------------------

### Revert to Default Binary

Source: https://forgecode.dev/docs/forge-bin

Unset the custom variable and revert to the system-installed forge binary.

```bash
unset FORGE_BIN  
source <(forge extension zsh)
```

--------------------------------

### Add MCP server to user scope

Source: https://forgecode.dev/docs/mcp-integration

Configures an MCP server globally for the user.

```bash
forge mcp import --scope user '{  
  "mcpServers": {  
    "playwright": {  
      "command": "npx",  
      "args": ["@playwright/mcp@latest"]  
    }  
  }  
}'  
```

--------------------------------

### Command Directory Precedence

Source: https://forgecode.dev/docs/commands

Displays the directory hierarchy for command storage, ordered by precedence.

```text
.forge/commands/          ← project commands (highest precedence)  
~/.agents/commands/       ← shared across agent tools  
~/forge/commands/         ← global, across all projects  
```

--------------------------------

### Skill Directory Structure

Source: https://forgecode.dev/docs/skills

Visual representation of the directory hierarchy for project, agent, and global skill storage.

```text
.forge/                          # project skills (highest precedence)  
└── skills/  
    └── release-notes/  
        └── SKILL.md  
  
~/.agents/                       # agents skills (shared across agent tools)  
└── skills/  
    └── release-notes/  
        └── SKILL.md  
  
~/forge/                         # global skills (all projects)  
└── skills/  
    └── release-notes/  
        └── SKILL.md  
```

--------------------------------

### Define Static Model List for Provider

Source: https://forgecode.dev/docs/custom-providers

Use an inline array of model objects within the provider configuration to explicitly define available models.

```toml
[[providers]]  
id             = "openai"  
api_key_vars   = "OPENAI_API_KEY"  
url_param_vars = []  
response_type  = "OpenAI"  
url            = "https://api.openai.com/v1/chat/completions"  
auth_methods   = ["api_key"]  
  
[[providers.models]]  
id                           = "o1"  
name                         = "O1"  
description                  = "OpenAI's reasoning model with advanced problem-solving capabilities"  
context_length               = 200000  
tools_supported              = true  
supports_parallel_tool_calls = true  
supports_reasoning           = true  
input_modalities             = ["text"]  
  
[[providers.models]]  
id                           = "o1-2024-12-17"  
name                         = "O1 (2024-12-17)"  
description                  = "OpenAI's reasoning model snapshot from December 2024"  
context_length               = 200000  
tools_supported              = true  
supports_parallel_tool_calls = true  
supports_reasoning           = true  
input_modalities             = ["text"]
```

--------------------------------

### Request a Development Plan

Source: https://forgecode.dev/docs/plan-and-act-guide

Prompts the Muse agent to generate and critique a technical implementation plan.

```text
: Write a plan for adding rate limiting to our API. Include:  
- Which endpoints need protection  
- Storage mechanism for rate data  
- Error responses and status codes  
- Integration points with existing middleware  
  
Now critique this plan. What did you miss?  
```

--------------------------------

### Add multiple MCP servers

Source: https://forgecode.dev/docs/mcp-integration

Configures multiple MCP servers within the local scope.

```bash
forge mcp import '{  
  "mcpServers": {  
    "context7": {  
      "url": "https://mcp.context7.com/sse"  
    },  
    "deepwiki": {  
      "url": "https://mcp.deepwiki.com/sse"  
    },  
    "playwright": {  
      "command": "npx",  
      "args": ["@playwright/mcp@latest"]  
    }  
  }  
}'  
```

--------------------------------

### Configure authenticated proxy

Source: https://forgecode.dev/docs/proxy-configuration

Embed credentials directly into the proxy URL. Use restricted file permissions for the .env file to protect these credentials.

```bash
HTTP_PROXY=http://username:password@proxy.company.com:8080  
HTTPS_PROXY=http://username:password@proxy.company.com:8080  
```

--------------------------------

### Print Keyboard Reference

Source: https://forgecode.dev/docs/shortcuts

Run this command in your terminal to display the ZSH keyboard shortcut reference.

```bash
forge zsh keyboard
```

--------------------------------

### Tagging a Directory

Source: https://forgecode.dev/docs/file-tagging

Reference a directory to include all files within that folder for tasks spanning multiple related files.

```text
@[src/components]  
```

--------------------------------

### ForgeCode Configuration File (.forge.toml)

Source: https://forgecode.dev/docs/forgecode-config

The primary configuration file for defining system limits, network behavior, and agent parameters.

```toml
$schema https://forgecode.dev/schema.json  
  
# Whether to automatically open HTML dump files in the browser  
auto_open_dump = false  
  
# Maximum number of conversations to show in list  
max_conversations = 100  
  
# Maximum number of file extensions to include in the system prompt  
max_extensions = 15  
  
# Maximum characters for fetch content  
max_fetch_chars = 50000  
  
# Maximum number of files that can be read in a single batch operation  
max_file_read_batch_size = 50  
  
# Maximum file size in bytes for operations  
max_file_size_bytes = 104857600  
  
# Maximum image file size in bytes for binary read operations  
max_image_size_bytes = 262144  
  
# Maximum characters per line for file read operations  
max_line_chars = 2000  
  
# Maximum number of files read concurrently in parallel operations  
max_parallel_file_reads = 64  
  
# Maximum number of lines to read from a file  
max_read_lines = 2000  
  
# Maximum number of requests that can be made in a single turn  
max_requests_per_turn = 100  
  
# The maximum number of lines returned for FSSearch  
max_search_lines = 1000  
  
# Maximum bytes allowed for search results  
max_search_result_bytes = 10240  
  
# Maximum number of results to return from initial vector search  
max_sem_search_results = 100  
  
# Maximum characters per line for shell output  
max_stdout_line_chars = 500  
  
# Maximum lines for shell output prefix  
max_stdout_prefix_lines = 100  
  
# Maximum lines for shell output suffix  
max_stdout_suffix_lines = 100  
  
# Maximum tokens the model may generate per response for all agents (1–100,000)  
max_tokens = 20480  
  
# Maximum tool failures per turn before the orchestrator forces completion  
max_tool_failure_per_turn = 3  
  
# TTL in seconds for the model API list cache  
model_cache_ttl_secs = 604800  
  
# Whether the application is running in restricted mode; when true, tool execution requires explicit permission grants  
restricted = false  
  
# Top-k parameter for relevance filtering during semantic search  
sem_search_top_k = 10  
  
# URL for the indexing server  
services_url = "https://api.forgecode.dev/"  
  
# Whether tool use is supported in the current environment; when false, tool calls are disabled regardless of agent configuration  
tool_supported = true  
  
# Maximum execution time in seconds for a single tool call  
tool_timeout_secs = 300  
  
# Top-k vocabulary cutoff for all agents; restricts sampling to the k highest-probability tokens (1–1000)  
top_k = 30  
  
# Nucleus sampling threshold for all agents; limits token selection to the top cumulative probability mass (0.0–1.0)  
top_p = 0.8  
  
  
[retry]  
# Backoff multiplication factor for each retry attempt  
backoff_factor = 2  
  
# Initial backoff delay in milliseconds for retry operations  
initial_backoff_ms = 200  
  
# Maximum number of retry attempts  
max_attempts = 8  
  
# Minimum delay in milliseconds between retry attempts  
min_delay_ms = 1000  
  
# HTTP status codes that should trigger retries  
status_codes = [429, 500, 502, 503, 504, 408, 522, 520, 529]  
  
# Whether to suppress retry error logging and events  
suppress_errors = false  
  
  
[http]  
# Accept invalid certificates  
accept_invalid_certs = false  
  
# Adaptive window sizing for improved flow control  
adaptive_window = true  
  
# Connection timeout in seconds  
connect_timeout_secs = 30  
  
# Use Hickory DNS resolver  
hickory = false  
  
# Keep-alive interval in seconds  
keep_alive_interval_secs = 60  
  
# Keep-alive timeout in seconds  
keep_alive_timeout_secs = 10  
  
# Keep-alive while connection is idle  
keep_alive_while_idle = true  
  
# Maximum number of HTTP redirects to follow  
max_redirects = 10  
  
# Connection pool idle timeout in seconds  
pool_idle_timeout_secs = 90  
  
# Maximum idle connections per host in the connection pool  
pool_max_idle_per_host = 5  
  
# Read timeout in seconds  
read_timeout_secs = 900  
  
# TLS backend to use ("default" or "rustls")  
tls_backend = "default"  
  
  
[compact]  
# Maximum percentage of the context that can be summarized during compaction (0.0–1.0)  
eviction_window = 0.2  
  
# Maximum number of tokens to keep after compaction  
max_tokens = 2000  
  
# Maximum number of messages before triggering compaction  
message_threshold = 200  
  
# Whether to trigger compaction when the last message is from a user  
on_turn_end = false  
  
# Number of most recent messages to preserve during compaction; these messages won't be considered for summarization  
retention_window = 6  
  
# Maximum number of tokens before triggering compaction  
token_threshold = 100000  
  
  
[updates]  
# Whether to automatically install updates without prompting  
auto_update = true  
  
# How frequently ForgeCode checks for updates ("daily", "weekly", or "always")  
frequency = "daily"
```

--------------------------------

### Domain-Specific Development Rules

Source: https://forgecode.dev/docs/custom-rules-guide

Organize guidelines by development domain to separate frontend and backend requirements.

```markdown
# Development Guidelines  
  
## Frontend Development  
  
- Use React functional components  
- Add accessibility attributes  
- Include PropTypes for components  
  
## Backend Development  
  
- Use dependency injection  
- Add request logging to endpoints  
- Validate all input with schemas  
```

--------------------------------

### Triggering File Tagging with TAB Completion

Source: https://forgecode.dev/docs/file-tagging

Use the @ symbol followed by a partial path and press TAB to trigger the fuzzy picker for file selection.

```text
: explain the logic in @src/utils/helper<TAB>  
: review @package<TAB>  
```

--------------------------------

### Debug authentication issues

Source: https://forgecode.dev/docs/vscode-extension

Use this command to reference a specific code block for debugging authentication failures.

```text
: Help me debug this auth function @[src/auth/AuthService.ts:45:67] - works locally but fails in production  
```

--------------------------------

### Run Zsh diagnostics

Source: https://forgecode.dev/docs

Checks the environment for configuration issues related to the Zsh plugin.

```bash
forge zsh doctor
```

--------------------------------

### Configure FORGE_BIN for Non-standard Paths

Source: https://forgecode.dev/docs/forge-bin

Set the binary path when the executable is located outside the system PATH.

```bash
export FORGE_BIN=/opt/forgecode/bin/forge
```

--------------------------------

### Switch to Muse Agent

Source: https://forgecode.dev/docs/plan-and-act-guide

Activates the Muse agent in the ZSH shell for read-only analysis and planning.

```shell
:muse  
```

--------------------------------

### Configure custom CA certificates for proxy

Source: https://forgecode.dev/docs/proxy-configuration

Specify paths to corporate CA certificates to resolve TLS inspection errors caused by corporate proxies.

```bash
# ~/.env  
HTTPS_PROXY=http://proxy.company.com:8080  
  
# Trust the corporate CA that signs the proxy's certificates  
FORGE_HTTP__ROOT_CERT_PATHS=/etc/ssl/certs/corporate-ca.pem  
```

--------------------------------

### Send prompt via Zsh

Source: https://forgecode.dev/docs

Sends a query to the configured AI model using the colon trigger.

```bash
: Hi! What is the time?
```

--------------------------------

### Define Multiple Custom Providers

Source: https://forgecode.dev/docs/custom-providers

Use multiple [[providers]] entries to configure different endpoints, such as local services or staging gateways.

```toml
[[providers]]  
id            = "local"  
url           = "http://localhost:11434/v1/chat/completions"  
models        = "http://localhost:11434/v1/models"  
response_type = "OpenAI"  
auth_methods  = ["api_key"]  
  
[[providers]]  
id            = "staging-gateway"  
url           = "https://staging-llm.internal/v1/chat/completions"  
api_key_vars  = "STAGING_LLM_KEY"  
response_type = "OpenAI"  
auth_methods  = ["api_key"]
```

--------------------------------

### Configure system-wide proxy in shell profile

Source: https://forgecode.dev/docs/proxy-configuration

Export proxy variables in your shell configuration file to apply them to all processes in the terminal.

```bash
# ~/.zshrc  
export HTTP_PROXY=http://proxy.company.com:8080  
export HTTPS_PROXY=http://proxy.company.com:8080  
export NO_PROXY=localhost,127.0.0.1,.internal.company.com  
```

--------------------------------

### Whitelist Files in .ignore

Source: https://forgecode.dev/docs/ignoring-files

Use the ! prefix in your .ignore file to force ForgeCode to include specific files or hidden files.

```text
!path/to/file
```

```text
!.important-config
```

--------------------------------

### React/TypeScript Development Guidelines

Source: https://forgecode.dev/docs/custom-rules-guide

Standard practices for React and TypeScript projects, emphasizing strict mode, functional components, and testing conventions.

```markdown
# React/TypeScript Development Guidelines  
  
## Core Standards  
  
- Use TypeScript strict mode  
- Prefer functional components with hooks  
- Add data-testid attributes for testing  
- Use React Testing Library for tests  
- Include JSDoc comments for props  
```

--------------------------------

### Configure browser automation MCP server

Source: https://forgecode.dev/docs/mcp-integration

Use this configuration for UI testing and scripted page interactions.

```json
{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-browser"],
      "env": {
        "HEADLESS": "false",
        "VIEWPORT_WIDTH": "1920",
        "VIEWPORT_HEIGHT": "1080"
      }
    }
  }
}
```

--------------------------------

### Use External Editor for Prompts

Source: https://forgecode.dev/docs/zsh-support

Open the configured system editor to compose long prompts.

```zsh
:edit  
```

```zsh
export FORGE_EDITOR="code --wait"  
# or: export EDITOR="code --wait"  
```

--------------------------------

### Verify configuration path

Source: https://forgecode.dev/docs/forge-config

Checks the current value of the FORGE_CONFIG environment variable.

```bash
echo $FORGE_CONFIG  
```

--------------------------------

### Configure database tool MCP server

Source: https://forgecode.dev/docs/mcp-integration

Use this configuration for database operations, schema work, and migration tooling.

```json
{
  "mcpServers": {
    "database_tools": {
      "command": "node",
      "args": ["database-mcp-server.js"],
      "env": {
        "DB_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/db",
        "QUERY_TIMEOUT": "30000"
      }
    }
  }
}
```

--------------------------------

### Define Logical Policies in permissions.yaml

Source: https://forgecode.dev/docs/permissions

Use logical operators to combine multiple permission rules for more granular control over tool access.

```yaml
policies:  
  - all:  
      - permission: allow  
        rule:  
          read: "src/**/*"  
      - permission: allow  
        rule:  
          dir: "/home/user/project/*"  
          read: "**/*"  
  
  - any:  
      - permission: allow  
        rule:  
          read: "**/*.rs"  
      - permission: allow  
        rule:  
          read: "**/*.toml"  
  
  - not:  
      permission: deny  
      rule:  
        command: "rm -rf/*"  
```

--------------------------------

### Authenticate with ForgeCode Services

Source: https://forgecode.dev/docs/forge-services

Initiates the authentication flow to enable ForgeCode Services.

```text
:login
```

--------------------------------

### Refactor component with hooks

Source: https://forgecode.dev/docs/vscode-extension

Use this command to request a refactor and performance optimization for a specific component.

```text
: Can you refactor this component to use hooks? @[components/UserProfile.tsx:12:89] Also suggest performance optimizations  
```

--------------------------------

### Manage Synced Workspaces

Source: https://forgecode.dev/docs/forge-services

Opens the interface to inspect and delete indexed project data.

```text
:workspace
```

--------------------------------

### Configure external API MCP server

Source: https://forgecode.dev/docs/mcp-integration

Use this configuration for real-time data access and API-backed workflows.

```json
{
  "mcpServers": {
    "weather_api": {
      "command": "python",
      "args": ["-m", "weather_mcp_server"],
      "env": {
        "WEATHER_API_KEY": "your_api_key",
        "DEFAULT_LOCATION": "San Francisco"
      }
    }
  }
}
```

--------------------------------

### Configure Custom Headers for a Provider

Source: https://forgecode.dev/docs/custom-providers

Use the [providers.custom_headers] table to inject specific headers like User-Agent into every request for a provider.

```toml
[[providers]]  
id            = "kimi_coding"  
api_key_vars  = "KIMI_API_KEY"  
url_param_vars = []  
response_type = "OpenAI"  
url           = "https://api.kimi.com/coding/v1/chat/completions"  
models        = "https://api.kimi.com/coding/v1/models"  
auth_methods  = ["api_key"]  
  
[providers.custom_headers]  
User-Agent = "KimiCLI/1.0.0"  
```

--------------------------------

### Configure persistent environment variables

Source: https://forgecode.dev/docs/forge-config

Sets the configuration path persistently in environment files.

```bash
FORGE_CONFIG=~/.config/forgecode  
```

```bash
export FORGE_CONFIG=~/.config/forgecode  
```

--------------------------------

### Refine Guideline Specificity

Source: https://forgecode.dev/docs/custom-rules-guide

Comparison between vague and actionable guideline definitions.

```markdown
<!-- Too vague -->  
  
# Guidelines  
  
- Write good code  
- Add tests  
- Handle errors  
  
<!-- Better -->  
  
# Guidelines  
  
- Add error handling with try/catch blocks  
- Include unit tests with arrange-act-assert pattern  
```

--------------------------------

### Tag Files in Prompts

Source: https://forgecode.dev/docs/zsh-support

Reference specific files using the @ symbol and tab completion or direct paths.

```zsh
: review the changes in @package<TAB>  
: explain the logic in @src/utils/helper<TAB>  
: optimize the queries in @database/queries<TAB>  
```

```zsh
: review the changes in @[src/components/Header.tsx]  
```

--------------------------------

### Export Session Diagnostics

Source: https://forgecode.dev/docs/ignoring-files

Command to generate a diagnostic dump for troubleshooting file visibility issues.

```text
:dump html
```

--------------------------------

### Tagging Images

Source: https://forgecode.dev/docs/file-tagging

Reference image files to provide visual context such as UI states or diagrams.

```text
@[assets/button-states.png]  
@[docs/wireframes/user-journey.jpg]  
```

--------------------------------

### Verify Active Services

Source: https://forgecode.dev/docs/forge-services

Checks the status of system tools to confirm that sem_search is active.

```text
:tools
```

--------------------------------

### Resolve type mismatches

Source: https://forgecode.dev/docs/vscode-extension

Use this command to compare an API file and a type definition file to resolve mismatches.

```text
: @[src/api/users.js:156:203] @[src/types/User.ts] have a type mismatch - API returns 'user_id' but type expects 'userId'  
```

--------------------------------

### Tagging a Single File

Source: https://forgecode.dev/docs/file-tagging

Reference a specific file to provide direct code context to the agent.

```text
@[src/auth/AuthService.ts]  
```

--------------------------------

### Importing Claude Code Skills

Source: https://forgecode.dev/docs/skills

Command to migrate existing Claude Code skills into a ForgeCode project.

```bash
cp -r .claude/skills .forge/skills  
```

--------------------------------

### forge mcp import

Source: https://forgecode.dev/docs/mcp-integration

Imports one or more MCP servers from a provided JSON configuration string.

```APIDOC
## forge mcp import

### Description
Import one or more MCP servers from a JSON string.

### Usage
`forge mcp import [OPTIONS] '<json_configuration>'`

### Options
- **-s, --scope** (string) - Optional - The scope of the import, either `local` or `user` (default: `local`).
- **--porcelain** (flag) - Optional - Provides machine-readable output.
```

--------------------------------

### Configure default session provider

Source: https://forgecode.dev/docs/custom-providers

Set the default provider and model for all conversations within the session block of your configuration.

```toml
[session]  
provider_id = "my-provider"  
model_id    = "meta-llama/Llama-3.3-70B-Instruct"
```

--------------------------------

### Persist FORGE_BIN in .zshrc

Source: https://forgecode.dev/docs/forge-bin

Define the variable and source the integration in the shell configuration file.

```bash
# ~/.zshrc  
export FORGE_BIN=/path/to/your/forge  
  
# This line sources the ZSH integration using $FORGE_BIN  
source <($FORGE_BIN extension zsh)
```

--------------------------------

### Test Ignore Patterns

Source: https://forgecode.dev/docs/ignoring-files

Commands to verify if specific files or patterns are being ignored by the system.

```bash
# Check if a specific file matches  
git check-ignore -v path/to/file  
  
# Find all files matching a pattern  
find . -name "*.log"  
  
# Check which of those are ignored  
git check-ignore -v $(find . -name "*.log")
```

--------------------------------

### Define a basic file read policy

Source: https://forgecode.dev/docs/permissions

The top-level structure for defining a policy that allows reading specific file types.

```yaml
policies:  
  - permission: allow  
    rule:  
      read: "**/*.rs"  
```

--------------------------------

### Define a URL-based MCP server

Source: https://forgecode.dev/docs/mcp-integration

Use this structure to connect to an MCP server hosted at a specific URL.

```json
{
  "server_name": {
    "url": "http://localhost:3000/events"
  }
}
```

--------------------------------

### Define a custom provider in .forge.toml

Source: https://forgecode.dev/docs/custom-providers

Add a new provider entry to your configuration file by specifying the unique ID, endpoint URL, and authentication details.

```toml
[[providers]]  
id             = "my-provider"  
url            = "https://my-llm-gateway.internal/v1/chat/completions"  
api_key_vars   = "MY_PROVIDER_API_KEY"  
response_type  = "OpenAI"  
auth_methods   = ["api_key"]
```

--------------------------------

### Configure buffer size

Source: https://forgecode.dev/docs/forge-term

Sets the number of commands stored in the buffer for ForgeCode context.

```bash
export FORGE_TERM_MAX_COMMANDS=20
```

--------------------------------

### Define agent configuration in YAML

Source: https://forgecode.dev/docs/creating-agents

Use this structure to define agent identity, model provider, sampling parameters, and reasoning capabilities.

```yaml
---
  id: my-agent  
title: My Agent  
description: Brief description of what this agent does  
  
# Model selection (optional — defaults to your configured model)  
model: claude-sonnet-4  
provider: anthropic # Must be snake_case: open_router, openai, requesty, etc.  
  
# Sampling (optional)  
temperature: 0.1 # 0.0–2.0 — lower = more precise, higher = more creative  
top_p: 0.9 # 0.0–1.0 nucleus sampling threshold  
top_k: 40 # 1–1000  
max_tokens: 8192 # 1–100,000  
  
# Limits (optional)  
max_turns: 50 # Max conversation turns before the agent stops  
max_requests_per_turn: 10  
max_tool_failure_per_turn: 3 # Max tool failures per turn before forcing completion  
  
# Visibility (optional)  
tool_supported: true # Whether this agent can be called as a tool by other agents  
  
# Reasoning (optional — for models that support it)  
reasoning:  
  enabled: true  
  effort: medium # low | medium | high  
  max_tokens: 2048 # Must be > 1024 and < max_tokens  
  exclude: false # Hide reasoning output from the response  
---
```

--------------------------------

### Configure Vim or Neovim as Editor

Source: https://forgecode.dev/docs/editor-configuration

Set the EDITOR variable to vim or nvim. These editors block the terminal by default, so no additional flags are required.

```bash
export EDITOR="vim"  
# or  
export EDITOR="nvim"  

```

--------------------------------

### Define multiline strings in YAML

Source: https://forgecode.dev/docs/creating-agents

Use the pipe operator to define multiline strings for agent descriptions.

```yaml
description: |
  Analyzes code for security vulnerabilities,
  explains each risk, and provides concrete fixes.
```
Tokens:
Raw