Toolchain Configuration

Updated on Oct 1, 2026

The toolchain tells AI agents which issue tracker, ticket tracker, code platform, and security scanner your project uses, and how to reach each one. This page shows how to create .forge/config/toolchain.toml, choose tools and access methods, and describe custom or on-premises tools.

The toolchain only describes tools to the agent. It does not install CLIs, start MCP servers, or create credentials.

Prerequisites

Forge is initialized in the project. See Project Setup.
Any CLI, MCP server, or API token that a tool definition references is installed and authenticated.

Create the toolchain

Generate toolchain.toml with frg config init. Pass a code platform and at least one tracker:

bash

frg config init --issues github_issues --code github
frg config init --tickets jira --code github --scanner polaris

Option	Values
`--issues <TOOL>`	`github_issues`, `jira`, `azure_devops`, `shortcut`, `local`
`--tickets <TOOL>`	`github_issues`, `jira`, `azure_devops`, `shortcut`, `local`
`--code <TOOL>`	`github`, `github_enterprise`, `bitbucket`, `azure_devops`, `local`
`--scanner <TOOL>`	`polaris`, `github_sast`

--code is required when you configure a toolchain, and it requires --issues or --tickets.
Built-in tools are generated with method = "skill", and Forge exports the matching skills to .agents/skills/.
The generated file includes commented description blocks for the CLI, MCP, and API methods, so you can switch methods by editing the file.
To replace an existing toolchain.toml, add --force. See Project Setup.

File structure

toml

schema_version = "1.0.0"

[issue_tracker]
name = "github_issues"
type = "built-in"
method = "skill"

[code_platform]
name = "github"
type = "built-in"
method = "skill"

# Optional
[ticket_tracker]
name = "jira"
type = "built-in"
method = "cli"

# Optional
[security_scanner]
name = "polaris"
type = "built-in"
method = "skill"

Configure one [code_platform], at least one of [issue_tracker] or [ticket_tracker], and at most one of each table.

Tool fields

Field	Required	Description
`name`	Yes	Built-in tool name, or your own name for a custom tool
`type`	Yes	`built-in` or `custom`
`method`	Yes	`skill`, `cli`, `mcp`, `api`, or `local`
`description`	Custom tools only	Instructions for the agent, up to 2,000 characters. Built-in tools have default descriptions.
`repository`	No	Repository URL when the tool targets a different repository than the current one
`skill_name`	No	Skill directory for a tool with `method = "skill"`. Defaults to the tool `name`.

A custom tool cannot reuse a built-in tool name. A description cannot contain shell substitution such as ${VALUE}.

Built-in tools and methods

Table	Tool names	Methods
`issue_tracker`	`github_issues`, `jira`, `azure_devops`, `shortcut`	`skill`, `cli`, `mcp`, `api`
`ticket_tracker`	`github_issues`, `jira`, `azure_devops`, `shortcut`	`skill`, `cli`, `mcp`, `api`
`code_platform`	`github`, `github_enterprise`, `bitbucket`, `azure_devops`	`skill`, `cli`, `mcp`, `api`
`issue_tracker`, `ticket_tracker`, `code_platform`	`local`	`local`
`security_scanner`	`polaris`, `github_sast`	`skill`, `cli`, `mcp`, `api`

Issue trackers hold development tasks. Ticket trackers hold customer-facing support or RFA work. For the skill each tool uses, see Agent Skills.

Access methods

Method	How the agent reaches the tool	Use when
`skill`	Loads a skill from `.agents/skills/<skill-name>/`	Default. Keeps prompts short and lets you customize instructions.
`cli`	Runs CLI commands, such as `gh issue view`	You want explicit CLI instructions
`mcp`	Uses a Model Context Protocol server	Your agent has an MCP server for the tool
`api`	Calls a REST API with a token such as `FORGE_ISSUE_TOKEN` or `FORGE_CODE_TOKEN`	You prefer direct API access
`local`	Reads local files and Git branches	No external system is available

Examples

Mixed methods

toml

schema_version = "1.0.0"

[issue_tracker]
name = "jira"
type = "built-in"
method = "skill"

[code_platform]
name = "github"
type = "built-in"
method = "cli"

Local mode

toml

schema_version = "1.0.0"

[issue_tracker]
name = "local"
type = "built-in"
method = "local"

[code_platform]
name = "local"
type = "built-in"
method = "local"

