Project Setup

Updated on Oct 1, 2026

Forge describes your repository to the AI coding agent using project metadata in .forge/config/project.toml. This page shows how to initialize Forge, fill in the metadata, add optional monorepo and context settings, and validate and lock the result.

Prerequisites

Forge is installed and on your PATH.
A terminal is open at the project root. A Git repository is recommended for workflows that inspect changes or create commits.
For workflow commands, an AI coding agent is installed and authenticated. See Agent Setup.

Warning: Forge workflows run agents autonomously. Run Forge in a sandbox or development container, not against production systems.

Step 1: Initialize Forge

For a new project, run the recommended interactive setup from the project root:

bash

frg config init -i

Forge guides you through agent selection, AI-assisted project metadata, development tool integrations, and a final review. Depending on your selections, it creates project.toml, agents.toml, toolchain.toml, and generated integration skills. See Interactive Configuration for every wizard phase.

For scripts, CI, or manual configuration, use non-interactive options to generate the required files:

bash

# Agent configuration (agents.toml). The default model profile is stable.
frg config init --agent github_copilot --models balanced

# Toolchain configuration (toolchain.toml). --code requires --issues or --tickets.
frg config init --issues github_issues --code github

Option	Description
`-i`, `--interactive`	Configure the agent, review AI-suggested project metadata, select tool integrations, and confirm generated files.
`--agent <AGENT>`	Generate `agents.toml` for `claude_code`, `github_copilot`, or `opencode`
`--models <PROFILE>`	Model profile: `lite`, `balanced`, `stable` (default), or `heavy`
`--issues <TOOL>`	Issue tracker: `github_issues`, `jira`, `azure_devops`, `shortcut`, or `local`
`--tickets <TOOL>`	Ticket tracker: `github_issues`, `jira`, `azure_devops`, `shortcut`, or `local`
`--code <TOOL>`	Code platform: `github`, `github_enterprise`, `bitbucket`, `azure_devops`, or `local`
`--scanner <TOOL>`	Security scanner: `polaris` or `github_sast`
`--app`	Create `application.toml` instead of project configuration. See Hierarchical Configuration.
`--force`	Overwrite the files selected by other options (see below)
`-q`, `--quiet`	Suppress all output except errors

Regenerate files with `--force`

--force overwrites only the files selected by the options you pass:

Option	File replaced
`--agent`	`agents.toml`
`--issues`, `--tickets`, or `--scanner`	`toolchain.toml`
`--interactive`	`project.toml`

For example, this command regenerates agents.toml without changing project.toml or toolchain.toml:

bash

frg config init --agent github_copilot --models balanced --force

--force cannot be used alone (--force requires at least one configuration option) and cannot be combined with --app.

Step 2: Complete the required metadata

Open .forge/config/project.toml. New projects use language-neutral defaults ("Unknown") that you replace with real values:

toml

schema_version = "1.0.0"

[project]
name = "my-project"
description = "Project description"
language = "Unknown"  # Primary language (e.g., TypeScript, C#, Python, Go, Rust, Java)
framework = "Unknown"  # Framework if any, or "None" (e.g., React, Angular, ASP.NET Core, Django, Gin, axum)
testing_framework = "Unknown"  # Testing tool (e.g., jest, xUnit, pytest, "go test", "cargo test")
package_manager = "Unknown"  # Package manager (e.g., npm, NuGet, pip, "go mod", cargo, Maven)

Field	Description	Example
`name`	Project name, up to 100 characters	`"user-service"`
`description`	Short summary for agent context, up to 250 characters	`"REST API for user management"`
`language`	Primary programming language	`"Rust"`
`framework`	Framework, or `"None"`	`"axum"`
`testing_framework`	Test framework or command	`"cargo test"`
`package_manager`	Package manager, or `"None"`	`"cargo"`

All six fields are required and must be non-empty. schema_version must be "1.0.0".

Step 3: Add custom fields (optional)

Add more keys under [project] when the agent needs extra information. Custom fields are available as template variables in prompts.

toml

