---
title: "Runs and the project kit"
description: "How the project kit sets up a plan, and how a bounded run claims tasks, records decisions and stops at its budgets."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.overlane.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Runs and the project kit

The **project kit** is a plan in your repository (`.overlane/plan/`), plus instruction blocks and CI, that lets an agent work through tasks unattended. A **run** is one bounded pass: it checks the run policy, claims a task, and ends with a record.

## Set up the kit

```sh
overlane connect --kit existing --dry-run
overlane connect --kit new --goal "Build a link shortener" --yes
```

With `--kit existing|new`, [`overlane connect`](/cli/connect/) also drafts the plan files, CI and a pull request. `--goal` is required with `--kit new`. Preview first; nothing is written under `--dry-run`.

## The agent loop

```sh
overlane run next
# do the work the task describes, then commit it
overlane run next
```

[`run next`](/cli/run-next/) is one step of the loop, the same for Claude Code, Codex or a scheduled cloud run:

1. It starts a run when this working copy has none.
2. If this working copy holds a task, it runs each of the task's verification commands on the committed work. A failure stops here and the task stays yours: fix it, commit, run `run next` again.
3. When every command passes, it submits the task, records each result as evidence, pushes the branch (`overlane/<task>` when you are on the default branch) and opens the pull request through the project's GitHub App. The task closes only when that evidence verifies it; a check that needs CI keeps it open until CI passes.
4. It claims the next runnable task in one step and prints its contract and verification commands.

Two agents running `run next` at the same moment never get the same task, and a task whose dependencies are not verified is never handed out: claiming it by name is refused too. When nothing is left, or a budget is spent, it exits 6 with the `run end` command to finish with.

## A run, step by step

```sh
overlane run start --trigger schedule
overlane run claim
overlane run decide --question "Which test runner?" --decision "Vitest" --evidence "package.json"
overlane run end --reason nothing_runnable
```

- [`run start`](/cli/run-start/) checks the run policy and starts one run, recorded in `.overlane/state/run.json`. A stop (policy paused, a budget spent, nothing runnable) exits 6, with the reason in the error code and the exact `run end` command as the hint.
- [`run claim`](/cli/run-claim/) claims the next runnable task, or a named one, and prints its contract and verification commands.
- [`run decide`](/cli/run-decide/) records a question, the decision taken and its evidence, so the run continues without waiting for an answer.
- [`run end`](/cli/run-end/) ends the run and releases its leases. Run it even when stopping early.

## Look and control

```sh
overlane run status
overlane run pause
overlane run resume
```

[`run status`](/cli/run-status/) reports the policy, this working copy's budgets and the next runnable task. [`run pause`](/cli/run-pause/) stops every run at its next check, and [`run resume`](/cli/run-resume/) undoes it. Loops that start runs on a schedule or an event are in [Loops](/issues/loops/).

Source: https://docs.overlane.app/runs-and-kit/index.mdx