Build & run configs

Define how to build and start your app, then launch it from Tegment or an agent.

Last updated Jul 19, 2026

A build & run config describes how to build and start your app. Once defined, you can launch it from Tegment with Ctrl+Shift+R, stop it, and read its logs — and an agent can do the same over the MCP server.

You create them in the app — open the project's settings and add a build & run config. Tegment saves them to .tegment/launch.config in your repo, so they're shared with everyone who opens the project. You don't have to write that file by hand; the format below is just for reference.

.tegment/launch.configjson

{
  "buildRunConfigs": [
    {
      "id": "web",
      "name": "Web app",
      "buildCommand": "npm run build",
      "runCommand": "npm run dev",
      "workingDirOffset": "packages/web",
      "showLogOnStart": true,
      "order": 0
    }
  ]
}

Field	Required	Description
`name`	yes	Label shown in the runner and the launch picker.
`runCommand`	yes	The command that starts the app.
`buildCommand`	no	Runs before `runCommand`; skip it if there's nothing to build.
`workingDirOffset`	no	Where the commands run, relative to the worktree root. Leave it out to run from the root.
`showLogOnStart`	no	Open the log view automatically when the app starts.
`id`	no	A stable id so a running instance is still recognized after a reload.
`order`	no	Sorts configs in the picker.

Tegment starts the app in the active worktree, tracks whether it's running, and captures its output so you can tail it without hunting for a terminal.

Running from a subdirectory#

By default the build and run commands both start at the worktree root. Set a Working directory on the config to start them somewhere below it instead, which is what you want when the app lives in a package inside a monorepo. It takes a relative path such as packages/web; absolute paths and parent traversal (..) are rejected as you type.

The offset applies to both the build and the run phase, and a restart re-applies it to the worktree root rather than stacking on top of the previous run.

From an agent#

When the MCP server is set up, these same configs are what list_app_configs, start_app, stop_app, get_app_status, and get_app_output operate on — so an agent can start your dev server, check that it came up, and read the logs on its own. See MCP server.