Forgecode

At a Glance:

Forge is an AI-enhanced terminal development environment that provides a coding agent in three modes, ships with three built-in agents (forge, sage, muse) covering implementation, research, and planning, and integrates with a user's shell via its : prefix ZSH plugin.

Overview:

Forge is a terminal-native coding agent designed to integrate AI capabilities into a developer's existing command-line workflow. It implements three distinct interaction modes: an interactive terminal UI for multi-step work, a one-shot CLI for scripted tasks, and a ZSH plugin that intercepts commands prefixed with :. Forge ships with three built-in agents that have different roles and access levels—forge for file-modifying implementation tasks, sage for read-only research and code understanding, and muse for writing implementation plans. The tool reads project files, writes patches, and runs commands across a persistent session. Users can customize agent behavior through AGENTS.md files and extend functionality with custom agents, commands, and skills. Forge supports multiple AI providers, including OpenAI, Anthropic, and self-hosted options.

Key Decision Points:

• Primary environment is the terminal: All interactions occur through a TUI, CLI one-shots, or the : prefix ZSH plugin; this is not an IDE plugin.

• Role-separated agents: Forge ships three agents with distinct, hard-coded capabilities—forge can modify files while sage and muse are read-only and focused on research and planning respectively.

• Customization model: Persistent instructions, custom agents, and reusable skills are defined through markdown and YAML files placed in project or global directories.

• Conversation persistence: Every conversation is saved, allowing users to switch between, clone, resume, and export sessions as JSON.

• Semantic search requires indexing: The :sync command sends codebase content to a workspace server to enable semantic search; a default hosted endpoint is used unless self-hosted.

Core Features:

• Three interaction modes: Interactive TUI for persistent sessions, one-shot CLI with the -p flag for scripted use, and a shell-integrated ZSH plugin that handles : prefixed commands.

• Three built-in agents: forge (implementation, modifies files), sage (code research and tracing, read-only), and muse (planning, writes to plans/ directory).

• File attachment with fuzzy search: Typing @ in a prompt and pressing Tab allows fuzzy-matching file paths to attach as context.

• Git-integrated workflows: Includes immediate and preview AI-generated commits, plus the ability to create isolated git worktrees via the --sandbox flag.

• MCP support: Can be configured to communicate with external tools and services through Anthropic's Model Context Protocol by defining servers in a .mcp.json file.

• Skills system: Includes built-in skills for creating new skills, executing plan files, and generating PR descriptions, with support for custom, user-defined skills.

Use Cases:

• Developers needing multi-step AI assistance in the terminal: The interactive TUI allows a single session to span research, implementation, and debugging across multiple files and commands.

• Shell-heavy developers wanting inline AI access: The ZSH plugin processes : prefixed commands directly, supporting fast context switching, git commits, and command suggestions without a separate application.

• Refactoring or code understanding sessions: A developer can use the sage agent to trace data flow and map architecture, then switch to the forge agent to implement changes within the same conversation context.

• Scripted development workflows: The one-shot CLI mode enables using AI prompts inside shell scripts or as part of a pipeline, returning control to the shell after a single response.

Open-Source Alternative Value:

Forge provides a terminal-centric AI coding agent with a clear separation of agent roles, persistent session management, and direct shell integration through a ZSH plugin. Its multi-provider architecture and MCP support mean users can configure it against OpenAI and Anthropic models, and its skills and custom agents can be defined through filesystem-based config files (SKILL.md, AGENTS.md, custom agent markdown). The tool saves conversations locally as JSON and supports self-hosting the semantic search workspace server for teams that want control over their code indexing data.