[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-5580":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":25,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":43,"readmeContent":44,"aiSummary":45,"trendingCount":16,"starSnapshotCount":16,"syncStatus":46,"lastSyncTime":47,"discoverSource":48},5580,"forgecode","tailcallhq\u002Fforgecode","tailcallhq","AI enabled pair programmer for Claude, GPT, O Series, Grok, Deepseek, Gemini and 300+ models","https:\u002F\u002Fforgecode.dev",null,"Rust",7403,1448,23,52,0,4,24,142,12,40.48,"Apache License 2.0",false,"main",true,[27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42],"ai-pair-programming","ai-workflows","artifical-intelligense","claude-3-7-sonnet","claude-4","claude-4-sonnet","cli-assistant","command-line","grok","llm","multi-agent-reinforcement-learning","open-router","open-source-claude-code","openai","qwen","shell","2026-06-12 02:01:12","\u003Ch1 align=\"center\">⚒️ Forge: AI-Enhanced Terminal Development Environment\u003C\u002Fh1>\n\u003Cp align=\"center\">A comprehensive coding agent that integrates AI capabilities with your development environment\u003C\u002Fp>\n\n\u003Cp align=\"center\">\u003Ccode>curl -fsSL https:\u002F\u002Fforgecode.dev\u002Fcli | sh\u003C\u002Fcode>\u003C\u002Fp>\n\n[![CI Status](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Factions\u002Fworkflow\u002Fstatus\u002Ftailcallhq\u002Fforgecode\u002Fci.yml?style=for-the-badge)](https:\u002F\u002Fgithub.com\u002Ftailcallhq\u002Fforgecode\u002Factions)\n[![GitHub Release](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Ftailcallhq\u002Fforgecode?style=for-the-badge)](https:\u002F\u002Fgithub.com\u002Ftailcallhq\u002Fforgecode\u002Freleases)\n[![Discord](https:\u002F\u002Fimg.shields.io\u002Fdiscord\u002F1044859667798568962?style=for-the-badge&cacheSeconds=120&logo=discord)](https:\u002F\u002Fdiscord.gg\u002FkRZBPpkgwq)\n[![CLA assistant](https:\u002F\u002Fcla-assistant.io\u002Freadme\u002Fbadge\u002Ftailcallhq\u002Fforgecode?style=for-the-badge)](https:\u002F\u002Fcla-assistant.io\u002Ftailcallhq\u002Fforgecode)\n\n![Code-Forge Demo](https:\u002F\u002Fassets.antinomy.ai\u002Fimages\u002Fforge_demo_2x.gif)\n\n---\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Table of Contents\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n- [Quickstart](#quickstart)\n- [Usage Examples](#usage-examples)\n- [Why Forge?](#why-forge)\n- [How Forge Works: Three Modes](#how-forge-works-three-modes)\n  - [Interactive Mode (TUI)](#interactive-mode-tui)\n  - [One-Shot CLI Mode](#one-shot-cli-mode)\n  - [ZSH Plugin Mode (`:` prefix)](#zsh-plugin-mode--prefix)\n- [ZSH Plugin: The `:` Prefix System](#zsh-plugin-the--prefix-system)\n  - [Agents](#agents)\n  - [Sending Prompts](#sending-prompts)\n  - [Attaching Files](#attaching-files)\n  - [Conversation Management](#conversation-management)\n  - [Git Integration](#git-integration)\n  - [Shell Command Tools](#shell-command-tools)\n  - [Session & Configuration](#session--configuration)\n  - [Skills](#skills)\n  - [Customizing Agent Behavior](#customizing-agent-behavior)\n  - [Semantic Search (Workspace)](#semantic-search-workspace)\n  - [Quick Reference: All `:` Commands](#quick-reference-all--commands)\n- [Command-Line Options](#command-line-options)\n- [Advanced Configuration](#advanced-configuration)\n  - [Provider Configuration](#provider-configuration)\n    - [Managing Provider Credentials](#managing-provider-credentials)\n    - [Deprecated: Environment Variables](#deprecated-environment-variables)\n  - [forge.yaml Configuration Options](#forgeyaml-configuration-options)\n  - [Environment Variables](#environment-variables)\n  - [MCP Configuration](#mcp-configuration)\n  - [Example Use Cases](#example-use-cases)\n  - [Usage in Multi-Agent Workflows](#usage-in-multi-agent-workflows)\n- [Documentation](#documentation)\n- [Community](#community)\n- [Support Us](#support-us)\n\n\u003C\u002Fdetails>\n\n---\n\n## Quickstart\n\nTo get started with Forge, run the command below:\n\n```bash\ncurl -fsSL https:\u002F\u002Fforgecode.dev\u002Fcli | sh\n```\n\nOn first run, Forge will guide you through setting up your AI provider credentials using the interactive login flow. Alternatively, you can configure providers beforehand:\n\n```bash\n# Configure your provider credentials interactively\nforge provider login\n\n# Then start Forge\nforge\n```\nThat's it! Forge is now ready to assist you with your development tasks.\n\n## Usage Examples\n\nForge can be used in different ways depending on your needs. Here are some common usage patterns:\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Code Understanding\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> Can you explain how the authentication system works in this codebase?\n```\n\nForge 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.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Implementing New Features\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> I need to add a dark mode toggle to our React application. How should I approach this?\n```\n\nForge will suggest the best approach based on your current codebase, explain the steps needed, and even scaffold the necessary components and styles for you.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Debugging Assistance\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> I'm getting this error: \"TypeError: Cannot read property 'map' of undefined\". What might be causing it?\n```\n\nForge will analyze the error, suggest potential causes based on your code, and propose different solutions to fix the issue.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Code Reviews\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> Please review the code in src\u002Fcomponents\u002FUserProfile.js and suggest improvements\n```\n\nForge will analyze the code, identify potential issues, and suggest improvements for readability, performance, security, and maintainability.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Learning New Technologies\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> I want to integrate GraphQL into this Express application. Can you explain how to get started?\n```\n\nForge will provide a tailored tutorial on integrating GraphQL with Express, using your specific project structure as context.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Database Schema Design\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> I need to design a database schema for a blog with users, posts, comments, and categories\n```\n\nForge will suggest an appropriate schema design, including tables\u002Fcollections, relationships, indexes, and constraints based on your project's existing database technology.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Refactoring Legacy Code\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> Help me refactor this class-based component to use React Hooks\n```\n\nForge can help modernize your codebase by walking you through refactoring steps and implementing them with your approval.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Git Operations\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> I need to merge branch 'feature\u002Fuser-profile' into main but there are conflicts\n```\n\nForge can guide you through resolving git conflicts, explaining the differences and suggesting the best way to reconcile them.\n\n\u003C\u002Fdetails>\n\n## Why Forge?\n\nForge is designed for developers who want to enhance their workflow with AI assistance while maintaining full control over their development environment.\n\n- **Zero configuration** - Just add your API key and you're ready to go\n- **Seamless integration** - Works right in your terminal, where you already work\n- **Multi-provider support** - Use OpenAI, Anthropic, or other LLM providers\n- **Secure by design** - Restricted shell mode limits file system access and prevents unintended changes\n- **Open-source** - Transparent, extensible, and community-driven\n\nForge helps you code faster, solve complex problems, and learn new technologies without leaving your terminal.\n\n---\n\n## How Forge Works: Three Modes\n\nForge has three distinct ways to use it. Understanding this distinction upfront will save you confusion.\n\n### Interactive Mode (TUI)\n\nRunning `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.\n\n```bash\nforge                              # Start a new interactive session\nforge conversation resume \u003Cid>     # Resume a specific saved conversation in interactive mode\nforge --conversation-id \u003Cid>       # Same: resume conversation by ID\nforge --agent \u003Cagent-id>           # Start interactive session with a specific agent\nforge -C \u002Fpath\u002Fto\u002Fproject          # Start in a specific directory\nforge --sandbox experiment-name    # Create an isolated git worktree + branch, then start there\n```\n\nOnce inside interactive mode, type your prompt and press Enter. Forge reads files, writes patches, runs commands, and maintains context across the whole session.\n\n### One-Shot CLI Mode\n\nPass `-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.\n\n```bash\nforge -p \"Explain the purpose of src\u002Fmain.rs\"\nforge -p \"Add error handling to the parse() function in lib.rs\"\necho \"What does this do?\" | forge    # Pipe input as the prompt\nforge commit                         # Generate an AI commit message and commit (exits when done)\nforge commit --preview               # Generate commit message, print it, then exit\nforge suggest \"find large log files\" # Translate natural language to a shell command, then exit\n```\n\n> **Note:** `forge conversation resume \u003Cid>` 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.\n\n### ZSH Plugin Mode (`:` prefix)\n\nInstall 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.\n\n```zsh\n: refactor the auth module      # Send a prompt to the active agent\n:commit                         # AI-powered git commit\n:suggest \"find large log files\" # Translate description → shell command in your buffer\n:conversation                   # Browse saved conversations with interactive picker\n```\n\nSee the full [ZSH Plugin reference below](#zsh-plugin-the--prefix-system) for all commands and aliases.\n\n---\n\n## ZSH Plugin: The `:` Prefix System\n\nWhen 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.\n\n**How it works:** Lines starting with `:` are intercepted before the shell sees them and routed to Forge. Everything else runs normally.\n\n```zsh\n: \u003Cprompt>         # Send a prompt to the active agent\n:sage \u003Cprompt>     # Send a prompt to a specific agent by name (sage, muse, forge, or any custom agent)\n:agent \u003Cname>      # Switch the active agent; opens interactive picker if no name given\n```\n\n### Agents\n\nForge ships with three built-in agents, each with a different role:\n\n| Agent | Alias | Purpose | Modifies files? |\n|---|---|---|---|\n| `forge` | (default) | Implementation: builds features, fixes bugs, and runs tests | Yes |\n| `sage` | `:ask` | Research: maps architecture, traces data flow, and reads code | No |\n| `muse` | `:plan` | Planning: analyzes structure and writes implementation plans to `plans\u002F` | No |\n\n### Sending Prompts\n\n```zsh\n: refactor the auth module to use the new middleware\n:sage how does the caching layer work?    # sage = read-only research agent\n:muse design a deployment strategy        # muse = planning agent (writes to plans\u002F)\n:ask how does X work?                     # alias for :sage\n:plan create a migration plan             # alias for :muse\n```\n\nThe agent context persists. Typing `:sage` alone (no prompt text) switches the active agent to sage for all subsequent `: \u003Cprompt>` commands.\n\n### Attaching Files\n\nType `@` 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.\n\n```zsh\n: review this code @[src\u002Fauth.rs] @[tests\u002Fauth_test.rs]\n```\n\n### Conversation Management\n\nForge saves every conversation. You can switch between them like switching directories.\n\n```zsh\n:new                      # Start a fresh conversation (saves current for :conversation -)\n:new \u003Cinitial prompt>     # Start a new conversation and immediately send a prompt\n:conversation             # Open interactive picker: browse and switch conversations with preview\n:conversation \u003Cid>        # Switch directly to a conversation by ID\n:conversation -           # Toggle between current and previous conversation (like cd -)\n:clone                    # Branch the current conversation (try a different direction)\n:clone \u003Cid>               # Clone a specific conversation by ID\n:rename \u003Cname>            # Rename the current conversation\n:conversation-rename      # Rename a conversation via interactive picker\n:retry                    # Retry the last prompt (useful if the AI misunderstood)\n:copy                     # Copy the last AI response to clipboard as markdown\n:dump                     # Export conversation as JSON\n:dump html                # Export conversation as formatted HTML\n:compact                  # Manually compact context to free up token budget\n```\n\n### Git Integration\n\n```zsh\n:commit                   # AI reads your diff, writes a commit message, and commits immediately\n:commit \u003Ccontext>         # Same, but pass extra context: :commit fix typo in readme\n:commit-preview           # AI generates the message and puts \"git commit -m '...'\" in your buffer\n                          # so you can review\u002Fedit the message before pressing Enter\n```\n\n### Shell Command Tools\n\n```zsh\n:suggest \u003Cdescription>    # Translate natural language to a shell command and put it in your buffer\n:edit                     # Open $EDITOR to compose a complex multi-line prompt, then send it\n```\n\n### Session & Configuration\n\nSome commands change settings for the current session only. Others persist to your config file (`~\u002Fforge\u002F.forge.toml`). The distinction matters:\n\n```zsh\n# Session-only (reset when you close the terminal; not saved to config)\n:model \u003Cmodel-id>              # Change model for this session only\n:reasoning-effort \u003Clevel>      # Set reasoning effort: none\u002Fminimal\u002Flow\u002Fmedium\u002Fhigh\u002Fxhigh\u002Fmax\n:agent \u003Cid>                    # Switch active agent for this session\n\n# Persistent (saved to config file)\n:config-model \u003Cmodel-id>       # Set default model globally  (alias: :cm)\n:config-provider               # Switch provider globally    (alias: :provider, :p)\n:config-reasoning-effort \u003Clvl> # Set default reasoning effort globally (alias: :cre)\n:config-commit-model \u003Cid>      # Set model used for :commit  (alias: :ccm)\n:config-suggest-model \u003Cid>     # Set model used for :suggest (alias: :csm)\n:config-reload                 # Reset session overrides back to global config (alias: :cr)\n\n# View & edit config\n:info                          # Show current session info (model, agent, conversation ID)\n:config                        # Display effective resolved configuration in TOML format\n:config-edit                   # Open config file in $EDITOR (alias: :ce)\n:tools                         # List available tools for the current agent\n:skill                         # List available skills\n```\n\n### Skills\n\nSkills are reusable workflows the AI can invoke as tools. Forge ships three built-in skills:\n\n- **`create-skill`**: scaffold a new custom skill\n- **`execute-plan`**: execute a plan file from `plans\u002F`\n- **`github-pr-description`**: generate a PR description from your diff\n\nUse `: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`.\n\n**Custom skills** live in `SKILL.md` files with YAML front-matter. Precedence (highest first):\n\n| Location | Path | Scope |\n|---|---|---|\n| Project-local | `.forge\u002Fskills\u002F\u003Cname>\u002FSKILL.md` | This project only |\n| Global | `~\u002Fforge\u002Fskills\u002F\u003Cname>\u002FSKILL.md` | All projects |\n| Built-in | Embedded in binary | Always available |\n\nProject-local skills override global ones, which override built-in ones. To scaffold a new skill, ask: `: create a new skill`.\n\n### Customizing Agent Behavior\n\n**`AGENTS.md`:** Create this file in your project root (or `~\u002Fforge\u002FAGENTS.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.\n\n**Custom agents:** Place a `.md` file with YAML front-matter in `.forge\u002Fagents\u002F` (project) or `~\u002Fforge\u002Fagents\u002F` (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\u002Fforge_repo\u002Fsrc\u002Fagents\u002F` are good examples of the format.\n\n**Custom commands:** Place YAML files in `.forge\u002Fcommands\u002F` (project) or `~\u002Fforge\u002Fcommands\u002F` (global) to define shortcut commands available via `:commandname`. Commands can also be defined inline in `forge.yaml` under the `commands:` key.\n\n### Semantic Search (Workspace)\n\n```zsh\n:sync                     # Index your codebase for semantic search\n:workspace-init           # Initialize workspace for indexing\n:workspace-status         # Show indexing status\n:workspace-info           # Show workspace details\n```\n\nAfter 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:\u002F\u002Fapi.forgecode.dev`. Set `FORGE_WORKSPACE_SERVER_URL` to override this if self-hosting.\n\n### Quick Reference: All `:` Commands\n\n\n| Command | Alias | What it does |\n|---|---|---|\n| `: \u003Cprompt>` | | Send prompt to active agent |\n| `:new` | `:n` | Start new conversation |\n| `:conversation` | `:c` | Browse\u002Fswitch conversations (interactive picker) |\n| `:conversation -` | | Toggle to previous conversation |\n| `:clone` | | Branch current conversation |\n| `:rename \u003Cname>` | `:rn` | Rename current conversation |\n| `:conversation-rename` | | Rename conversation (interactive picker) |\n| `:retry` | `:r` | Retry last prompt |\n| `:copy` | | Copy last response to clipboard |\n| `:dump` | `:d` | Export conversation as JSON |\n| `:compact` | | Compact context |\n| `:commit` | | AI commit (immediate) |\n| `:commit-preview` | | AI commit (review first) |\n| `:suggest \u003Cdesc>` | `:s` | Translate natural language to command |\n| `:edit` | `:ed` | Compose prompt in $EDITOR |\n| `:sage \u003Cprompt>` | `:ask` | Q&A \u002F code understanding agent |\n| `:muse \u003Cprompt>` | `:plan` | Planning agent |\n| `:agent \u003Cname>` | `:a` | Switch active agent (interactive picker if no name given) |\n| `:model \u003Cid>` | `:m` | Set model for this session only |\n| `:config-model \u003Cid>` | `:cm` | Set default model (persistent) |\n| `:reasoning-effort \u003Clvl>` | `:re` | Set reasoning effort for session |\n| `:config-reload` | `:cr` | Reset session overrides to global config |\n| `:info` | `:i` | Show session info |\n| `:sync` | `:workspace-sync` | Index codebase for semantic search |\n| `:tools` | `:t` | List available tools |\n| `:skill` | | List available skills |\n| `:login` | `:provider-login` | Login to a provider |\n| `:logout` | | Logout from a provider |\n| `:keyboard-shortcuts` | `:kb` | Show keyboard shortcuts |\n| `:doctor` | | Run shell environment diagnostics |\n\n---\n\n## Command-Line Options\n\nHere's a quick reference of Forge's command-line options:\n\n| Option                              | Description                                                              |\n| ----------------------------------- | ------------------------------------------------------------------------ |\n| `-p, --prompt \u003CPROMPT>`             | Direct prompt to process without entering interactive mode               |\n| `-e, --event \u003CEVENT>`               | Dispatch an event to the workflow in JSON format                         |\n| `--conversation \u003CCONVERSATION>`     | Path to a JSON file containing the conversation to execute               |\n| `--conversation-id \u003CID>`            | Resume or continue an existing conversation by ID                        |\n| `--agent \u003CAGENT>`                   | Agent ID to use for this session                                         |\n| `-C, --directory \u003CDIR>`             | Change to this directory before starting                                 |\n| `--sandbox \u003CNAME>`                  | Create an isolated git worktree + branch for safe experimentation        |\n| `--verbose`                         | Enable verbose logging output                                            |\n| `-h, --help`                        | Print help information                                                   |\n| `-V, --version`                     | Print version                                                            |\n\n### Subcommands\n\n```bash\n# Conversations\nforge conversation list                  # List all saved conversations\nforge conversation resume \u003Cid>           # Resume a conversation in interactive mode\nforge conversation new                   # Create a new conversation ID (prints it)\nforge conversation dump \u003Cid>             # Export conversation as JSON\nforge conversation compact \u003Cid>          # Compact conversation context\nforge conversation retry \u003Cid>            # Retry last message\nforge conversation clone \u003Cid>            # Clone a conversation\nforge conversation rename \u003Cid> \u003Cname>    # Rename a conversation\nforge conversation delete \u003Cid>           # Delete a conversation permanently\nforge conversation info \u003Cid>             # Show conversation details\nforge conversation stats \u003Cid>            # Show token usage statistics\nforge conversation show \u003Cid>             # Show last assistant message\n\n# Commits\nforge commit                             # Generate AI commit message and commit\nforge commit --preview                   # Generate commit message only (prints it)\nforge commit fix the auth bug            # Pass extra context for the commit message\n\n# Shell command suggestion\nforge suggest \"list files by size\"       # Translate description to a shell command\n\n# Providers\nforge provider login                     # Add or update provider credentials (interactive)\nforge provider logout                    # Remove provider credentials\nforge list provider                      # List supported providers\n\n# Models & agents\nforge list model                         # List available models\nforge list agent                         # List available agents\n\n# Workspace \u002F semantic search\nforge workspace sync                     # Index current directory for semantic search\nforge workspace init                     # Initialize workspace\nforge workspace status                   # Show indexing status\nforge workspace query \u003Ctext>             # Query the semantic index\n\n# MCP servers\nforge mcp list                           # List configured MCP servers\nforge mcp import                         # Add a server from JSON\nforge mcp show                           # Show server configuration\nforge mcp remove                         # Remove a server\nforge mcp reload                         # Reload all servers and rebuild caches\n\n# Other\nforge info                               # Show config, active model, environment\nforge list tool --agent \u003Cid>             # List tools for a specific agent\nforge doctor                             # Run shell environment diagnostics\nforge update                             # Update forge to the latest version\nforge setup                              # Install ZSH plugin (updates .zshrc)\n```\n\n## Advanced Configuration\n\n### Provider Configuration\n\nForge supports multiple AI providers. The recommended way to configure providers is using the interactive login command:\n\n```bash\nforge provider login\n```\n\nThis will:\n\n1. Show you a list of available providers\n2. Guide you through entering the required credentials\n\n#### Managing Provider Credentials\n\n```bash\n# Login to a provider (add or update credentials)\nforge provider login\n\n# Remove provider credentials\nforge provider logout\n\n# List supported providers\nforge provider list\n```\n\n#### Deprecated: Environment Variables\n\n> **⚠️ DEPRECATED**: Using `.env` files for provider configuration is deprecated and will be removed in a future version. Please use `forge provider login` instead.\n\nFor backward compatibility, Forge still supports environment variables. On first run, any credentials found in environment variables will be automatically migrated to file-based storage.\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Legacy Environment Variable Setup (Deprecated)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>OpenRouter\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nOPENROUTER_API_KEY=\u003Cyour_openrouter_api_key>\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Requesty\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nREQUESTY_API_KEY=\u003Cyour_requesty_api_key>\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>x-ai\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nXAI_API_KEY=\u003Cyour_xai_api_key>\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>z.ai\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nZAI_API_KEY=\u003Cyour_zai_api_key>\n\n# Or for coding plan subscription\nZAI_CODING_API_KEY=\u003Cyour_zai_coding_api_key>\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Cerebras\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nCEREBRAS_API_KEY=\u003Cyour_cerebras_api_key>\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>IO Intelligence\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nIO_INTELLIGENCE_API_KEY=\u003Cyour_io_intelligence_api_key>\n```\n\n```yaml\n# forge.yaml\nmodel: meta-llama\u002FLlama-3.3-70B-Instruct\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>OpenAI\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nOPENAI_API_KEY=\u003Cyour_openai_api_key>\n```\n\n```yaml\n# forge.yaml\nmodel: o3-mini-high\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Anthropic\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nANTHROPIC_API_KEY=\u003Cyour_anthropic_api_key>\n```\n\n```yaml\n# forge.yaml\nmodel: claude-3.7-sonnet\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Google Vertex AI\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**Setup Instructions:**\n\n1. **Install Google Cloud CLI** and authenticate:\n\n   ```bash\n   gcloud auth login\n   gcloud config set project YOUR_PROJECT_ID\n   ```\n\n2. **Get your authentication token**:\n\n   ```bash\n   gcloud auth print-access-token\n   ```\n\n3. **Use the token when logging in via Forge**:\n\n   ```bash\n   forge provider login\n   # Select Google Vertex AI and enter your credentials\n   ```\n\n**Legacy `.env` setup:**\n\n```bash\n# .env\nPROJECT_ID=\u003Cyour_project_id>\nLOCATION=\u003Cyour_location>\nVERTEX_AI_AUTH_TOKEN=\u003Cyour_auth_token>\n```\n\n```yaml\n# forge.yaml\nmodel: google\u002Fgemini-2.5-pro\n```\n\n**Available Models:**\n- Claude models: `claude-sonnet-4@20250514`\n- Gemini models: `gemini-2.5-pro`, `gemini-2.0-flash`\n\nUse the `\u002Fmodel` command in Forge CLI to see all available models.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>OpenAI-Compatible Providers\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nOPENAI_API_KEY=\u003Cyour_provider_api_key>\nOPENAI_URL=\u003Cyour_provider_url>\n```\n\n```yaml\n# forge.yaml\nmodel: \u003Cprovider-specific-model>\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Groq\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nOPENAI_API_KEY=\u003Cyour_groq_api_key>\nOPENAI_URL=https:\u002F\u002Fapi.groq.com\u002Fopenai\u002Fv1\n```\n\n```yaml\n# forge.yaml\nmodel: deepseek-r1-distill-llama-70b\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Amazon Bedrock\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nTo use Amazon Bedrock models with Forge, you'll need to first set up the [Bedrock Access Gateway](https:\u002F\u002Fgithub.com\u002Faws-samples\u002Fbedrock-access-gateway):\n\n1. **Set up Bedrock Access Gateway**:\n\n   - Follow the deployment steps in the [Bedrock Access Gateway repo](https:\u002F\u002Fgithub.com\u002Faws-samples\u002Fbedrock-access-gateway)\n   - Create your own API key in Secrets Manager\n   - Deploy the CloudFormation stack\n   - Note your API Base URL from the CloudFormation outputs\n\n2. **Configure in Forge**:\n\n   ```bash\n   forge provider login\n   # Select OpenAI-compatible provider and enter your Bedrock Gateway details\n   ```\n\n**Legacy `.env` setup:**\n\n```bash\n# .env\nOPENAI_API_KEY=\u003Cyour_bedrock_gateway_api_key>\nOPENAI_URL=\u003Cyour_bedrock_gateway_base_url>\n```\n\n```yaml\n# forge.yaml\nmodel: anthropic.claude-3-opus\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>ForgeCode Services\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nFORGE_API_KEY=\u003Cyour_forge_api_key>\n```\n\n```yaml\n# forge.yaml\nmodel: claude-3.7-sonnet\n```\n\n\u003C\u002Fdetails>\n\n\u003C\u002Fdetails>\n\n---\n\n### forge.yaml Configuration Options\n\n### Environment Variables\n\nForge supports several environment variables for advanced configuration and fine-tuning. These can be set in your `.env` file or system environment.\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Retry Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nControl how Forge handles retry logic for failed requests:\n\n```bash\n# .env\nFORGE_RETRY_INITIAL_BACKOFF_MS=1000    # Initial backoff time in milliseconds (default: 1000)\nFORGE_RETRY_BACKOFF_FACTOR=2           # Multiplier for backoff time (default: 2)\nFORGE_RETRY_MAX_ATTEMPTS=3             # Maximum retry attempts (default: 3)\nFORGE_SUPPRESS_RETRY_ERRORS=false      # Suppress retry error messages (default: false)\nFORGE_RETRY_STATUS_CODES=429,500,502   # HTTP status codes to retry (default: 429,500,502,503,504)\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>HTTP Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nFine-tune HTTP client behavior for API requests:\n\n```bash\n# .env\nFORGE_HTTP_CONNECT_TIMEOUT=30              # Connection timeout in seconds (default: 30)\nFORGE_HTTP_READ_TIMEOUT=900                # Read timeout in seconds (default: 900)\nFORGE_HTTP_POOL_IDLE_TIMEOUT=90            # Pool idle timeout in seconds (default: 90)\nFORGE_HTTP_POOL_MAX_IDLE_PER_HOST=5        # Max idle connections per host (default: 5)\nFORGE_HTTP_MAX_REDIRECTS=10                # Maximum redirects to follow (default: 10)\nFORGE_HTTP_USE_HICKORY=false               # Use Hickory DNS resolver (default: false)\nFORGE_HTTP_TLS_BACKEND=default             # TLS backend: \"default\" or \"rustls\" (default: \"default\")\nFORGE_HTTP_MIN_TLS_VERSION=1.2             # Minimum TLS version: \"1.0\", \"1.1\", \"1.2\", \"1.3\"\nFORGE_HTTP_MAX_TLS_VERSION=1.3             # Maximum TLS version: \"1.0\", \"1.1\", \"1.2\", \"1.3\"\nFORGE_HTTP_ADAPTIVE_WINDOW=true            # Enable HTTP\u002F2 adaptive window (default: true)\nFORGE_HTTP_KEEP_ALIVE_INTERVAL=60          # Keep-alive interval in seconds (default: 60, use \"none\"\u002F\"disabled\" to disable)\nFORGE_HTTP_KEEP_ALIVE_TIMEOUT=10           # Keep-alive timeout in seconds (default: 10)\nFORGE_HTTP_KEEP_ALIVE_WHILE_IDLE=true      # Keep-alive while idle (default: true)\nFORGE_HTTP_ACCEPT_INVALID_CERTS=false      # Accept invalid certificates (default: false) - USE WITH CAUTION\nFORGE_HTTP_ROOT_CERT_PATHS=\u002Fpath\u002Fto\u002Fcert1.pem,\u002Fpath\u002Fto\u002Fcert2.crt  # Paths to root certificate files (PEM, CRT, CER format), multiple paths separated by commas\n```\n\n> **⚠️ Security Warning**: Setting `FORGE_HTTP_ACCEPT_INVALID_CERTS=true` disables SSL\u002FTLS 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.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>API Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nOverride default API endpoints and provider\u002Fmodel settings:\n\n```bash\n# .env\nFORGE_API_URL=https:\u002F\u002Fapi.forgecode.dev  # Custom Forge API URL (default: https:\u002F\u002Fapi.forgecode.dev)\nFORGE_WORKSPACE_SERVER_URL=http:\u002F\u002Flocalhost:8080  # URL for the indexing server (default: https:\u002F\u002Fapi.forgecode.dev\u002F)\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Tool Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nConfiguring the tool calls settings:\n\n```bash\n# .env\nFORGE_TOOL_TIMEOUT=300         # Maximum execution time in seconds for a tool before it is terminated to prevent hanging the session. (default: 300)\nFORGE_MAX_IMAGE_SIZE=10485760  # Maximum image file size in bytes for read_image operations (default: 10485760 - 10 MB)\nFORGE_DUMP_AUTO_OPEN=false     # Automatically open dump files in browser (default: false)\nFORGE_DEBUG_REQUESTS=\u002Fpath\u002Fto\u002Fdebug\u002Frequests.json  # Write debug HTTP request files to specified path (supports absolute and relative paths)\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>ZSH Plugin Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nConfigure the ZSH plugin behavior:\n\n```bash\n# .env\nFORGE_BIN=forge                    # Command to use for forge operations (default: \"forge\")\n```\n\nThe `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\"`.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Display Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nConfigure display options for the Forge UI and ZSH theme:\n\n```bash\n# .env\nFORGE_CURRENCY_SYMBOL=\"$\"         # Currency symbol for cost display in ZSH theme (default: \"$\")\nFORGE_CURRENCY_CONVERSION_RATE=1.0  # Conversion rate for currency display (default: 1.0)\nNERD_FONT=1                       # Enable Nerd Font icons in ZSH theme (default: auto-detected, set to \"1\" or \"true\" to enable, \"0\" or \"false\" to disable)\nUSE_NERD_FONT=1                   # Alternative variable for enabling Nerd Font icons (same behavior as NERD_FONT)\n```\n\nThe `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.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>System Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nSystem-level environment variables (usually set automatically):\n\n```bash\n# .env\nFORGE_CONFIG=\u002Fcustom\u002Fconfig\u002Fdir        # Base directory for all Forge config files (default: ~\u002F.forge)\nFORGE_MAX_SEARCH_RESULT_BYTES=10240   # Maximum bytes for search results (default: 10240 - 10 KB)\nFORGE_HISTORY_FILE=\u002Fpath\u002Fto\u002Fhistory    # Custom path for Forge history file (default: uses system default location)\nFORGE_BANNER=\"Your custom banner text\" # Custom banner text to display on startup (default: Forge ASCII art)\nFORGE_MAX_CONVERSATIONS=100            # Maximum number of conversations to show in list (default: 100)\nFORGE_MAX_LINE_LENGTH=2000             # Maximum characters per line for file read operations (default: 2000)\nFORGE_STDOUT_MAX_LINE_LENGTH=2000      # Maximum characters per line for shell output (default: 2000)\nSHELL=\u002Fbin\u002Fzsh                         # Shell to use for command execution (Unix\u002FLinux\u002FmacOS)\nCOMSPEC=cmd.exe                        # Command processor to use (Windows)\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Semantic Search Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nConfigure semantic search behavior for code understanding:\n\n```bash\n# .env\nFORGE_SEM_SEARCH_LIMIT=200            # Maximum number of results to return from initial vector search (default: 200)\nFORGE_SEM_SEARCH_TOP_K=20             # Top-k parameter for relevance filtering during semantic search (default: 20)\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Logging Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nConfigure logging verbosity and output:\n\n```bash\n# .env\nFORGE_LOG=forge=info                  # Log filter level (default: forge=debug when tracking disabled, forge=info when tracking enabled)\n```\n\nThe `FORGE_LOG` variable controls the logging level for Forge's internal operations using the standard tracing filter syntax. Common values:\n- `forge=error` - Only errors\n- `forge=warn` - Warnings and errors\n- `forge=info` - Informational messages (default when tracking enabled)\n- `forge=debug` - Debug information (default when tracking disabled)\n- `forge=trace` - Detailed tracing\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Tracking Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nControl tracking of user-identifying metadata in telemetry events:\n\n```bash\n# .env\nFORGE_TRACKER=false                   # Disable tracking enrichment metadata (default: true)\n```\n\nThe `FORGE_TRACKER` variable controls whether tracking enrichment metadata is included in telemetry events.\n\n\u003C\u002Fdetails>\n\nThe `forge.yaml` file supports several advanced configuration options that let you customize Forge's behavior.\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Custom Rules\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nAdd your own guidelines that all agents should follow when generating responses.\n\n```yaml\n# forge.yaml\ncustom_rules: |\n  1. Always add comprehensive error handling to any code you write.\n  2. Include unit tests for all new functions.\n  3. Follow our team's naming convention: camelCase for variables, PascalCase for classes.\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Commands\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nDefine custom commands as shortcuts for repetitive prompts:\n\n```yaml\n# forge.yaml\ncommands:\n  - name: \"refactor\"\n    description: \"Refactor selected code\"\n    prompt: \"Please refactor this code to improve readability and performance\"\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Model\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nSpecify the default AI model to use for all agents in the workflow.\n\n```yaml\n# forge.yaml\nmodel: \"claude-3.7-sonnet\"\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Max Walker Depth\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nControl how deeply Forge traverses your project directory structure when gathering context.\n\n```yaml\n# forge.yaml\nmax_walker_depth: 3 # Limit directory traversal to 3 levels deep\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Temperature\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nAdjust 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.\n\n```yaml\n# forge.yaml\ntemperature: 0.7 # Balanced creativity and focus\n```\n\n\u003C\u002Fdetails>\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Tool Max Failure Limit\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nControl 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.\n\n```yaml\n# forge.yaml\nmax_tool_failure_per_turn: 3 # Allow up to 3 failures per tool before forcing completion\n```\n\nSet to a higher value if you want more retry attempts, or lower if you want faster failure detection.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Max Requests Per Turn\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nLimit 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.\n\n```yaml\n# forge.yaml\nmax_requests_per_turn: 50 # Allow up to 50 requests per turn\n```\n\nWhen this limit is reached, Forge will:\n\n- Ask you if you wish to continue\n- If you respond with 'Yes', it will continue the conversation\n- If you respond with 'No', it will end the conversation\n\n\u003C\u002Fdetails>\n\n---\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Model Context Protocol (MCP)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nThe MCP feature allows AI agents to communicate with external tools and services. This implementation follows Anthropic's [Model Context Protocol](https:\u002F\u002Fdocs.anthropic.com\u002Fen\u002Fdocs\u002Fclaude-code\u002Ftutorials#set-up-model-context-protocol-mcp) design.\n\n### MCP Configuration\n\nConfigure MCP servers using the CLI:\n\n```bash\n# List all MCP servers\nforge mcp list\n\n# Import a server from JSON\nforge mcp import\n\n# Show server configuration details\nforge mcp show\n\n# Remove a server\nforge mcp remove\n\n# Reload servers and rebuild caches\nforge mcp reload\n```\n\nOr manually create a `.mcp.json` file with the following structure:\n\n```json\n{\n  \"mcpServers\": {\n    \"server_name\": {\n      \"command\": \"command_to_execute\",\n      \"args\": [\"arg1\", \"arg2\"],\n      \"env\": { \"ENV_VAR\": \"value\" }\n    },\n    \"another_server\": {\n      \"url\": \"http:\u002F\u002Flocalhost:3000\u002Fevents\"\n    }\n  }\n}\n```\n\nMCP configurations are read from two locations (project-local takes precedence):\n\n1. **Project-local:** `.mcp.json` in your project directory\n2. **Global:** `~\u002Fforge\u002F.mcp.json`\n\n### Example Use Cases\n\nMCP can be used for various integrations:\n\n- Web browser automation\n- External API interactions\n- Tool integration\n- Custom service connections\n\n### Usage in Multi-Agent Workflows\n\nMCP 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.\n\n\u003C\u002Fdetails>\n\n---\n\n## Documentation\n\nFor comprehensive documentation on all features and capabilities, please visit the [documentation site](https:\u002F\u002Fgithub.com\u002Ftailcallhq\u002Fforgecode\u002Ftree\u002Fmain\u002Fdocs).\n\n---\n\n## Installation\n\n```bash\n# YOLO\ncurl -fsSL https:\u002F\u002Fforgecode.dev\u002Fcli | sh\n\n# Package managers\nnix run github:tailcallhq\u002Fforgecode # for latest dev branch\n```\n\n---\n\n## Community\n\nJoin our vibrant Discord community to connect with other Forge users and contributors, get help with your projects, share ideas, and provide feedback!\n\n[![Discord](https:\u002F\u002Fimg.shields.io\u002Fdiscord\u002F1044859667798568962?style=for-the-badge&cacheSeconds=120&logo=discord)](https:\u002F\u002Fdiscord.gg\u002FkRZBPpkgwq)\n\n---\n\n## Support Us\n\nYour support drives Forge's continued evolution! By starring our GitHub repository, you:\n\n- Help others discover this powerful tool 🔍\n- Motivate our development team 💪\n- Enable us to prioritize new features 🛠️\n- Strengthen our open-source community 🌱\n","Forge 是一个集成 AI 能力的终端开发环境，支持 Claude、GPT、O 系列、Grok、Deepseek、Gemini 以及 300 多种模型。其核心功能包括交互式模式（TUI）、一次性 CLI 模式和 ZSH 插件模式，能够通过自然语言指令执行代码操作、文件管理及 Git 集成等任务。利用 Rust 编写，确保了高效稳定的运行性能。适用于需要借助 AI 提升编程效率的各种场景，比如日常编码、项目管理和技术文档编写等。",2,"2026-06-11 03:04:10","top_language"]