ForgeCode CLI
A terminal coding agent: a dialogue, a one-off prompt and a zsh plugin, with models from OpenAI, Anthropic and other providers to choose from
- 7,637 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- The agent reads project files, writes patches and runs shell commands, and `forge commit` makes the commit itself
- Provider keys sit in a file on disk, and conversation context goes to the chosen model providers
- `forge setup` changes `.zshrc`, and `:sync` sends file contents to the indexing server
Install
Manual install
curl -fsSL https://forgecode.dev/cli | shOn first run it offers to sign in to a model provider. forge provider login does the sign-in separately.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent reads project files, writes patches and runs shell commands, and `forge commit` makes the commit itself
- Provider keys sit in a file on disk, and conversation context goes to the chosen model providers
- `forge setup` changes `.zshrc`, and `:sync` sends file contents to the indexing server
This is third-party code. Review the repository files before installing.
What it does
ForgeCode is an open-source terminal coding agent that reads project files, writes patches and runs commands. It installs with `curl -fsSL https://forgecode.dev/cli | sh`, offers to sign in to a model provider on first launch, and `forge provider login` does the same separately. Keys are kept in a file, and old environment variables are migrated into that store on first run. There are three ways to work. `forge` with no arguments opens a conversational terminal interface, and `forge -p "task"` runs a single prompt and returns you to the shell; piped input works too. The third way is a zsh plugin: `forge setup` appends it to `.zshrc`, after which lines starting with `:` go to the agent, for example `: rewrite the auth module`. Three agents are built in: `forge` makes edits and runs tests, `sage` only studies code, and `muse` writes plans into a `plans/` folder. There is also `forge commit`, which reads the diff and writes the commit message, `forge suggest` to turn a description into a shell command, file attachments with `@`, and a `--sandbox` mode that creates an isolated git worktree with its own branch. MCP servers connect through `forge mcp` commands or a `.mcp.json` file, and skills live in the project's `.forge/skills/<name>/SKILL.md` folders and in `~/forge/skills/`.
Who it is for. For developers who work in the terminal and want to connect models from different providers to a single agent.
Good fit when
- You want a terminal agent that can be pointed at a model from any supported provider, with the model switchable on the fly
- You want to call the agent straight from a zsh prompt without opening a separate interface
- You want separate agents for separate jobs: one studies code with no edits, one writes a plan, one makes changes
- You want commit messages and shell command suggestions from a model, with the result visible before it runs
- Risky experiments need their own branch and git worktree
Not a fit when
- You do not use zsh: the `:` prefix plugin is built for that shell, and without it you have the `forge` interface and the `-p` mode
- You need code indexing without sending files out: by default `:sync` passes file contents to a ForgeCode server, and a server of your own has to be set up yourself
- You need an agent from Anthropic or GitHub themselves: Claude Code or GitHub Copilot CLI in the catalog are closer
- You need a terminal agent with a desktop version and build and plan modes: OpenCode is closer
Example request
Explain how caching works in this project and change nothingLimitations
The license is Apache-2.0. You need a key or a sign-in at a model provider, and the agent itself includes no paid plans.
- Semantic search through `:sync` sends file contents to `https://api.forgecode.dev`. The address changes with the `FORGE_WORKSPACE_SERVER_URL` variable if you run a server of your own.
- The project description promises a restricted shell mode but does not detail its limits: check them before giving the agent working directories.
- Using `.env` files for provider keys is marked deprecated and will be removed in a future version.
- Some settings commands apply only to the current session while others are saved in `~/forge/.forge.toml`: `:model` changes the model for the session, `:config-model` permanently.
- A tool is limited to 300 seconds of run time by default, and `FORGE_TOOL_TIMEOUT` changes the limit.
How to disable. Remove the plugin lines from `.zshrc` that `forge setup` added and open the shell again. `forge provider logout` signs out of a provider and `forge mcp remove` drops an MCP server. The settings files live in `~/forge/`.
FAQ
How do the forge, sage and muse agents differ?
`forge` implements: it builds features, fixes bugs and runs tests, changing files. `sage` studies architecture and data flow and changes no files. `muse` analyzes structure and writes plans into a `plans/` folder, also leaving the code alone.
How do I attach a file to a request?
Type `@` in the prompt and press Tab for a fuzzy file search. The chosen path is inserted as `@[file name]` and sent to the agent as context.
What does the `--sandbox` mode do?
It creates an isolated git worktree on a separate branch under the name you give and starts the agent there, so the experiment does not touch your main branch.
Where do skills live and in what order do they apply?
Project skills in `.forge/skills/<name>/SKILL.md` come first, then global ones from `~/forge/skills/`, then built-in ones. Three are built in: `create-skill`, `execute-plan` and `github-pr-description`.
How do I set standing rules for the agent?
Put an `AGENTS.md` file in the project root or in `~/forge/`: the agent reads it at the start of every conversation. Your own agents are described by `.md` files with a YAML header in `.forge/agents/`.
How do I connect an MCP server?
With `forge mcp import` or a `.mcp.json` file with an `mcpServers` block. The project file takes priority over the global `~/forge/.mcp.json`.
Discussion
No questions or reviews yet.
Related
CLI toolsA Go coding agent for open models: it turns a chat into tasks on separate branches, checks and merges the result and runs all projects in one window
A skill set for designing, building, auditing and releasing bundle-plugins for Claude Code, Cursor, Codex and other agents
An open coding agent for the terminal, browser and desktop that works with models from OpenAI and Claude to Ollama
One runtime for Claude Code, Codex, OpenCode and more: a run counts as done only when checks the agent did not write pass
A skill with 25 commands to audit and improve the prompts, tools and agent designs of a project in Cursor, Claude Code and Codex
A tmux-based TUI that runs Claude Code, Codex and other agents in one list: status, quick prompts, worktrees and diff review
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| ForgeCode (this entry) | no | 7,637 | |
| OpenCode | no | 222,896 | an open terminal and desktop agent with build and plan modes |
| GitHub Copilot CLI | no | 11,307 | GitHub Copilot's terminal agent with access to repositories, issues and pull requests |
README in short
The English description opens with the install command and a quick start, then shows example tasks: explain code, add a feature, debug an error, review, design a database schema. After that it explains the three ways to work and details the `:` prefix command system for zsh: agents, attachments, conversation management, git helpers, session settings, skills and semantic search. A reference of options and subcommands, provider setup, `forge.yaml`, environment variables and MCP close it out. The repository holds Rust source, the project's own skills and commands in `.forge/` and a dev container configuration.