Forge 3.0

Forge is an interactive coding agent for local Git repositories. It combines a Claude Code-style terminal workflow with Docker isolation, durable multi-turn sessions, visible public activity, one-shot approvals, resumable history, and structured context compaction. Each turn also carries a durable task contract, separates verified evidence from model hypotheses, and can use bounded user-controlled long-term memory.

Forge shows what it is doing—direction, tool activity, policy decisions, tests, retries, pauses, and compactions—but never displays or stores private chain-of-thought. Changes remain in a Forge-owned Git worktree. Forge does not apply, commit, push, or open a pull request automatically.

Read the architecture and security boundary before using Forge on an important repository.

Requirements

• Windows 10/11 with CMD, PowerShell, or Windows Terminal.

• Python 3.12 or 3.13.

• uv.

• Git.

• Docker Desktop with the Linux container engine.

• An API key and OpenAI-compatible base URL for the chosen model.

Docker Desktop is a prerequisite; Forge does not install or upgrade it. Forge starts Docker Desktop when necessary, reuses a responsive engine, and leaves it running after exit.

Related MCP server: mcp-dev-tools

Quick start

1. Clone and install the global command

git clone <repository-url>
cd forge
uv tool install .

If CMD cannot find forge, add uv's tool directory to PATH:

uv tool update-shell

Close and reopen CMD after uv tool update-shell, then verify the installed command from a directory outside the Forge checkout:

forge --help

Reinstall a changed checkout with uv tool install . --force. Development contributors can instead use uv sync --locked --all-groups and uv run forge --help.

2. Let Forge create the v2 JSON configuration

Open CMD in a Git repository root and enter forge once. If the configuration does not exist, Forge creates a template before starting Docker or contacting a model, shows its exact path, and pauses startup. It never overwrites an existing configuration.

Edit the generated file at:

• Windows: C:\Users\<username>\.forge\config.json

• Cross-platform form: ~/.forge/config.json

The generated template has this shape; replace the empty base_url, model, and api_key values:

{
  "schema_version": 2,
  "active_model": "primary",
  "models": {
    "primary": {
      "provider": "openai",
      "base_url": "",
      "model": "",
      "api_key": "",
      "context_window": 128000,
      "streaming": true
    }
  }
}

provider, base_url, model, and api_key must be non-empty. active_model must name one entry in models. Add more named entries when needed and change only active_model to select the default.

provider: "openai" selects the OpenAI-compatible request protocol; it does not claim that the configured model was created by OpenAI. The profile name, model name, and base URL together identify the configured runtime.

The API key is intentionally stored as plaintext in this local file. Forge applies owner-only permissions where the host supports them, but local plaintext storage remains a user-accepted risk. Protect the file with the Windows account and disk controls appropriate for your machine. Forge never places the key in session snapshots, UI output, logs, traces, exports, tool results, or Docker environment variables.

Forge 3.0 does not read, modify, or migrate the v1 TOML profile automatically.

3. Open a repository

After saving the generated configuration, enter:

forge

Forge uses the current directory, validates local configuration without making a model request, checks Docker, starts Docker Desktop if required, builds the exact forge-runner:3.0.1 image when missing or carrying an incompatible runner-version label, creates an isolated worktree, and then enables the conversation input.

To review a different repository:

forge <repository-path>

Before the first task, /repo <repository-path> can replace the selected repository and its fresh isolated worktree.

Primary commands

Local diagnostics never contact the provider:

forge doctor
forge doctor --all
forge doctor --profile primary

A live provider request occurs only when explicitly requested:

forge doctor --profile primary --probe

Terminal interaction

The ready screen initially displays the Forge name, fixed session model, repository, and status without a conversation scrollbar. On the first submitted instruction, scrolling is enabled and the transcript is positioned at the top of the conversation viewport. The title page remains immediately above the first message in scrollback and can be recovered with the mouse wheel. Static interface text is Chinese by default; assistant answers follow the language used in the instruction unless the user requests another language.

• Enter: submit the instruction.

• Shift+Enter: insert a newline.

• Ctrl+K: show or hide the command table; Esc closes it.

• Ctrl+O: show or hide the entire detailed activity history.

• Mouse wheel: scroll the transcript or expanded activities.

• First Ctrl+C while running or in a modal: request a durable safe pause.

• Second Ctrl+C within two seconds: exit.

• First Ctrl+C in READY: clear non-empty input; with empty input, arm exit.

• Arrow keys + Enter: choose clarification, approval, history, or cleanup options.

The command table describes available slash commands and shortcuts. The compact footer remains visible in this order: Ctrl+K 展开命令 · Ctrl+O 展开活动 · Ctrl+C 暂停/退出 · 用时. The Shift+Enter newline hint is intentionally omitted from the footer.

Tool details are collapsed by default. Expanded activity contains only user-safe arguments, affected paths, status, and result summaries. It does not contain hidden prompts or private model reasoning.

Risky operations pause behind exactly three choices:

1. 仅本次批准

2. 拒绝该操作

3. 告诉 Agent 应该怎么做

Approval is tied to the displayed invocation, command, arguments, and paths. It is consumed once. Rejection or redirection invalidates that operation.

Sessions, history, and context

One open Forge window is one conversation. Each submitted instruction creates a new bounded turn. Transcript, model snapshot, worktree, and context continue across turns; model/tool/time budgets reset per turn.

