Forge
Run, supervise, and resume AI coding work without leaving the terminal.
Forge is an open-source terminal coding environment for engineering with AI
agents. It combines agent conversations, a file explorer, Vim-style editing,
an interactive shell, diffs, approvals, model selection, and multiple durable
sessions in one keyboard-driven TUI.
Managed sessions keep their own durable state and isolated Git worktree, so one
session can keep working while you inspect, edit, or direct another. Agent shell
commands run under an OS sandbox, with network egress controlled by explicit
host rules.
Forge is alpha software. Review every approval prompt and use it first in a
disposable or backed-up repository.
Why this exists
Most terminal coding agents optimize the prompt-to-patch loop. Real engineering
work is wider than that: you inspect code, edit some parts yourself, delegate
others, run commands, review diffs, verify behavior, switch tasks, and come back
later.
Forge keeps that whole loop in one workspace. The agent is part of the
environment rather than the entire environment: you can work directly in the
editor and shell, supervise long-running agent work, switch between independent
sessions, and resume durable state after an interruption.
What Forge does
- Runs multiple independent coding sessions in one TUI; managed sessions use
isolated linked Git worktrees and session-local state.
- Chats with configured models, reads and edits files, searches code, works
with Git, and runs tools until the task completes or you interrupt it.
- Gives you a built-in file explorer, Vim-style editor, interactive shell,
diffs, diagnostics, activity, and task state.
- Runs agent shell commands inside an OS sandbox confined to the workspace,
with network egress denied by default and opened through explicit host rules.
- Preserves transcripts, task state, queued follow-ups, and unfinished work in
a local SQLite journal so sessions can survive process restarts.
- Supports provider sign-in, per-session model selection, reasoning effort, and
model switching from the TUI.
- Connects configured MCP servers and exposes their tools to the agent.
- Supports child agents with durable state and isolated worktrees for delegated
work.
Install
Install a prebuilt release
On macOS or Linux:
curl --proto '=https' --tlsv1.2 -LsSf \
https://raw.githubusercontent.com/NorviaLabs/forge/main/install/forge-installer.sh | sh
On Windows PowerShell:
irm https://raw.githubusercontent.com/NorviaLabs/forge/main/install/forge-installer.ps1 | iex
The installers select the current release for your platform and verify its
SHA-256 checksum before installing. To install a specific release, set
FORGE_VERSION, for example v0.1.0-beta.8.
On Linux the installer also installs the sandbox's dependencies —
bubblewrap and socat — if they are not already present, prompting once
for sudo. It supports apt, dnf, yum, pacman, zypper, and apk. If that fails
it says so and continues: forge still runs, but without a sandbox it must ask
before every command. Set FORGE_SKIP_DEPS=1 to manage them yourself.
macOS needs nothing extra; its sandbox is built into the OS.
Windows runs forge under WSL2, where it uses the Linux sandbox. There is no
native Windows build — the PowerShell installer detects WSL2 and points you
at the Linux installer inside it. The sandbox suite runs against WSL2 in CI.
Build from source
You need Git and Rust 1.97.1 or newer.
git clone https://github.com/NorviaLabs/forge.git
cd forge
cargo build --release --locked --package forge-cli
./target/release/forge --version
To run the development build:
cargo run --locked --package forge-cli
Start Forge
Run Forge from the repository you want the agent to work in:
forge
The default workspace is the current directory. Forge also respects the
FORGE_WORKSPACE environment variable.
On first launch, Forge walks through theme, directory trust, and provider
connect. A committed theme is stored in your user config; trust is stored
per directory (children inherit). Esc during those steps quits without
claiming setup is done. Later folders only ask for trust. Returning to a
trusted folder opens the normal TUI.
GitHub issue workflow
Use i from Git review or /issues to browse open issues without hiding the
conversation. ←/→ selects an issue even when the navigator is collapsed;
↑/↓ scrolls details, / filters, r refreshes selected details, and R
reloads the repository list. Esc restores the previous file or patch.
n previews a new isolated issue session; Enter confirms it. Starting or
completing an issue never automatically pushes, creates a PR, or merges.
Attach the linked session and explicitly press p to push and create its PR.
PR refresh is read-only. Checks show the captured PR head and refresh time;
local passing tests do not imply passing remote checks. l loads bounded logs
for the first failed GitHub Actions check; other check providers show their link.
a previews concrete check/review feedback; confirmation copies it into an empty
composer for explicit submission, preserving existing drafts.
GitHub reads require gh and gh auth login, run in background workers, and
have command deadlines and output limits. The list is limited to 100 open issues.
Automation and benchmark runs
Forge also has a frontend-independent entry point for automation. Pipe one
prompt to forge bench to use the same session assembly, provider routes,
credentials, journal, sandbox, governance, and tool loop as the TUI:
printf '%s\n' 'Inspect the repository and summarize it.' | \
forge bench \
--workspace /path/to/repository \
--journal /tmp/forge-journal \
--model openai_codex/gpt-5.6-luna \
--effort max \
--approve-all
--model is required and names the provider by its prefix
(<provider>/<model>). The command emits one JSON response on stdout and
keeps logs on stderr.
--approve-all is intended only for an isolated evaluation checkout; without
it, a tool request that needs human approval stops with an error.
Providers and models
Forge includes native routes for:
- OpenAI API (
openai/*)
- Anthropic API (
anthropic/*)
- xAI Grok through OAuth (
xai/*)
- OpenAI Codex subscriptions through device login (
openai_codex/*)
- OpenCode Go (
opencode_go/*)
- OpenCode Zen (
opencode_zen/*)
- Ollama running locally (
ollama/*)
A model id's prefix is its provider id. Ids saved with an older prefix
(openai-codex/, opencode-go/, opencode-zen/) are converted when Forge
reads them; typing one gives an error naming the current prefix.
The simplest setup is to export a provider key, launch Forge, and pick a
model with /model:
export OPENAI_API_KEY="..."
forge
Forge remembers the last model you chose and starts new sessions on it;
resumed sessions keep their own model.
Each key provider reads FORGE_<ID>_API_KEY first (for example
FORGE_OPENAI_API_KEY or FORGE_OPENCODE_GO_API_KEY), then its usual
variables such as ANTHROPIC_API_KEY, OPENCODE_API_KEY,
OPENCODE_GO_API_KEY, and OPENCODE_ZEN_API_KEY. FORGE_<ID>_BASE_URL
overrides the endpoint. An environment key wins over a key saved with
/connect, and /disconnect cannot remove it: unset the variable instead.
For xAI, an XAI_API_KEY in the environment is used instead of the login.
For OAuth providers, use /connect inside Forge. For Ollama, start the local
Ollama service first, then choose the Ollama route and a locally available
model.
OpenCode Go serves its models on more than one protocol. Forge routes each
model to the endpoint OpenCode publishes for it — Chat Completions, Responses,
or the Anthropic Messages API — so models such as opencode_go/union-alpha
work without extra configuration. Union Alpha on OpenCode Zen
(opencode_zen/union-alpha) also uses the Messages API.
Custom OpenAI- or Anthropic-compatible providers are added with
/connect → + Add custom provider, which saves them to
forge/providers.toml in the platform config directory. Keys stay in the
separate credentials.toml. Provider entries saved by this version use the
current field names, which older Forge builds cannot read.
On Chat Completions routes (including OpenCode Go's DeepSeek models), a
provider output limit or a stream that ends without a completion signal is
reported as an incomplete-turn error rather than a successful answer. Use
Continue to resume the task; tools from the incomplete response are not executed.
Useful in-app commands:
/connect Connect or change a provider
/model Browse or change models
/resume Browse previous sessions in the current journal
/continue Resume the most recent previous session
/new Start a new session in its own worktree
/fork Start a new session from this conversation
/clear Clear the visible transcript
/compact Compact the active context
/disconnect Remove a saved provider connection
/edit Open the active file in your editor
/context-file Attach the active file to the next message
/terminal Open the terminal panel
/resize Resize panes with arrow keys (`/resize reset` restores defaults)
/theme Change the presentation theme
/status Session status and diagnostics
/git Review, stage, commit, branch and merge in the center pane
(`s`/`u` stage, `d` cycles working tree/staged/last turn, `c` commit,
`<`/`>` pull/push, `f` fetch, `b` branches (`x` delete, `r` rename),
`M` merge, `a` abort merge). In the navigator's Git tab the same keys
work from the changed-file list, which adds `↑`/`↓` to move the list
cursor and `i` for issues
/issues Browse repository issues inline; requires authenticated GitHub CLI
/goal Work toward a completion condition until it holds (`/goal clear` stops)
/effort Set model effort
/thinking Toggle model thinking generation
/help Open help
/quit Close the current session; on the primary session, quit Forge
/resume <session-id> resumes a specific session. The command-line form
forge --resume <session-id> does the same; bare forge --resume resumes the
most recently modified session when one exists.
Keyboard controls
Forge displays contextual hints for the current focus. The most useful global
controls are:
| Key | Action |
|---|
Tab / Shift+Tab | Move between visible blocks |
| Any printable key | Start (or continue) a draft in the composer — from any block except the terminal panel |
Enter / i | Interact with the focused block or control |
Esc | Leave the current interaction level |
↑ / ↓ | Navigate a local list or input |
F1 | Open help |
F3 | Open the session switcher |
F4 | Open model picker |
Ctrl+1 / Ctrl+2 / Ctrl+3 | Show Sessions / Files / Git (repository mode) |
F6 | Switch between conversation and the current file, diff, or issue |
Ctrl+E | Cycle navigator tabs (Sessions / Files / Git in a repository) |
↑ at the first row, then ← / → | Move onto the navigator tab row and step through Sessions / + / Files; Enter switches tab or, on +, starts a session (repository mode) |
Ctrl+Backtick | Toggle the terminal panel (or /terminal) |
Ctrl+O | Expand or collapse tool details |
Alt+M | Quick-switch model |
Alt+, / Alt+. | Step reasoning effort down or up |
Alt+← | Go back to the previous workspace view |
Ctrl+↑ / Ctrl+↓ | Move the selection in the queued-message list |
Ctrl+Backspace | Cancel the selected queued message |
Ctrl+C |
Typing is always one step from anywhere: a printable key the focused block has
no binding for starts (or continues) a draft in the composer, and focus moves
with it, so a chat message never lands behind a pane that still looks active.
The block's own keys win — d in the session list still marks a session done,
x in the chat transcript still stops a background task. The terminal panel is
the exception: its shell takes every byte.
The footer carries a chip row: model and effort. It is an ordinary Tab
stop — Tab to it, ←/→ to pick a chip, Enter to open the picker.
Enter still sends from the composer; ⏎ is a hint only. Ctrl+Shift+V attaches a
PNG/JPEG/GIF/WebP from the local clipboard (workspace-only; SSH has no image
clipboard). A clipboard that only holds TIFF — several macOS apps publish it
alone — is converted to PNG on the way in, and a clipboard helper that fails
(denied Automation permission, no wl-clipboard/xclip installed) says why
rather than reporting an empty clipboard. Model, effort, thinking, and provider
connection controls remain available while a turn is running; changes apply to
the next model step. The model can also call view_image on a workspace file
when the active model accepts image input.
Conversation is the primary surface, with a resource inspector on the right
when there is room. The prompt spans the work surface. Below 116 columns,
F6 or the workspace tabs switch between conversation and the current resource,
preserving the draft, reading position, and unsaved edits. File, session, and Git
navigation temporarily fill the body when a persistent column cannot fit;
Ctrl+P still opens file search at the 80×18 minimum.
Below 24 rows, the terminal yields space while another surface has focus;
Tab back to the panel, Ctrl+Backtick, or /terminal resume the same shell.
When the terminal panel is focused, it is an interactive login shell, and its
title shows > Terminal with a thicker rule so you can tell it holds the keyboard.
Type or paste commands directly into it; standard control keys, arrows, Tab,
and terminal resize are forwarded to the shell. Ctrl+Backtick, Esc, or a
directly typed exit hides the panel without killing the shell, so reopening
resumes the same session.
Manual commands are passed through without adding status scripts to shell history.
Ctrl+E and Ctrl+N keep their shell meanings while the panel is focused;
Shift+Tab leaves panel focus. Shift+PageUp / Shift+PageDown and the mouse
wheel browse the terminal's 1,024-line scrollback; typing returns to live output.
In full-screen programs using the alternate screen (such as Vim), Esc goes to
the program and Ctrl+Backtick hides the panel. If the login shell exits through
EOF or exit 0, hiding and reopening the panel starts a fresh shell.
Paste into the file editor or scratchpad in Insert mode; Normal and Visual mode
reject pasted text rather than interpreting it as commands. Drag-selection copies
visible text, including Unicode glyphs. Scrolling, editing or resizing clears a
finished selection when its displayed content changes. Right-click offers Copy
and Clear selection in a menu that stays on screen.
Ctrl+N opens the session scratchpad outside the terminal panel. Notes autosave
when you close the scratchpad, leave terminal focus, or quit Forge, and return
when you resume the same session. :w saves explicitly; :q! discards unsaved
edits. A new session starts with empty notes.
When a text file is open, the workspace uses Vim-style editing. Markdown,
structured text, HTML/XML/SVG, stylesheets, diffs, configuration files, Mermaid
diagrams, and logs start in read-only preview; press i to edit. Other text
files start in Normal mode; press i to insert. Esc leaves the current
interaction, and Alt+E hands the file to $VISUAL/$EDITOR. In Normal mode,
/ searches forward and ? searches backward; both accept uppercase letters
typed with Shift. Press Enter to accept or Esc to cancel. After accepting,
use n to repeat in the same direction or N to go the opposite way. : opens
the editor command line. The beta command set includes :w, :q,
:q!, :wq, :x, :preview, :edit, :e [path],
:s/pattern/replacement/[g], and :%s/pattern/replacement/[g]. Saving is
immediate. Forge asks whether to save, discard, or cancel before leaving or
switching away from dirty buffers, and asks whether to reload or force-save
when the file changed on disk. Binary and invalid-UTF-8 files stay explicitly
read-only.
Configuration
Forge reads defaults, a user configuration file, a forge.toml in the
working directory, and environment variables. Environment variables override
file configuration.
A minimal project forge.toml can look like this:
[tui]
theme = "forge-dark"
file_icons = "unicode"
notify = "auto"
reduced_motion = false # Set true for static working indicators.
[journal]
path = ".forge/sessions"
[tools.agents]
max_depth = 2
min_wait_ms = 100
default_wait_ms = 10000
max_wait_ms = 120000
forge.toml does not choose the provider or model: [model] provider,
model, base_url, and api_key are ignored with a startup notice. Use
/connect and /model instead. [model] request_timeout_secs still applies.
Agent orchestration is enabled by default. The model can use spawn_agent,
send_message, followup_task, wait_agent, list_agents, and
interrupt_agent. Each child runs in an isolated Git worktree and inherits the
parent model, governance, and workspace policy. spawn_agent can narrow a
child's tools with tool_allowlist.
notify controls whether Forge reaches you when a background task blocks on
approval or stops while the terminal is unfocused: auto (the default) sends a
desktop notification where the terminal is known to support one and stays
silent elsewhere, bell rings the terminal bell, osc9 forces a desktop
notification, both sends both, and off disables it. auto is silent rather
than falling back to the bell, because an unexpected audible bell is worse than
no notification; set bell if your terminal is not on the known-good list.
max_depth bounds nested work. send_message queues a
mailbox message without waking its target; followup_task wakes an idle or
completed descendant. Agent IDs are opaque session identifiers, and operations
are limited to descendants of the calling agent. Child journals, statuses,
summaries, and worktree locations are durable. Running children are resumed
after a restart when their worktree is recoverable; completed children remain
available for a later follow-up without reopening their historical task.
Themes
Forge ships built-in themes you can pick with /theme or set in forge.toml.
Bare /theme opens a bottom dock: ↑↓ live-previews against the real UI, Enter
confirms, Esc restores the previous theme. /theme <id> applies immediately.
| Theme id | Name |
|---|
forge-dark | Forge Dark (default) |
forge-light | Forge Light |
system | Follow terminal light/dark preference |
Drop custom .toml theme files into .forge/themes/ in your workspace or
~/.config/forge/themes/ to add or override themes. See
crates/forge-tui/themes/ for the schema and examples.
Common environment variables are:
FORGE_WORKSPACE
FORGE_JOURNAL_PATH
FORGE_DATA_DIR
FORGE_MODEL_REQUEST_TIMEOUT_SECS
Forge stores session journals in repository-local runtime storage when
possible, or in the platform application-data directory outside a Git
repository. FORGE_DATA_DIR replaces that directory; cargo test and
cargo run in this repository set it to target/forge-data. Runtime data is not source code and should not be committed.
MCP servers
MCP servers can be configured in a trusted user config or an explicitly
managed configuration:
[[mcp.servers]]
id = "my-tools"
transport = "stdio"
command = "my-mcp-server"
args = ["--stdio"]
Project-discovered configuration is intentionally restricted: settings that
could execute code or redirect credentialed requests are not accepted from an
untrusted checked-out repository.
The sandbox
Every shell command the agent runs is confined by the operating system.
Confinement is applied at spawn, so it does not depend
on the agent classifying a command correctly beforehand — forge does not try
to decide whether rm -rf is dangerous, it removes the reach that would make
it matter.
| Platform | Mechanism |
|---|
| macOS | Seatbelt (sandbox-exec), built into the OS |
| Linux | bubblewrap (bwrap) |
| Windows | WSL2, using the Linux sandbox |
Inside the sandbox a command can:
- read inside your workspace, the per-session temp directory, and the
OS-owned paths a process needs to start (system binaries, libraries,
frameworks, and standard configuration), plus the read-only runtime paths
selected from the command's resolved executable and configured toolchain
homes. Everything else user-writable —
~/.ssh, ~/.aws, and other home
configuration included — is outside that boundary, exactly as it is for
read_file/write_file;
- write only inside your workspace and the per-session temp directory;
- use installed command-line tools without exposing host caches or
credentials: Cargo's mutable state is redirected into the per-session temp
directory, and XDG-aware clients get session-local config, cache, and state
directories;
- reach the network only through the egress proxy described below.
On macOS, Apple Event sending is denied so sandboxed commands cannot drive
host GUI apps via osascript. Application handoffs through open may also
require approval to retry outside the sandbox.
.git and .forge are read-only: the agent can inspect history but cannot
rewrite it, and cannot edit the permission rules that govern it.
What a command needs from outside that boundary — an SSH key, an installed SDK,
or unrelated home data — is refused by the OS and escalated to you: forge asks
before replaying the command unconfined rather than letting a confined process
reach it. Selected command runtimes remain read-only; their network access
still requires an explicit personal host(...) grant, and .git remains
read-only unless the command is an explicitly approved git operation.
Forge reports a shell-redirection refusal even when a later pipeline stage
makes the shell exit zero. Network refusals are attributed to the exact command
that reached the proxy, so a swallowed error cannot trigger a misleading
approval on the next command. A command that deliberately discards every
filesystem diagnostic and returns zero is not observable from the portable
process interface; the write is still blocked, but Forge cannot infer that an
unconfined retry was intended.
If macOS open reports the Launch Services permission error -54, Forge
asks to retry that exact command outside the sandbox. For a failed bash
call whose output does not identify a sandbox denial, the agent can use
request_unconfined_retry with the failed call's ID and a reason. Forge
recovers the original arguments and asks for one-time approval; the request
cannot supply a replacement command. Session and saved command rules do not
authorize removal of the sandbox. A failed unconfined attempt cannot trigger
another escalation for the same command during that turn. Retry references
are consumed once and expire at the end of the turn. After restarting Forge,
an approval whose original arguments are unavailable must be denied and the
command issued again; Forge never executes redacted display arguments as a
sandbox retry.
There is one residual socket gap worth stating plainly. On Linux the sandbox
still exposes the rest of the host filesystem read-only rather than hiding
it, and a read-only mount does not stop a process connecting to a Unix
socket — that check looks at the inode, not the mount flag. Forge masks
/run, /tmp, and the home trees (/home, /root), which covers the
sockets with the worst blast radius: docker.sock (root on the host),
systemd, D-Bus, $XDG_RUNTIME_DIR (where ssh-agent and gpg-agent live), and
~/.docker. A pathname socket somewhere else — under /var or /opt — is
still reachable from inside the sandbox. A confined command already runs as
you, so this widens what it can touch rather than crossing a privilege
boundary. Closing it needs Landlock's LANDLOCK_ACCESS_FS_RESOLVE_UNIX,
which is newer than the kernels forge runs on today; seccomp cannot express
it. Tracked in issue #392.
If the OS cannot confine — bubblewrap missing, an unsupported platform — forge
does not start. It prints why on stderr and exits. There is no combination of
settings that turns oversight off without an enforcement floor in place.
Network egress
The sandbox denies network access outright, then reinstates it through a
filtering proxy reached over a Unix socket. The proxy reads the CONNECT host
each request names and refuses anything not on the allow-list. It does not
terminate TLS, install a certificate, or see your traffic — it only decides
where a connection may go.
The allow-list is empty until you add hosts. Nothing — not crates.io, npm,
PyPI, or GitHub — is reachable unless a personal host(...) allow says so,
or you grant unrestricted network with host(*). A repo-committed file
cannot open this; only your personal permissions file can.
Permission rules
permissions.toml can re-prompt a call (deny) or skip a prompt that would
otherwise appear (allow). Pattern rules match the actual call — a command
prefix for shell tools, a path glob for file tools, a host for fetch-style
tools. host(...) rules are different: they feed the egress proxy, not the
approval prompt. Shell does not prompt by default, so allow rules for shell
do nothing to prompting. MCP still prompts unless allowed:
allow = [
"bash(cargo test *)",
"bash(cargo build*)",
"host(**.crates.io)",
"host(**.github.com)",
]
deny = ["bash(cargo publish*)"]
host(*) is unrestricted network through the proxy (the filesystem sandbox
stays on). A host(...) deny still wins over a broader allow.
A deny entry carves an exception out of a broader allow entry (cargo *
allowed, but cargo publish still asks); it never blocks a call outright —
that's still the ACL's job. Two files are read and merged:
<user config dir>/forge/permissions.toml — personal, trusted..forge/permissions.toml in the workspace — repo-committed, and for the
same reason project-discovered MCP config is restricted above, its allow
entries are ignored. A checked-out repository cannot grant itself a wider
blast radius than a human approved locally. Its deny entries are always
honored, since narrowing approval further is safe regardless of source.
Menu rows (when a prompt appears):
- Run once — run this call; ask again next time.
- Remember similar commands this session — remember a generalized
family for the rest of the session. The selected row explains what would
match (for example
git push …). Matching commands later run without a
prompt; a different family still asks. Not written to permissions.toml.
- Don't run — block the call.
When the sandbox blocked a host (for example a CLI talking to
api.github.com), the menu is a host grant instead, and the command is
retried still confined. A host grant also projects HTTPS identity
for that host into the confined spawn: credentials are filled on the
host (git credential), SSH remotes (git@host:) are rewritten to
HTTPS (SSH cannot use the CONNECT proxy), git-dir writes are allowed
only for spawns that run git itself — and never for .git/hooks or
.git/config, which decide what git executes on the host — and HTTPS CLIs
that read a {label}_TOKEN
environment variable receive one derived from the granted host. Ordinary
commands still cannot write .git. The sandbox cannot open the OS
secret store, so without projection an HTTPS client prints HTTP 401 /
"invalid token" and looks like broken auth.
- Always allow
**.github.com — writes host(**.github.com) to the
personal permissions file so the next session does not ask again.
- Allow
**.github.com this session — live proxy only.
- Don't run — block the call.
Approvals
There is no permission-mode setting. Shell commands and file writes run
without a prompt: the sandbox is the boundary. MCP tools still prompt,
because those are separate server processes the sandbox does not confine. A
deny pattern re-prompts even for shell. An ACL deny is a hard block, not a
prompt.
A host that cannot confine never reaches this policy — Forge refuses to start.
Approving shell commands
When a command needs approval, use the inline menu:
- ↑ / ↓ — move selection (default: Run once)
- Enter — confirm
- Esc — don’t run (or back out of “Deny with note”)
Optional text aliases still work: yes, no, remember, always,
no <note>.
Built-in tools
Depending on configuration, the agent can use tools for:
- reading and writing files;
- applying validated workspace-confined patches;
- running shell commands inside the sandbox;
- inspecting Git status and diffs;
- fast file and content search;
- coordinating isolated child agents and reviewing their status;
- web search;
- configured MCP tools.
Tool arguments are validated before execution, and shell commands are confined
by the OS sandbox rather than judged for danger beforehand. Forge does not
treat model output as trusted input.
Sessions and resume
Forge supports multiple durable managed sessions inside one TUI. Each session
has its own identifier, transcript, queued follow-ups, model selection, runtime
state, and isolated linked Git worktree. A session can continue streaming or
running tools in the background while you switch to another session and work
there independently.
Use F3 to open the session switcher. Session presentation and input routing
stay session-local: switching sessions does not move drafts, queued prompts,
approvals, questions, or model state into another session.
Start a new session with n in the navigator's Sessions list, the + cell on
the navigator tab row (reachable with ↑ from the first list row), or /new
from the composer. The session is created straight away and named from the first
prompt submitted in it.
If Forge stops unexpectedly, start it with:
forge --continue
--continue resumes the most recently modified previous session in the
current workspace. To browse or resume a specific session:
forge --resume
forge --resume <session-id>
Use --fork <session-id> to create a new session seeded with the selected
conversation while leaving the original session unchanged. The equivalent TUI
commands are /continue, /resume, and /fork. Model transcripts are
session-scoped; composer Up/Down recall is stored separately at the user level
and partitioned by workspace, so starting a new session does not erase recent
input recall. /clear hides the rendered transcript but does not erase model
context; use /compact when you want a smaller model-visible context.
Inside the TUI, /resume lists previous sessions and shows a title hint from
the first user message when available. Session journals stay separate from your
source files and should never contain API keys or OAuth tokens.
Safety
Forge can execute commands and modify files on your machine. Treat it like a
shell with an AI interface:
- Run it only in repositories you trust. The sandbox confines what a command
can reach; it does not make an untrusted repository safe to build.
- Read each approval prompt, including the exact command and consequence.
In Auto mode most shell commands do not prompt — the sandbox is what
stands in for that review, so check that it is active (the footer's mode
chip says when the mode is capped).
- Keep credentials in your environment or trusted user configuration. The
sandbox restricts where a command may connect, but a command that legitimately
reaches an allow-listed host can carry whatever it can read.
- Do not commit
.forge/, runtime journals, API keys, OAuth tokens, or
credential files.
- Use a disposable clone when evaluating an unfamiliar repository.
See SECURITY.md for the threat model and private vulnerability
reporting process.
Development
Forge is a Rust workspace. The main crates are:
forge-cli — command-line entry point;forge-tui — terminal interface;forge-core — agent loop and session lifecycle;forge-model — provider transports and message normalization;forge-connect — provider profiles, credentials, and model catalog;forge-tools — built-in tools and validation;forge-durable — SQLite session journals.
Run the standard checks before submitting a change:
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --all-targets --locked
See CONTRIBUTING.md for contribution guidance.
License
Forge is available under the MIT License.
