Local Mode Guide

Updated on Oct 1, 2026

Local mode runs Forge workflows without an external issue tracker, ticket tracker, or code hosting platform. Forge reads issue and ticket descriptions from Markdown files in .forge/work/, and the agent uses local Git branches for code. Use local mode for offline or restricted environments, for trying Forge, or for small projects that don't need platform integration.

Prerequisites

Forge installed with a valid license. See Licensing.
A configured AI agent. Local mode removes the tracker and platform dependencies; the agent still needs its own access.
A Git repository.

Configure local tools

Initialize the toolchain with the local tools:

bash

frg config init --issues local --code local

To also track support tickets locally, add --tickets local. To replace an existing toolchain.toml, add --force.

The resulting .forge/config/toolchain.toml contains (abbreviated):

toml

schema_version = "1.0.0"

[issue_tracker]
name = "local"
type = "built-in"
method = "local"  # Only supported method for local tools

[code_platform]
name = "local"
type = "built-in"
method = "local"  # Only supported method for local tools

You can mix local and external tools, for example local issues with GitHub:

bash

frg config init --issues local --code github --force

See Toolchain Configuration.

Work with a local issue

Set an issue ID:
bash
```
frg config set-issue FEAT-123
# or
export FORGE_ISSUE_ID=FEAT-123
```
Use a numeric (123) or alphanumeric (FEAT-123, my-feature) ID of up to 100 characters. Choose an ID that won't conflict with issues or pull requests in any online tracker you might use later.
Create the issue directory:
bash
```
mkdir -p .forge/work/job_FEAT-123/issue
```

Write the issue description in .forge/work/job_FEAT-123/issue/issue.md, or let Forge draft it with frg issue draft. For example:

markdown

# Add CSV export to the reports page

## Overview
Users need to download report data for use in spreadsheets.

## Acceptance criteria
- [ ] The reports page has an "Export CSV" button
- [ ] The export contains the rows and columns currently displayed
- [ ] Large reports export without a timeout

## Out of scope
- Excel (.xlsx) export

Run workflow commands as usual:
bash
```
frg issue review
frg issue plan
```

Work with a local ticket

With --tickets local, Forge reads ticket content from .forge/work/ticket_<ticket_id>/ticket.md:

bash

frg config set-ticket TICKET-42
mkdir -p .forge/work/ticket_TICKET-42
# Write the ticket content to .forge/work/ticket_TICKET-42/ticket.md
frg ticket triage

Work with the local code platform

With code_platform.name = "local":

Branches are created with local Git commands.
There is no remote pull request creation or merge.
The PR ID is a conceptual identifier for branch naming and tracking.

Set a PR ID when a command needs one:

bash

frg config set-pr 1
# or
export FORGE_PR_ID=1

Merge locally with Git, for example git merge feature/FEAT-123.

Limitations

Area	Local mode	External tools
Issue and ticket content	Read from Markdown files	Fetched from the tracker
Status, labels, assignees	Not supported (static documents)	Synchronized
Synchronization	None	Automatic
Pull request creation and review	Not supported	Through the platform
Merge	Local Git only	Remote merge
CI/CD triggers	Not supported	On push or pull request

Troubleshooting

Issue ID required for 'issue' operations

Cause: No issue ID is set in the environment or in .forge/context.toml.

Solution:

Set the ID with frg config set-issue <id> or export FORGE_ISSUE_ID=<id>.
Confirm with frg config show-context.

The agent can't find the issue description

Cause: issue.md isn't at .forge/work/job_<issue_id>/issue/issue.md, or the directory name doesn't match the current issue ID.

Solution:

Run frg config show-context and note the issue ID.
Check that .forge/work/job_<issue_id>/issue/issue.md exists.
Create the directory and file if they're missing.

Move to an external tracker

Create the issue in the external tracker.

Regenerate the toolchain, for example:

bash

frg config init --issues github_issues --code github --force

Set the new issue ID with frg config set-issue <new-id>.