The local issue tracker reads .forge/work/job_<issue_id>/issue/issue.md.
The local code platform uses local Git branches.
Set the issue ID with FORGE_ISSUE_ID or frg config set-issue <ISSUE_ID>.

You can combine a local issue tracker with a hosted code platform, such as github. See Local Mode.

Separate issue and code repositories

Set repository when issues live in another repository, for example in a fork workflow:

toml

schema_version = "1.0.0"

[issue_tracker]
name = "github_issues"
type = "built-in"
method = "cli"
repository = "https://github.com/upstream-org/project.git"

[code_platform]
name = "github"
type = "built-in"
method = "cli"
# No repository: Forge detects it from the Git remote

Set repository on both tables to keep public issues and private code in different repositories. Make sure your credentials can access every repository you name.

Custom description for a built-in tool

toml

[issue_tracker]
name = "github_issues"
type = "built-in"
method = "cli"
description = """
GitHub Issues on github.mycompany.com, accessed with the gh CLI.
Use 'gh issue view <number>' to read issues.
Authentication: run 'gh auth login --hostname github.mycompany.com'.
"""

Custom on-premises tool

toml

[issue_tracker]
name = "jira-onprem"
type = "custom"
method = "api"
description = """
Jira on-premises at https://jira.mycompany.com/rest/api/2.
Read the token from the FORGE_ISSUE_TOKEN environment variable.
View issue: GET /rest/api/2/issue/{issueKey}
Search issues: POST /rest/api/2/search with a JQL query
"""

[code_platform]
name = "github"
type = "built-in"
method = "cli"

For a custom tool that uses a skill, see Agent Skills.

Warning: Descriptions are sent to the agent as prompt text. Reference credentials by environment variable name; never paste secrets into toolchain.toml.

How Forge uses the toolchain

Forge turns the toolchain into a # Development Toolchain section in the prompt. For a built-in tool, it uses the first description available:

The description in toolchain.toml
The built-in description for the selected method
The generic built-in description

Custom prompts can reference toolchain values with placeholders:

Placeholder	Value
`{{issue_tracker_name}}`, `{{issue_tracker_method}}`, `{{issue_tracker_description}}`	Issue tracker values
`{{ticket_tracker_name}}`, `{{ticket_tracker_method}}`, `{{ticket_tracker_description}}`	Ticket tracker values
`{{code_platform_name}}`, `{{code_platform_method}}`, `{{code_platform_description}}`	Code platform values
`{{security_scanner_name}}`, `{{security_scanner_method}}`, `{{security_scanner_description}}`	Security scanner values
`{{issue_tracker_repo_owner}}`, `{{issue_tracker_repo_name}}`, `{{issue_tracker_repo_slug}}`	Repository values, when available. Equivalent placeholders exist for the code platform.

toolchain.toml supports hierarchical loading. Toolchain values merge per table. See Hierarchical Configuration.

Validate and lock

bash

frg config validate
frg config lock

Run frg config lock again after every change, so the lock matches the current files.

Troubleshooting

toolchain.toml is required. Run 'frg config init --issues --code ' to create it.

Cause: A command needs the toolchain, but .forge/config/toolchain.toml does not exist.

Solution:

Run frg config init --issues <TOOL> --code <TOOL>.

--code flag is required when configuring toolchain

Cause: frg config init received a tracker or scanner option without --code.

Solution:

Add --code <TOOL>, for example frg config init --issues local --code local.

At least one of issue_tracker or ticket_tracker must be configured

Cause: toolchain.toml has no [issue_tracker] or [ticket_tracker] table.

Solution:

Add at least one tracker table.
Run frg config validate.

Custom '' must have a description

Cause: A type = "custom" tool has no description.

Solution:

Add a description that tells the agent how to use the tool.

Unknown built-in : ''

Cause: The name is not in the built-in catalog.

Solution:

Correct the name using the built-in tools table, or
Set type = "custom", choose a name that is not a built-in name, and add a description.

Tool '' description exceeds maximum length of 2000 characters

Cause: The description is longer than 2,000 characters.

Solution:

Shorten the description. Move long instructions into a skill.

Tool '' description contains unsafe shell variable substitution: ${...}

Cause: The description contains ${...}.

Solution:

Remove the substitution. Name the environment variable in plain text instead.

toolchain.toml shows as absent although the file exists

Cause: The file could not be loaded, for example because method has an unsupported value.

Solution:

Check type and method against the tables on this page.
Run frg config validate and confirm that the file shows valid (Repo).