Build & run configs

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

Last updated Sep 10, 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.

Stopping an app#

Stopping an app sends it Ctrl+C, the same as pressing it in a terminal, and waits up to ten seconds for it to exit. That gives it time to run its own shutdown, so whatever it started outside itself, such as a database container, is stopped with it instead of left running.

If the app is still running after ten seconds, Tegment terminates it and tells you so, since its shutdown didn't get to run. Every way of stopping an app works like this: the stop button, a restart, and an agent calling stop_app.

Two exceptions: with cmd.exe as your shell, a stop always takes the full ten seconds, because Tegment can't see the app exit there. And quitting Tegment still stops running apps straight away.

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.