[project]
# ...required fields...
documentation_framework = "rustdoc"
repository = "https://github.com/example/user-service"

Custom values must be non-empty, up to 250 characters, and free of control characters. A custom field cannot reuse a reserved core field name. Do not put credentials or tokens in custom fields; they are sent to the agent.

Step 4: Configure a monorepo (optional)

Add [monorepo] when one repository contains several services:

toml

[monorepo]
enabled = true

[[monorepo.services]]
name = "api"
path = "services/api"
description = "REST API service"
language = "Rust"
framework = "axum"
testing_framework = "cargo test"
package_manager = "cargo"

[[monorepo.services]]
name = "web"
path = "services/web"
language = "TypeScript"
framework = "React"
testing_framework = "Jest"
package_manager = "npm"

Each service needs a unique name and a unique relative path inside the repository. Other service fields are optional. When enabled = true, define at least one service. Select the active service with frg config set-service <SERVICE_NAME>.

For monorepo workflows, see Monorepo Configuration Support.

Step 5: Add project context (optional)

Use [[project.context]] to include files or directories in every workflow prompt:

toml

[[project.context]]
type = "file"
path = "docs/architecture.md"
description = "System architecture overview"

[[project.context]]
type = "directory"
path = "docs/standards"
description = "Coding standards and guidelines"

See Context Configuration.

Step 6: Validate the configuration

bash

frg config validate

The command validates application.toml, project.toml, agents.toml, toolchain.toml, and commands.toml when they are present, then checks agent dependencies and workflows. A successful run ends with All configuration files are valid. Review any warnings before you run workflows.

To validate a single file, use -f/--file <FILE>.

Step 7: Lock the configuration (optional)

bash

frg config lock

This command validates all configuration files and, if they pass, writes .forge/.config_lock with the SHA-256 hash of each file. The success message is Configuration locked successfully.

When a lockfile exists and a locked file changes, workflow commands are blocked until you run frg config lock again. Without a lockfile, workflow commands run without this check.

Other project.toml settings

Table	Purpose	Details
`[commit]`	Commit instruction behavior: `enabled` (default), `tagged`, or `disabled`	Commit Behavior Configuration
`[config.external_sources]`	Load configuration from user and system profiles	Hierarchical Configuration
`[ui]`	`show_command_hints`	Next Command Hints
`allow_app` (under `[project]`)	Join a multi-repository application	Hierarchical Configuration

Verify the setup

bash

frg config validate
frg config show
frg status

frg config validate reports no invalid files.
frg config show displays your project, agent, and toolchain values.
frg status detects the configured agent and its authentication state.

Troubleshooting

project.toml is missing

Cause: Forge is not initialized in this directory, or the file was removed.

Solution:

Change to the project root.
Run frg config init.

A required field is missing or empty

Cause: One of the six required [project] fields is absent or blank.

Solution:

Add values for name, description, language, framework, testing_framework, and package_manager.
Use "None" when a framework or package manager does not apply.
Run frg config validate.

Unsupported schema version

Cause: schema_version is not "1.0.0".

Solution:

Set schema_version = "1.0.0" at the top of the file.
Run frg config validate.

Monorepo is enabled but no services are defined.

Cause: [monorepo] enabled = true without any [[monorepo.services]] entries, or services have duplicate names or invalid paths.

Solution:

Add [[monorepo.services]] entries with unique names and existing relative paths, or set enabled = false.
Run frg config validate.

A workflow is blocked after configuration changes

Cause: A file recorded in .forge/.config_lock changed after the last lock.

Solution:

Review the configuration changes.
Run frg config validate.
Run frg config lock.

--code requires at least one tracker (--issues or --tickets)

Cause: frg config init --code was run without a tracker option.

Solution:

Add --issues <TOOL> or --tickets <TOOL>, for example:

bash

frg config init --issues github_issues --code github

The agent is not installed or not authenticated

Cause: The selected agent CLI is not installed, not on PATH, or not signed in. frg config validate reports, for example, GitHub Copilot CLI is not installed.

Solution:

Follow Agent Setup.
Run frg status.