diff --git a/README.md b/README.md index 01100087ad..4e98e38c4c 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,311 @@ 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 | +| `:conversation-rename` | | Rename conversation (fzf picker) | +| `: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 +836,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"`. @@ -731,17 +1037,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: @@ -761,10 +1067,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