Documentation

Getting started

Configuration

Capabilities

Control

Reference

Tools

The registry the model can call, and each tool's risk level.

A tool is a function the model may call, with a typed schema and a risk level. The set below is the whole registry - Forge cannot reach anything that is not in it, and cannot reach a file outside the workspace root through any of them.

$ forge tools$ forge tools --json

That command prints the registry of the build you have installed. It is the authoritative list; this page is a description of it.

Risk levels

Every tool carries one of three levels. The level is a property of the tool, and it is what the permission policy decides on - not the tool's name and not the model's opinion of how safe a call is.

read

Observes only. Always runs unattended.

write

Creates or modifies things the agent can also inspect and fix.

destructive

Discards work or reaches outside the workspace. Needs a human.

The split is deliberate: writes are recoverable because the agent can inspect and fix them, while destructive calls throw work away. Only the third class needs a human in the default mode. See Permissions for how a call is decided.

The registry

Filesystem

Reading and changing the workspace. Every path resolves inside the workspace root.

read_fileread

Read a UTF-8 text file and return its contents. Supports offset/limit for reading a slice of a large file.

list_directoryread

List directory contents (optionally recursive).

search_filesread

Search file contents by regex, returning 'path:line: text' matches.

write_filewrite

Create or overwrite a file with the given contents.

edit_filewrite

Replace an exact string in a file. Fails if old_string is missing, or matches more than once and replace_all is false.

apply_patchwrite

Apply unified-diff hunks to an existing file (exact context match).

Shell

One tool, and the reason Forge can prove its work instead of asserting it.

shellwrite

Run a shell command in the workspace and return its stdout, stderr, and exit code. Use for tests, builds, linters, and other CLI tools.

Git

Typed operations rather than shelled-out strings. On by default.

git_statusread

Show the working-tree status: staged, unstaged, and untracked files.

git_diffread

Show changes as a unified diff. Use this to review your own edits before committing, and to confirm what a task actually changed.

git_logread

Show recent commit history.

git_showread

Show a commit's message and diff.

git_addwrite

Stage changes for the next commit.

git_commitwrite

Create a commit. Commits only what is staged unless paths or all_tracked are given. Never pushes.

git_branchwrite

List branches, or create/switch to a new branch. Deletion is gated.

git_checkoutwrite

Switch to a branch or commit, or restore specific paths from a ref. Restoring paths discards uncommitted changes and requires approval.

git_revertdestructive

Create a commit that undoes an earlier commit.

git_resetdestructive

Move HEAD to a ref. 'hard' mode permanently discards uncommitted work.

Boundaries

Workspace confinement - relative paths resolve against the workspace root, and a path that escapes it is refused rather than clamped.
Failures are data - a non-zero exit, a missing file, or a patch that does not apply comes back as a result the model must read. It does not crash the run, which is what lets the loop correct itself.
Truncated output - long stdout is cut with a marker, so one chatty command cannot consume the whole context window.
Exact-match edits - edit_file fails when its target string is missing or ambiguous, and apply_patch requires exact context. A silent partial edit is the one outcome worth ruling out.

A note on the shell tool

shell is the most capable tool in the registry and the one worth understanding. It runs a command in the workspace with a timeout, and returns stdout, stderr, and the exit code as structured data. Tests, builds, linters, and type checkers all arrive through it.

Because a shell can do anything, it is also where the deny list applies. Commands matching a deny pattern are refused in every mode, and a set of recognisably dangerous commands is escalated to destructive so they reach you even in auto. Run it in a container if you want a harder boundary than that.

Extending the registry

Tools are registered through one interface, which is where MCP servers will plug in. That work is not done - nothing outside this page's list is callable today.