Forge Code reports runtime identity from that fixed, non-secret session snapshot. Every question, including 你是什么模型 and Who are you?, is sent to the configured model as a normal durable turn. Before each request, Forge adds Forge Code and the model name from the session snapshot as internal identity grounding so the model does not infer its identity from filenames or provider implementations found inside the reviewed repository. Identity-only questions still call the configured model, but Forge does not expose any tools to that model turn. The model chooses the answer's wording, length, paragraphs, headings, and lists without a one-sentence or template restriction. Forge buffers the answer until the model completes only so configuration-detail lines and unexpected tool calls can be removed before display; all other formatting is preserved. The identity prompt asks the model to follow the user's language and correct false-vendor premises naturally. The internal identity context exists only at the live model-request boundary; it is not stored in the session contract, checkpoint, trace, or inspection output.

Plain forge always creates a new session. It never resumes recent history implicitly. forge resume lists all retained sessions:

• closing a fresh window before submitting any instruction discards its empty session record and isolated worktree;

• every compatible retained session resumes in place with its original ID and worktree;

• reopening a normally closed session creates neither a child session nor a summary;

• a changed or missing model configuration tells the user to restore the original model configuration before resuming.

Near 80% of the usable model context during an active conversation, Forge replaces older active prompt history with a cumulative structured summary while retaining raw history in storage. Exiting and reopening a session never initiates compaction. The summary preserves goals, latest intent, decisions, code locations, provenance-bearing verified evidence, unverified working hypotheses, failed approaches, diff, tests, pending work, interactions, safety/budget state, artifacts, and recent messages.

Conversation commands:

• /repo <path>: change repository before the first turn.

• /diff: inspect the current isolated worktree patch.

• /export: write a redacted report, trace, and patch.

• /compact: compact context now.

• /compact <focus>: compact with an explicit focus.

• /context: show usage, whether it is estimated, compaction count, and latest compaction time.

• /memory: list project long-term rules and exemptions and their state.

• @agent remember: <text>: add a project suggestion rule.

• @agent remember: 豁免文件 <path> 的<reason>: add a file exemption.

• @agent forget <id>: remove an incorrect rule or exemption.

• /memory add global|repo <text>: compatibility syntax that now adds a project suggestion rule.

• /memory disable <id> / /memory enable <id>: change whether an entry is injected.

• /memory remove <id>: delete an entry.

Completed review summaries are retained automatically. When the next user message supplies feedback on that review, Forge makes one tool-free, strict-JSON model request and merges only validated rule, exemption, and architecture-note candidates. Every write is audited by updated_by, guarded by a file lock, and written through an atomic replacement. Entries are selected from the current task's file scope and injected under a hard prompt budget. Credential-like content, private server locations, and private keys are rejected before persistence.

Storage and cleanup

Session runtime data remains global. Project review memory is version-controlled with the reviewed repository:

<repository>/
  .codereview/
    memory.json

~/.forge/
  config.json
  memory.json  # legacy v1 import source, if present
  sessions/
    forge-v2.sqlite
    <session-id>/artifacts and exports
  worktrees/
    <session-id>/

.codereview/memory.json separates mandatory rules, suggestions, exemptions, architecture notes, team preferences, risk hotspots, review summaries, and decisions. Mandatory rules and team preferences are always selected; other memory is filtered by changed paths, rule triggers, modules, ignore directories, keywords, and tags. The selected block remains in the fixed system context of every provider request in that turn. The schema automatically migrates flat v1 memory and imports applicable entries from the legacy global file without deleting it. Forge rejects credential-like content when loading or saving this version-controlled file. See Project review memory.

Active task state remains in durable session/run checkpoints. Ordinary file reads, listings, searches, and status output are turn-scoped: Forge retains them while a run can still be resumed, then removes their raw text at terminal completion while preserving source references and integrity hashes. Patches, tests, commands, approvals, errors, and final reports remain durable audit evidence.

Set FORGE_HOME to use a different root for tests or isolated operation. Sessions with at least one submitted instruction and their worktrees are retained indefinitely. Normal startup and exit do not delete retained history; the sole exception is a fresh zero-turn window, whose empty record and isolated worktree are discarded on exit. forge cleanup displays exact paths and sizes, defaults to cancellation, and removes only explicitly selected retained targets after confirmation.

Docker and repository safety

Each agent task uses an ephemeral container with --network=none, a read-only root filesystem, dropped capabilities, no-new-privileges, bounded resources, and only the isolated Forge worktree mounted writable. Finished containers use Docker --rm. Docker Desktop itself remains running to make later launches faster.

The target path must be an existing Git worktree root with a commit. Forge never infers it from recent history. The user's original worktree remains unchanged; inspect /diff or /export before manually applying any result.

Additional non-interactive commands

Existing automation surfaces remain available and use the v2 JSON model configuration and global Forge storage:

forge models list
forge prepare
forge run --help
forge inspect --help
forge export --help
forge eval --help

forge prepare normally is unnecessary because interactive bootstrap prepares the image automatically.

Troubleshooting

Configuration failure

Run forge doctor. Errors identify the expected config.json path and invalid field without printing API keys. Startup performs no billable probe.

Docker does not become ready

Check both the client and server:

docker version
docker info

Forge's failure screen offers R to retry and Q to quit. A redacted diagnostic is retained beneath ~/.forge/sessions/diagnostics. An McpError: Connection closed usually means the container or Docker engine closed before the MCP handshake; inspect the earlier Docker error first.

forge is not found

Run uv tool update-shell, reopen the terminal, and retry forge --help. Do not copy wrapper scripts manually.

Development and release

uv sync --locked --all-groups
uv run pytest
uv run ruff format --check src tests
uv run ruff check src tests
uv run pyright
uv build

The wheel contains the Dockerfile, hashed runner dependencies, and MCP server source needed to build the runner image after installation. The full reproducible gate is documented in the release checklist.

Project governance

• Security reports: SECURITY.md

• Contributions: CONTRIBUTING.md

• Support: SUPPORT.md

• User-visible changes: CHANGELOG.md

Forge is released under the MIT License.