From 92696933a66faf286eafea2f19cf67453adf73e0 Mon Sep 17 00:00:00 2001 From: Andrew Hundt Date: Mon, 6 Apr 2026 03:34:14 -0400 Subject: [PATCH 1/2] docs(README): add newcomer orientation, ZSH plugin reference, and sync CLI docs Adds onboarding context and documents the ZSH plugin system, which was not covered in the README. Also updates the CLI reference to match the current binary and clarifies a few configuration details. What's added: - "How Forge Works: Three Modes" section orienting newcomers to the three distinct usage patterns: Interactive TUI, One-Shot CLI (-p), and ZSH Plugin. Includes a note that `forge conversation resume ` opens the interactive TUI (not a one-shot command), which is a common point of confusion. - "ZSH Plugin: The `:` Prefix System" section with full coverage of agents (forge/sage/muse, aliases :ask/:plan), prompt sending, file attachment via @ + Tab, conversation management (:new, :conversation, :clone, :rename, :retry, :copy, :dump, :compact), git integration (:commit, :commit-preview), shell tools (:suggest, :edit), session-only vs persistent config options, skills (built-in and custom), AGENTS.md, custom agents/commands, semantic search/workspace, and a quick-reference table of all : commands. - "Subcommands" section listing all forge subcommands by category. What's updated: - Command-Line Options table: reflects current flags (--conversation-id, --agent, -C/--directory, --sandbox); removes flags not present in the current CLI (-c, -w, -r). - MCP section: replaces commands from an earlier version (add, add-json, get) with the current subcommands (import, show, remove, reload); makes config paths explicit (./.mcp.json for project-local, ~/forge/.mcp.json for global). - ZSH plugin env var comment: corrected from # prefix to : prefix. - Global config path: corrected from ~/.forge/.forge.toml to ~/forge/.forge.toml (source: crates/forge_infra/src/env.rs line 27-29, h.join("forge")). - Three minor grammar fixes (missing comma, pronoun clarity, sentence structure). --- README.md | 348 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 326 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 34ac0483aa..6077d06a45 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,22 @@ - [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) @@ -159,21 +175,309 @@ Forge is designed for developers who want to enhance their workflow with AI assi 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 fzf preview +``` + +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 fzf 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. + +```zsh +:new # Start a fresh conversation (saves current for :conversation -) +:new # Start a new conversation and immediately send a prompt +:conversation # Open fzf picker: browse and switch conversations with preview +:conversation # Switch directly to a conversation by ID +:conversation - # Toggle between current and previous conversation (like cd -) +:clone # Branch the current conversation (try a different direction) +:clone # Clone a specific conversation by ID +:rename # Rename the current conversation +:conversation-rename # Rename a conversation via fzf picker +:retry # Retry the last prompt (useful if the AI misunderstood) +:copy # Copy the last AI response to clipboard as markdown +:dump # Export conversation as JSON +:dump html # Export conversation as formatted HTML +:compact # Manually compact context to free up token budget +``` + +### Git Integration + +```zsh +:commit # AI reads your diff, writes a commit message, and commits immediately +:commit # 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: + +```zsh +# Session-only (reset when you close the terminal; not saved to config) +:model # Change model for this session only +:reasoning-effort # Set reasoning effort: none/minimal/low/medium/high/xhigh/max +:agent # Switch active agent for this session + +# Persistent (saved to config file) +:config-model # Set default model globally (alias: :cm) +:config-provider # Switch provider globally (alias: :provider, :p) +:config-reasoning-effort # Set default reasoning effort globally (alias: :cre) +:config-commit-model # Set model used for :commit (alias: :ccm) +:config-suggest-model # Set model used for :suggest (alias: :csm) +:config-reload # Reset session overrides back to global config (alias: :cr) + +# View & edit config +:info # Show current session info (model, agent, conversation ID) +:env # Show environment and provider info +:config # List current configuration values +:config-edit # Open config file in $EDITOR (alias: :ce) +:tools # List available tools for the current agent +:skill # List available skills +``` + +### Skills + +Skills are reusable workflows the AI can invoke as tools. Forge ships three built-in skills: + +- **`create-skill`**: scaffold a new custom skill +- **`execute-plan`**: execute a plan file from `plans/` +- **`github-pr-description`**: generate a PR description from your diff + +Use `:skill` to list available skills. The AI invokes them automatically when relevant, or you can ask explicitly: `: generate a PR description using the github-pr-description skill`. + +**Custom skills** live in `SKILL.md` files with YAML front-matter. Precedence (highest first): + +| Location | Path | Scope | +|---|---|---| +| Project-local | `.forge/skills//SKILL.md` | This project only | +| Global | `~/forge/skills//SKILL.md` | All projects | +| Built-in | Embedded in binary | Always available | + +Project-local skills override global ones, which override built-in ones. To scaffold a new skill, ask: `: create a new skill`. + +### Customizing Agent Behavior + +**`AGENTS.md`:** Create this file in your project root (or `~/forge/AGENTS.md` globally) to give all agents persistent instructions such as coding conventions, commit message style, and things to avoid. Forge reads it automatically at the start of every conversation. + +**Custom agents:** Place a `.md` file with YAML front-matter in `.forge/agents/` (project) or `~/forge/agents/` (global) to define additional agents with their own models, tools, and system prompts. Project-local agents override global ones. The built-in agent files in `crates/forge_repo/src/agents/` are good examples of the format. + +**Custom commands:** Place YAML files in `.forge/commands/` (project) or `~/forge/commands/` (global) to define shortcut commands available via `:commandname`. Commands can also be defined inline in `forge.yaml` under the `commands:` key. + +### Semantic Search (Workspace) + +```zsh +:sync # Index your codebase for semantic search +:workspace-init # Initialize workspace for indexing +:workspace-status # Show indexing status +:workspace-info # Show workspace details +``` + +After running `:sync`, the AI can search your codebase by meaning rather than exact text matches. Indexing sends file content to the workspace server, which defaults to `https://api.forgecode.dev`. Set `FORGE_WORKSPACE_SERVER_URL` to override this if self-hosting. + +### Quick Reference: All `:` Commands + +| Command | Alias | What it does | +|---|---|---| +| `: ` | | Send prompt to active agent | +| `:new` | `:n` | Start new conversation | +| `:conversation` | `:c` | Browse/switch conversations (fzf) | +| `:conversation -` | | Toggle to previous conversation | +| `:clone` | | Branch current conversation | +| `:rename ` | `:rn` | Rename current conversation | +| `:retry` | `:r` | Retry last prompt | +| `:copy` | | Copy last response to clipboard | +| `:dump` | `:d` | Export conversation as JSON | +| `:compact` | | Compact context | +| `:commit` | | AI commit (immediate) | +| `:commit-preview` | | AI commit (review first) | +| `:suggest ` | `:s` | Translate natural language to command | +| `:edit` | `:ed` | Compose prompt in $EDITOR | +| `:sage ` | `:ask` | Q&A / code understanding agent | +| `:muse ` | `:plan` | Planning agent | +| `:agent ` | `:a` | Switch active agent (fzf picker if no name given) | +| `:model ` | `:m` | Set model for this session only | +| `:config-model ` | `:cm` | Set default model (persistent) | +| `:reasoning-effort ` | `:re` | Set reasoning effort for session | +| `:config-reload` | `:cr` | Reset session overrides to global config | +| `:info` | `:i` | Show session info | +| `:sync` | `:workspace-sync` | Index codebase for semantic search | +| `:tools` | `:t` | List available tools | +| `:skill` | | List available skills | +| `:login` | `:provider-login` | Login to a provider | +| `:logout` | | Logout from a provider | +| `:keyboard-shortcuts` | `:kb` | Show keyboard shortcuts | +| `:doctor` | | Run shell environment diagnostics | + +--- + ## Command-Line Options Here's a quick reference of Forge's command-line options: -| Option | Description | -| ------------------------------- | ---------------------------------------------------------- | -| `-p, --prompt ` | Direct prompt to process without entering interactive mode | -| `-c, --command ` | Path to a file containing initial commands to execute | -| `-w, --workflow ` | Path to a file containing the workflow to execute | -| `-e, --event ` | Dispatch an event to the workflow | -| `--conversation ` | Path to a file containing the conversation to execute | -| `-r, --restricted` | Enable restricted shell mode for enhanced security | -| `--verbose` | Enable verbose output mode | -| `-h, --help` | Print help information | -| `-V, --version` | Print version | +| Option | Description | +| ----------------------------------- | ------------------------------------------------------------------------ | +| `-p, --prompt ` | Direct prompt to process without entering interactive mode | +| `-e, --event ` | Dispatch an event to the workflow in JSON format | +| `--conversation ` | Path to a JSON file containing the conversation to execute | +| `--conversation-id ` | Resume or continue an existing conversation by ID | +| `--agent ` | Agent ID to use for this session | +| `-C, --directory ` | Change to this directory before starting | +| `--sandbox ` | Create an isolated git worktree + branch for safe experimentation | +| `--verbose` | Enable verbose logging output | +| `-h, --help` | Print help information | +| `-V, --version` | Print version | + +### Subcommands + +```bash +# Conversations +forge conversation list # List all saved conversations +forge conversation resume # Resume a conversation in interactive mode +forge conversation new # Create a new conversation ID (prints it) +forge conversation dump # Export conversation as JSON +forge conversation compact # Compact conversation context +forge conversation retry # Retry last message +forge conversation clone # Clone a conversation +forge conversation rename # Rename a conversation +forge conversation delete # Delete a conversation permanently +forge conversation info # Show conversation details +forge conversation stats # Show token usage statistics +forge conversation show # Show last assistant message + +# Commits +forge commit # Generate AI commit message and commit +forge commit --preview # Generate commit message only (prints it) +forge commit fix the auth bug # Pass extra context for the commit message + +# Shell command suggestion +forge suggest "list files by size" # Translate description to a shell command + +# Providers +forge provider login # Add or update provider credentials (interactive) +forge provider logout # Remove provider credentials +forge list provider # List supported providers + +# Models & agents +forge list model # List available models +forge list agent # List available agents + +# Workspace / semantic search +forge workspace sync # Index current directory for semantic search +forge workspace init # Initialize workspace +forge workspace status # Show indexing status +forge workspace query # Query the semantic index + +# MCP servers +forge mcp list # List configured MCP servers +forge mcp import # Add a server from JSON +forge mcp show # Show server configuration +forge mcp remove # Remove a server +forge mcp reload # Reload all servers and rebuild caches + +# Other +forge info # Show config, active model, environment +forge list tool --agent # List tools for a specific agent +forge doctor # Run shell environment diagnostics +forge update # Update forge to the latest version +forge setup # Install ZSH plugin (updates .zshrc) +``` ## Advanced Configuration @@ -530,7 +834,7 @@ Configure the ZSH plugin behavior: FORGE_BIN=forge # Command to use for forge operations (default: "forge") ``` -The `FORGE_BIN` environment variable allows you to customize the command used by the ZSH plugin when transforming `#` prefixed commands. If not set, it defaults to `"forge"`. +The `FORGE_BIN` environment variable allows you to customize the command used by the ZSH plugin when transforming `:` prefixed commands. If not set, it defaults to `"forge"`. @@ -730,17 +1034,17 @@ Configure MCP servers using the CLI: # List all MCP servers forge mcp list -# Add a new server -forge mcp add +# Import a server from JSON +forge mcp import -# Add a server using JSON format -forge mcp add-json - -# Get server details -forge mcp get +# Show server configuration details +forge mcp show # Remove a server forge mcp remove + +# Reload servers and rebuild caches +forge mcp reload ``` Or manually create a `.mcp.json` file with the following structure: @@ -760,10 +1064,10 @@ Or manually create a `.mcp.json` file with the following structure: } ``` -MCP configurations are read from two locations (in order of precedence): +MCP configurations are read from two locations (project-local takes precedence): -1. Local configuration (project-specific) -2. User configuration (user-specific) +1. **Project-local:** `.mcp.json` in your project directory +2. **Global:** `~/forge/.mcp.json` ### Example Use Cases From b9f77ef64e32c7c0879e5926c7f03e35bb0661ac Mon Sep 17 00:00:00 2001 From: Tushar Mathur Date: Mon, 6 Apr 2026 20:19:15 +0530 Subject: [PATCH 2/2] Update README.md Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com> --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 6077d06a45..82c97d77af 100644 --- a/README.md +++ b/README.md @@ -373,6 +373,7 @@ After running `:sync`, the AI can search your codebase by meaning rather than ex ### Quick Reference: All `:` Commands + | Command | Alias | What it does | |---|---|---| | `: ` | | Send prompt to active agent | @@ -381,6 +382,7 @@ After running `:sync`, the AI can search your codebase by meaning rather than ex | `:conversation -` | | Toggle to previous conversation | | `:clone` | | Branch current conversation | | `:rename ` | `:rn` | Rename current conversation | +| `:conversation-rename` | | Rename conversation (fzf picker) | | `:retry` | `:r` | Retry last prompt | | `:copy` | | Copy last response to clipboard | | `:dump` | `:d` | Export conversation as JSON |