⚒️ 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

Quickstart

To get started with Forge, run the command below:

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:

# 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:

> Can you explain how the authentication system works in this codebase?

> I need to add a dark mode toggle to our React application. How should I approach this?

> I'm getting this error: "TypeError: Cannot read property 'map' of undefined". What might be causing it?

> Please review the code in src/components/UserProfile.js and suggest improvements

> I want to integrate GraphQL into this Express application. Can you explain how to get started?

> I need to design a database schema for a blog with users, posts, comments, and categories

> Help me refactor this class-based component to use React Hooks

> I need to merge branch 'feature/user-profile' into main but there are conflicts

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.

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 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.

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 <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 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.

: 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 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.

: <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 given

Agents

Forge ships with three built-in agents, each with a different role:

Sending Prompts

: 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 : <prompt> 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/