Quickstart

1. Point Forge at a model

There is no default model. Set one in your shell profile, or pass --model per run.

$ export ANTHROPIC_API_KEY="sk-ant-..."$ export ANTHROPIC_MODEL="claude-sonnet-4-5"

2. Start a session

Run forge in the repository you want it to work in. The current directory becomes the workspace unless you pass -C.

$ cd ~/projects/api$ forge

Forge prints what it resolved, inside a cyan panel:

Forge  -  autonomous software-engineering agentmodel: claude-sonnet-4-5workspace: ~/projects/apiapprovals: auto   sandbox: noneType a task, /help for commands, or 'exit' to quit.

3. Give it a task

Type a sentence at the › prompt. Forge logs each tool call as it makes it, then prints a run summary with duration, model calls, tool calls, and token usage.

› add a /healthz endpoint and a test for it

A first task should be small and verifiable - a failing test to fix, a missing endpoint, a rename across a package. Watch what it does before handing it something larger.

Session commands

Anything that is not a slash command is sent to the agent as a task.

One task, then exit

Pass the task as an argument and Forge runs it to completion and exits with a meaningful code - this is the form to use in scripts, git hooks, and CI.

$ forge "fix the failing test in tests/test_auth.py"$ echo "run ruff and fix what it reports" | forge run --json

Approve as you go

The default mode lets Forge write files and run commands unattended, and stops to ask before anything destructive. If you would rather approve every change on the first few runs:

$ forge --cautious "refactor the config loader"

• Permissions - the modes, the risk model, and what is always refused.
• Sandbox - run shell commands in a container instead.