A comprehensive coding agent that integrates AI capabilities with your development environment
curl -fsSL https://forgecode.dev/cli | sh
Table of Contents
To get started with Forge, run the command below:
curl -fsSL https://forgecode.dev/cli | shOn first run, Forge will guide you through setting up your AI provider credentials using the interactive login flow. Alternatively, you can configure providers beforehand:
# Configure your provider credentials interactively
forge provider login
# Then start Forge
forgeThat's it! Forge is now ready to assist you with your development tasks.
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.
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.
Forge has three distinct ways to use it. Understanding this distinction upfront will save you confusion.
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.
forge # Start a new interactive session
forge conversation resume <id> # Resume a specific saved conversation in interactive mode
forge --conversation-id <id> # Same: resume conversation by ID
forge --agent <agent-id> # 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 thereOnce inside interactive mode, type your prompt and press Enter. Forge reads files, writes patches, runs commands, and maintains context across the whole session.
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.
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 exitNote:
forge conversation resume <id>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 pressCtrl+Cto exit.
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.
: 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 pickerSee the full ZSH Plugin reference below for all commands and aliases.
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.
: <prompt> # Send a prompt to the active agent
:sage <prompt> # Send a prompt to a specific agent by name (sage, muse, forge, or any custom agent)
:agent <name> # Switch the active agent; opens interactive picker if no name givenForge 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 |
: 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 :museThe agent context persists. Typing :sage alone (no prompt text) switches the active agent to sage for all subsequent : <prompt> commands.
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.
: review this code @[src/auth.rs] @[tests/auth_test.rs]Forge saves every conversation. You can switch between them like switching directories.
:new # Start a fresh conversation (saves current for :conversation -)
:new <initial prompt> # Start a new conversation and immediately send a prompt
:conversation # Open interactive picker: browse and switch conversations with preview
:conversation <id> # 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 <id> # Clone a specific conversation by ID
:rename <name> # Rename the current conversation
:conversation-rename # Rename a conversation via interactive 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:commit # AI reads your diff, writes a commit message, and commits immediately
:commit <context> # 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:suggest <description> # 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 itSome commands change settings for the current session only. Others persist to your config file (~/forge/.forge.toml). The distinction matters:
# Session-only (reset when you close the terminal; not saved to config)
:model <model-id> # Change model for this session only
:reasoning-effort <level> # Set reasoning effort: none/minimal/low/medium/high/xhigh/max
:agent <id> # Switch active agent for this session
# Persistent (saved to config file)
:config-model <model-id> # Set default model globally (alias: :cm)
:config-provider # Switch provider globally (alias: :provider, :p)
:config-reasoning-effort <lvl> # Set default reasoning effort globally (alias: :cre)
:config-commit-model <id> # Set model used for :commit (alias: :ccm)
:config-suggest-model <id> # 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)
:config # Display effective resolved configuration in TOML format
:config-edit # Open config file in $EDITOR (alias: :ce)
:tools # List available tools for the current agent
:skill # List available skillsSkills are reusable workflows the AI can invoke as tools. Forge ships three built-in skills:
create-skill: scaffold a new custom skillexecute-plan: execute a plan file fromplans/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/<name>/SKILL.md |
This project only |
| Global | ~/forge/skills/<name>/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.
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.
:sync # Index your codebase for semantic search
:workspace-init # Initialize workspace for indexing
:workspace-status # Show indexing status
:workspace-info # Show workspace detailsAfter 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.
| Command | Alias | What it does |
|---|---|---|
: <prompt> |
Send prompt to active agent | |
:new |
:n |
Start new conversation |
:conversation |
:c |
Browse/switch conversations (interactive picker) |
:conversation - |
Toggle to previous conversation | |
:clone |
Branch current conversation | |
:rename <name> |
:rn |
Rename current conversation |
:conversation-rename |
Rename conversation (interactive 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 <desc> |
:s |
Translate natural language to command |
:edit |
:ed |
Compose prompt in $EDITOR |
:sage <prompt> |
:ask |
Q&A / code understanding agent |
:muse <prompt> |
:plan |
Planning agent |
:agent <name> |
:a |
Switch active agent (interactive picker if no name given) |
:model <id> |
:m |
Set model for this session only |
:config-model <id> |
:cm |
Set default model (persistent) |
:reasoning-effort <lvl> |
: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 |
Here's a quick reference of Forge's command-line options:
| Option | Description |
|---|---|
-p, --prompt <PROMPT> |
Direct prompt to process without entering interactive mode |
-e, --event <EVENT> |
Dispatch an event to the workflow in JSON format |
--conversation <CONVERSATION> |
Path to a JSON file containing the conversation to execute |
--conversation-id <ID> |
Resume or continue an existing conversation by ID |
--agent <AGENT> |
Agent ID to use for this session |
-C, --directory <DIR> |
Change to this directory before starting |
--sandbox <NAME> |
Create an isolated git worktree + branch for safe experimentation |
--verbose |
Enable verbose logging output |
-h, --help |
Print help information |
-V, --version |
Print version |