forgecode

⚒️ Forge: AI-Enhanced Terminal Development Environment

A comprehensive coding agent that integrates AI capabilities with your development environment

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

--- Table of Contents - [Quickstart](#quickstart) - [Usage Examples](#usage-examples) - [Why Forge?](#why-forge) - [How Forge Works: Three Modes](#how-forge-works-three-modes) - [Interactive Mode (TUI)](#interactive-mode-tui) - [One-Shot CLI Mode](#one-shot-cli-mode) - [ZSH Plugin Mode (`:` prefix)](#zsh-plugin-mode--prefix) - [ZSH Plugin: The `:` Prefix System](#zsh-plugin-the--prefix-system) - [Agents](#agents) - [Sending Prompts](#sending-prompts) - [Attaching Files](#attaching-files) - [Conversation Management](#conversation-management) - [Git Integration](#git-integration) - [Shell Command Tools](#shell-command-tools) - [Session & Configuration](#session--configuration) - [Skills](#skills) - [Customizing Agent Behavior](#customizing-agent-behavior) - [Semantic Search (Workspace)](#semantic-search-workspace) - [Quick Reference: All `:` Commands](#quick-reference-all--commands) - [Command-Line Options](#command-line-options) - [Advanced Configuration](#advanced-configuration) - [Provider Configuration](#provider-configuration) - [Managing Provider Credentials](#managing-provider-credentials) - [Deprecated: Environment Variables](#deprecated-environment-variables) - [forge.yaml Configuration Options](#forgeyaml-configuration-options) - [Environment Variables](#environment-variables) - [MCP Configuration](#mcp-configuration) - [Example Use Cases](#example-use-cases) - [Usage in Multi-Agent Workflows](#usage-in-multi-agent-workflows) - [Documentation](#documentation) - [Community](#community) - [Support Us](#support-us) --- ## Quickstart To get started with Forge, run the command below: ```bash curl -fsSL https://forgecode.dev/cli | sh ``` On first run, Forge will guide you through setting up your AI provider credentials using the interactive login flow. Alternatively, you can configure providers beforehand: ```bash # Configure your provider credentials interactively forge provider login # Then start Forge forge ``` That's it! Forge is now ready to assist you with your development tasks. ## Usage Examples Forge can be used in different ways depending on your needs. Here are some common usage patterns: Code Understanding ``` > Can you explain how the authentication system works in this codebase? ``` Forge will analyze your project's structure, identify authentication-related files, and provide a detailed explanation of the authentication flow, including the relationships between different components. Implementing New Features ``` > I need to add a dark mode toggle to our React application. How should I approach this? ``` Forge will suggest the best approach based on your current codebase, explain the steps needed, and even scaffold the necessary components and styles for you. Debugging Assistance ``` > I'm getting this error: "TypeError: Cannot read property 'map' of undefined". What might be causing it? ``` Forge will analyze the error, suggest potential causes based on your code, and propose different solutions to fix the issue. Code Reviews ``` > Please review the code in src/components/UserProfile.js and suggest improvements ``` Forge will analyze the code, identify potential issues, and suggest improvements for readability, performance, security, and maintainability. Learning New Technologies ``` > I want to integrate GraphQL into this Express application. Can you explain how to get started? ``` Forge will provide a tailored tutorial on integrating GraphQL with Express, using your specific project structure as context. Database Schema Design ``` > I need to design a database schema for a blog with users, posts, comments, and categories ``` Forge will suggest an appropriate schema design, including tables/collections, relationships, indexes, and constraints based on your project's existing database technology. Refactoring Legacy Code ``` > Help me refactor this class-based component to use React Hooks ``` Forge can help modernize your codebase by walking you through refactoring steps and implementing them with your approval. Git Operations ``` > I need to merge branch 'feature/user-profile' into main but there are conflicts ``` Forge can guide you through resolving git conflicts, explaining the differences and suggesting the best way to reconcile them. ## Why Forge? Forge is designed for developers who want to enhance their workflow with AI assistance while maintaining full control over their development environment. - **Zero configuration** - Just add your API key and you're ready to go - **Seamless integration** - Works right in your terminal, where you already work - **Multi-provider support** - Use OpenAI, Anthropic, or other LLM providers - **Secure by design** - Restricted shell mode limits file system access and prevents unintended changes - **Open-source** - Transparent, extensible, and community-driven Forge helps you code faster, solve complex problems, and learn new technologies without leaving your terminal. --- ## How Forge Works: Three Modes Forge has three distinct ways to use it. Understanding this distinction upfront will save you confusion. ### Interactive Mode (TUI) Running `forge` with no arguments starts the interactive terminal UI, a persistent session where you type prompts and the AI responds in a conversational loop. This is the primary way to do multi-step work. ```bash forge # Start a new interactive session forge conversation resume # Resume a specific saved conversation in interactive mode forge --conversation-id # Same: resume conversation by ID forge --agent # Start interactive session with a specific agent forge -C /path/to/project # Start in a specific directory forge --sandbox experiment-name # Create an isolated git worktree + branch, then start there ``` Once inside interactive mode, type your prompt and press Enter. Forge reads files, writes patches, runs commands, and maintains context across the whole session. ### One-Shot CLI Mode Pass `-p` (or `--prompt`) to run a single prompt and exit. Forge does the work and returns to your shell. Useful for scripts, piping output, or quick tasks. ```bash forge -p "Explain the purpose of src/main.rs" forge -p "Add error handling to the parse() function in lib.rs" echo "What does this do?" | forge # Pipe input as the prompt forge commit # Generate an AI commit message and commit (exits when done) forge commit --preview # Generate commit message, print it, then exit forge suggest "find large log files" # Translate natural language to a shell command, then exit ``` > **Note:** `forge conversation resume ` opens the interactive TUI. It does **not** just print a message and exit. If you run it and see the cursor waiting, you are inside the interactive session. Type your prompt or press `Ctrl+C` to exit. ### ZSH Plugin Mode (`:` prefix) Install the ZSH plugin once with `forge setup`, then use `:` commands directly at your shell prompt without ever typing `forge`. This is the fastest mode for day-to-day development: send prompts, switch conversations, commit, and suggest commands without leaving your shell. ```zsh : refactor the auth module # Send a prompt to the active agent :commit # AI-powered git commit :suggest "find large log files" # Translate description → shell command in your buffer :conversation # Browse saved conversations with interactive picker ``` See the full [ZSH Plugin reference below](#zsh-plugin-the--prefix-system) for all commands and aliases. --- ## ZSH Plugin: The `:` Prefix System When you install the ZSH plugin (`forge setup`), you get a `:` prefix command system at your shell prompt. This is the fastest way to use Forge during normal development; you never leave your shell. **How it works:** Lines starting with `:` are intercepted before the shell sees them and routed to Forge. Everything else runs normally. ```zsh : # Send a prompt to the active agent :sage # Send a prompt to a specific agent by name (sage, muse, forge, or any custom agent) :agent # Switch the active agent; opens interactive picker if no name given ``` ### Agents Forge ships with three built-in agents, each with a different role: | Agent | Alias | Purpose | Modifies files? | |---|---|---|---| | `forge` | (default) | Implementation: builds features, fixes bugs, and runs tests | Yes | | `sage` | `:ask` | Research: maps architecture, traces data flow, and reads code | No | | `muse` | `:plan` | Planning: analyzes structure and writes implementation plans to `plans/` | No | ### Sending Prompts ```zsh : refactor the auth module to use the new middleware :sage how does the caching layer work? # sage = read-only research agent :muse design a deployment strategy # muse = planning agent (writes to plans/) :ask how does X work? # alias for :sage :plan create a migration plan # alias for :muse ``` The agent context persists. Typing `:sage` alone (no prompt text) switches the active agent to sage for all subsequent `: ` commands. ### Attaching Files Type `@` in a prompt, then press Tab to fuzzy-search and select files. The path is inserted as `@[filename]` and attached as context to the AI. ```zsh : review this code @[src/auth.rs] @[tests/auth_test.rs] ``` ### Conversation Management Forge saves every conversation. You can switch between them like switching directories. ``` … ``` ### Git Integration ```zsh :commit # AI reads your diff, writes a commit message, and commits immediately :commit # Same, but pass extra context: :commit fix typo in readme :commit-preview # AI generates the message and puts "git commit -m '...'" in your buffer # so you can review/edit the message before pressing Enter ``` ### Shell Command Tools ```zsh :suggest # Translate natural language to a shell command and put it in your buffer :edit # Open $EDITOR to compose a complex multi-line prompt, then send it ``` ### Session & Configuration Some commands change settings for the current session only. Others persist to your config file (`~/forge/.forge.toml`). The distinction matters: ``` … ``` ### Skills Skills are reusable workflows the AI can invoke as tools. Forge ships three built-in skills: - **`create-skill`**: scaffold a new custom skill - **`execute-plan`**: execute a plan file from `plans/` - **`github-pr-description`**: generate a PR description from your diff Use `:skill` to list available skills. The AI invokes them automatically when relevant, or you can ask explicitly: `: generate a PR description using the github-pr-description skill`. **Custom skills** live in `SKILL.md` files with YAML front-matter. Precedence (highest first): | Location | Path | Scope | |---|---|---| | Project-local | `.forge/skills//SKILL.md` | This project only | | Global | `~/forge/skills//SKILL.md` | All projects | | Built-in | Embedded in binary | Always