How it works

Self-driving runs one planner per repository per day. This page describes what that run does, the scouts it uses, and the codebase mapper that supports them.

The planner daily run

Once a day, in your configured timezone, Coldtea starts a planner run for each repository that has self-driving running. The run is pinned to your local calendar day, so a re-trigger for the same day does not start a second run.

A run moves through three states:

• Scanning: the planner has chosen its scouts and they are looking for work.
• Ready: the scouts have settled and the planner has ranked and filed tasks.
• Done: the run is complete and the day's brief is written.

The planner does not invent work. It selects scouts, waits for their proposals, and then curates them: it removes duplicates by fingerprint, confirms the ones with real evidence, ranks what is left, and promotes the winners into tasks. Each task is sized, and the run stops filing once the day's capacity budget is spent. See settings and permissions for how sizing and the budget work.

Scouts

A scout is a focused agent the planner sends out to find work. Each scout writes proposals to a short-lived store, and the planner reviews them before anything becomes a task. A proposal always carries proof: an error, a failing test, a code reference, an analytics number, or a piece of feedback. A proposal with no evidence does not survive.

There are two kinds of scout: code scouts, which read the repository, and the signal scout, which reads connected providers.

Code scouts

Code scouts work from the repository itself and cite a precise location, shaped like path/from/root.ts:42, so the planner can check the claim.

• Diff scout: reads recent changes to the repository. It looks at what moved lately and proposes follow-up work tied to those changes.
• Slice scout: reads one area of the codebase at a time. It works through a slice the codebase mapper has identified and proposes work within it.

Signal scout

The signal scout reads the observability and deploy providers you have connected, such as error tracking, analytics, and deployments. Its proposals cite the source signals they came from, and can carry an impact estimate: how many users are affected, an event count, a window, and whether the trend is rising, flat, or falling.

The signal scout only has something to read once you connect signals. With no providers connected, the planner still runs the code scouts and plans from the code alone.

The codebase mapper

The scouts and the planner need to know what the repository is before they can reason about it. The codebase mapper builds and keeps that picture.

The mapper clones the repository and produces a map of it:

• The kind of repository: a single app, a monorepo, a library, or other.
• The areas inside it, each with a path, a kind (web app, backend service, package, docs, infra, and so on), the languages and frameworks it uses, and a criticality from critical down to low.
• The signals it can see and how well the code is set up to capture server errors, client errors, and product analytics.

The map runs when self-driving is first set up for a repository, refreshes on a monthly schedule, and can be rebuilt on demand. Each run updates the existing map rather than replacing it wholesale, so notes and history carry forward.

Because the map records which areas are critical, the planner can weight work toward the parts of the repository that matter most.

What a run leaves behind

A finished run leaves a record you can read: the scouts it ran and what each found, the tasks it filed, and the day's brief. Any task the planner starts runs as a cloud run, so you can open the task and use View session, or Watch live while it is still going, to see exactly what the agent did. Review it the way you would review any agent work. Nothing merges without you.