How a build actually runs

The shape of it

Connecting the terminal

In a linked folder, run it and leave it up. Ctrl-C stops it, and the failure mode of stopping is that nothing happens — the only correct one for a thing that runs an agent on your computer.

graph agent

A folder holds one runner at a time. A second graph agent in the same directory refuses rather than starting, so two agents can never edit the same files at once.

The board shows what is connected. When the indicator is green, Execute has somewhere to go; when it is not, the button says so rather than queueing work nobody will claim.

Which agent writes the code

Graphlit does not ship a coding model of its own for this step and does not call one over an API. It shells the coding CLI already installed on your machine, in your project folder, headless.

• It uses your own login. Whatever subscription or key that CLI is already signed in with is what pays and what the run is attributed to. Graphlit does not need a model key for this step, and does not have one.
• `--permission-mode acceptEdits` is not optional. Without it the agent stops to ask for an approval nobody is sitting at the terminal to give, and the run hits its timeout looking exactly like a hang.
• *Every `VIPL_` variable is stripped** from the child's environment. Your agent gets your shell, not this process's credentials.
• It runs in the linked folder, so the agent sees your real tree — your AGENTS.md, your lockfile, the code the last task wrote.
• If the binary is missing the task fails immediately with `claude` is not installed on this machine — install it and press Execute again, rather than timing out fifteen minutes later.
• If `git` is missing the build still runs and warns that changes will not be committed.

What the runner does with the folder

1. 01Syncs, if the folder is empty. A freshly scaffolded project is pulled down once as a zip — source, not node_modules.
2. 02Renders the goal from the state your machine currently holds, so it reflects what earlier tasks already built rather than what the plan predicted.
3. 03Runs the agent with a timeout — fifteen minutes by default. That is generous on purpose: the thing being guarded against is a wedged process, not a slow one.
4. 04Compares what changed against the files the task owns.
5. 05Commits with a subject naming the task, using your git identity when it is set.
6. 06Reports the verdict, the files, and the commit sha.

The scope guard

Each task owns a set of nodes, and each node maps to files. After the agent stops, the runner diffs the folder and checks what actually moved. A task that edits a file outside its own scope does not silently pass — the run is reported with the violation named, and the commit is there to look at or put back.

  ✗ t002 did not pass.
    It changed files the task does not own: prisma/migrations/20260820000000_init/migration.sql

  Look at it:  git show a7f17a95
  Put it back: graph undo
  Try again:   graph run t002

Building without the board

graph run builds one task in this folder, now, through the same path the runner uses — same goal, same scope enforcement, same commit, same report. No browser needed, and the board still finds out because the result is pushed to it.

graph run              # the next unblocked task
graph run t004         # a specific one
graph run --all        # the rest of the plan, task after task
graph run --force      # even though something it depends on is unfinished

Undoing a build

graph undo reverts the last build commit and puts its task back to pending, so the plan is runnable again. It shows you what it is about to undo and asks first.

Choosing the agent, once

Anything you would otherwise pass as a flag every time is a setting. graph config prints all of them, their values, and which layer decided — because a value that is set here and overridden by an environment variable looks, from every other command, like configuration being ignored.