Tasks runner

Tasks are named shell commands you define per project. They show up in the command palette, run in dedicated terminal sessions, and the agent can invoke them too.

Where they live

<project>/.forge/tasks.toml. Forge creates a starter file the first time you open a project.

Format

[[task]]
id = "dev"
label = "Start dev server"
command = "pnpm dev"
shell = "powershell"  # optional

[[task]]
id = "test"
label = "Run tests"
command = "pnpm test"

[[task]]
id = "build"
label = "Production build"
command = "pnpm build"

Each [[task]] table has:

• id: a stable identifier. Used by the agent and as the task’s slug in the palette.
• label: the human-readable name shown in the palette.
• command: the shell command. Multi-line is fine.
• shell: optional override for which shell runs the command (powershell, cmd, bash, wsl). Defaults to your system primary shell.

Older docs and snippets sometimes show [[tasks]] (plural) with name = .... The current Forge parser expects [[task]] (singular) with id = .... If you copied an old example, rename the table and the field.

There’s also a special [preview] section for the Web preview tab.

Running a task

Open the command palette with Ctrl+Shift+P. Tasks appear as Task: <label> entries:

Task: Start dev server
Task: Run tests
Task: Production build

Pick one. Forge spawns a new terminal session and pre-loads the command. The session is a real PTY, so interactive tools (REPLs, prompts, watch modes) work normally.

The terminal session lives in the bottom panel. If the panel is hidden, the task still runs; the panel pops open the first time output arrives.

Auto-submit timing

After the task command is typed into the terminal, Forge waits 200 ms and then sends Enter automatically. This is a heuristic to give the shell time to print its prompt before the command fires. If you have an unusually slow shell startup, you’ll occasionally need to press Enter manually.

The agent and tasks

In Act mode, the agent can invoke tasks directly. Tell it to run the test suite and it picks the right Task: ... entry and executes it. Output streams back into the chat as a tool-call result.

In Plan or Ask mode, the agent can list and describe tasks but won’t run them. Switch to Act when you want the agent driving.

Engine integrations

Forge sets a few environment variables automatically when it detects an engine:

• UNITY_PATH (Unity projects) points at the Editor binary.
• GODOT (Godot projects, after you set the binary in Settings → Workspace) points at the Godot binary.

Use them in tasks for headless builds:

[[task]]
id = "build-windows"
label = "Build Windows"
shell = "powershell"
command = '& "$env:UNITY_PATH" -batchmode -nographics -quit -projectPath . -executeMethod ForgeBuild.BuildWindows -logFile -'

[[task]]
id = "godot-export-web"
label = "Export HTML5 build"
shell = "powershell"
command = '& "$env:GODOT" --headless --export-release "Web" .build/web/index.html'

Notes

• Terminal sessions persist when you toggle the bottom panel. Closing a session (× on its tab) terminates the underlying process.
• Per-project terminal cwds are remembered in workspace.json and restored when you reopen the project.
• Long-running tasks (dev servers, watch modes) keep running until you close the terminal session or stop them with Ctrl+C.