# 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](docs/architecture.md) and
[security boundary](docs/security.md) before using Forge on an important
repository.

## Requirements

- Windows 10/11 with CMD, PowerShell, or Windows Terminal.
- Python 3.12 or 3.13.
- [uv](https://docs.astral.sh/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.

## Quick start

### 1. Clone and install the global command

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

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

```powershell
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:

```powershell
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:

```json
{
  "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:

```powershell
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:

```powershell
forge <repository-path>
```

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

## Primary commands

| Command | Purpose |
| --- | --- |
| `forge` | Start a fresh conversation for the current Git repository. |
| `forge <path>` | Start a fresh conversation for an explicit Git repository. |
| `forge resume` | Choose any retained conversation with arrows and `Enter`. |
| `forge doctor` | Validate the active v2 configuration locally. |
| `forge cleanup` | Preview, select, and explicitly confirm retained data removal. |

Local diagnostics never contact the provider:

```powershell
forge doctor
forge doctor --all
forge doctor --profile primary
```

A live provider request occurs only when explicitly requested:

```powershell
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:

```text
<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](docs/memory.md).

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:

```powershell
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:

```powershell
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

```powershell
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](docs/release-checklist.md).

## Project governance

- Security reports: [SECURITY.md](SECURITY.md)
- Contributions: [CONTRIBUTING.md](CONTRIBUTING.md)
- Support: [SUPPORT.md](SUPPORT.md)
- User-visible changes: [CHANGELOG.md](CHANGELOG.md)

Forge is released under the [MIT License](LICENSE).