---
title: "overlane run loop"
description: "Run tasks overnight through Claude Code, Codex, Gemini CLI or Cursor, handing off when one hits its usage limit"
---

> 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.

# overlane run loop

{/* Generated by apps/docs/scripts/generate.mjs (CLI pages from the command registry in packages/cli). Do not edit; run `pnpm --filter @overlane/docs gen`. */}

Runs on your machine, in this working copy, under the clients you have signed in to. Each iteration picks the next runnable task and the next eligible client by your usage policy, puts the working copy on wip/\<task-id\>, and starts that client headless with the fixed run-step instruction. The loop renews the child's lease while it works, reports how each iteration ended, and when a client stops on a usage limit it writes the checkpoint, pauses the task and hands it to the next client on the policy's list. The same failure three times in a row, or three iterations with no progress, pauses the task as stuck. The loop ends at the first of 20 iterations, 7:00 local time, three iterations in a row with nothing verified, a spent budget, a paused policy, or nothing runnable until the end time, and then prints the morning report and puts it in your inbox. Clients start with a scrubbed environment and one project token that lives at most 12 hours; nothing is merged, and Gemini CLI runs only on your own API key or Vertex project. Exit 0 when the night ended on its end time or iteration limit; 6 for a paused policy, a spent budget, nothing runnable or no progress; 5 for a working copy with uncommitted changes or no signed-in client.

## Usage

```sh
overlane run loop [--until TIME] [--max-iterations N] [--idle-limit N] [--executor NAME...] [--dry-run]
```

## Flags

| Flag | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--until` | string | no |  | When the loop ends: a local time such as 06:30, a span such as 8h, or an ISO time (default: the next 7:00 local) |
| `--max-iterations` | string | no |  | Iterations before the loop ends (default 20) |
| `--idle-limit` | string | no |  | Iterations in a row with nothing verified before the loop ends (default 3) |
| `--executor` | string (repeatable) | no |  | Use only these clients, in this order: claude-code, codex, gemini-cli, cursor (default: the policy's list) |
| `--dry-run` | boolean | no |  | Print the requests and file changes this command would make, then stop. Needs no credentials. |

## Examples

```sh
overlane run loop
overlane run loop --until 06:30 --executor claude-code --executor codex
overlane run loop --dry-run
```

## Behavior

- Effect: `write` (changes local or hosted state).
- Needs credentials: yes. Uses the network: yes.
- Supports `--dry-run`: yes. Accepts `--force`: no.
- Machine-readable description: `overlane schema run loop`.

## Result

With `--json` (the default when stdout is not a terminal) the command prints this JSON Schema's shape on stdout.

```json
{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "stop": {
          "type": "string",
          "enum": [
            "max_iterations",
            "end_time",
            "no_progress",
            "budget",
            "paused",
            "nothing_runnable",
            "dirty_working_tree",
            "signed_out",
            "error"
          ]
        },
        "detail": {
          "type": "string"
        },
        "iterations": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991
        },
        "verified": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "handoffs": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "taskId": {
                "type": "string"
              },
              "from": {
                "type": "string"
              },
              "to": {
                "type": "string"
              }
            },
            "required": [
              "taskId",
              "from",
              "to"
            ],
            "additionalProperties": false
          }
        },
        "held": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "taskId": {
                "type": "string"
              },
              "reason": {
                "type": "string",
                "enum": [
                  "stuck",
                  "ceiling"
                ]
              },
              "detail": {
                "type": "string"
              }
            },
            "required": [
              "taskId",
              "reason",
              "detail"
            ],
            "additionalProperties": false
          }
        },
        "quota": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "taskId": {
                "type": "string"
              },
              "executor": {
                "type": "string"
              },
              "resetsAt": {
                "type": "string"
              }
            },
            "required": [
              "taskId",
              "executor"
            ],
            "additionalProperties": false
          }
        },
        "reaped": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "cooledForLoop": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "report": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "stop",
        "detail",
        "iterations",
        "verified",
        "handoffs",
        "held",
        "quota",
        "reaped",
        "cooledForLoop",
        "report"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "dryRun": {
          "type": "boolean",
          "const": true
        },
        "service": {
          "type": "string"
        },
        "requests": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "method": {
                "type": "string"
              },
              "path": {
                "type": "string"
              },
              "body": {},
              "note": {
                "type": "string"
              }
            },
            "required": [
              "method",
              "path"
            ],
            "additionalProperties": false
          }
        },
        "commands": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "writes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "path": {
                "type": "string"
              },
              "action": {
                "type": "string",
                "enum": [
                  "write",
                  "append",
                  "delete"
                ]
              },
              "description": {
                "type": "string"
              }
            },
            "required": [
              "path",
              "action",
              "description"
            ],
            "additionalProperties": false
          }
        },
        "notes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "dryRun",
        "requests",
        "commands",
        "writes",
        "notes"
      ],
      "additionalProperties": false
    }
  ]
}
```

See [exit codes](/cli/#exit-codes) for the status the process returns.

Source: https://docs.overlane.app/cli/run-loop/index.mdx