docs/configuration.md

Configuration reference (loop.yaml)

Paths are relative to the folder containing loop.yaml. Durations use Go syntax (45m, 1h30m, 90s).

Top level

repo

Set GITHUB_API_URL for GitHub Enterprise.

sources

An ordered list. Order matters: it is the pick-up order.

Common keys:

type: markdown

Frontmatter keys: id, title, status (open, in-progress, closed), created, labels, depends_on, model, loop_run. Without a title the first # heading or the file name is used. Claiming writes status: in-progress and loop_run; closing writes status: closed and closed_note. These edits touch only the keys loop owns: every other key keeps its position, quoting and comments, and a file without frontmatter gets a minimal one. Loop notes are appended under a ## Loop log heading.

type: github

Claiming adds the label and a comment with the run id. Closing happens through Closes #n in the PR body or explicitly after the merge.

type: jira

Credentials: JIRA_EMAIL + JIRA_API_TOKEN (Cloud, basic auth) or JIRA_TOKEN (bearer, Server/Data Center).

prompts

Paths to template files; missing keys use the built-in defaults (loop init writes copies to prompts/).

See prompts.md.

agent

Permissions in headless sessions

A headless claude -p session cannot ask for permission: a tool call the rules do not allow is denied, and an agent that cannot run the tests or commit stalls or gives up. Before every session loop writes <workdir>/.claude/settings.local.json (kept out of git) with permission_mode as the default mode and the allow and deny rules, so the headless session and anyone who later joins it with loop join get the same rules.

The defaults allow the git commands needed to inspect and commit work and deny git push, gh pr, gh api and git reset --hard, because pushing and opening the PR is loop’s job. The defaults contain nothing project specific, so add the commands your verify steps and your agent need:

agent:
  permission_mode: acceptEdits
  allow:
    - "Bash(npm test:*)"
    - "Bash(npm run lint:*)"
    - "Bash(go test:*)"

Setting allow replaces the defaults; include the git rules you still want. permission_mode: bypassPermissions skips all checks and is the quickest way to get a first run going in a sandbox, at the cost of the agent being able to run anything. loop doctor warns when only the default rules are configured. The Cursor runner always runs with --force, which is Cursor’s equivalent of bypassing permissions.

Environment of a session

Agent sessions do not inherit loop’s whole environment. They get an allowlist: shell and locale basics, proxy settings, git identity variables, the toolchain variables of Go, Node, Rust, Java and Python, the agent CLIs’ own configuration and credentials (ANTHROPIC_*, CLAUDE_*, CURSOR_*), the LOOP_* variables and agent.env. GITHUB_TOKEN, GH_TOKEN, JIRA_* and anything else are withheld, so an agent cannot push, merge or comment with loop’s credentials. Name what else your project needs in env_passthrough:

agent:
  env_passthrough: [DATABASE_URL, "MY_APP_*"]

run: and script: steps are your own scripts and keep the full environment; agent: steps are sessions and get the allowlist.

How the prompt reaches the agent: claude receives it on standard input with a pre-assigned session id. agent (Cursor) receives short prompts as the positional argument; long ones (over 16 KiB, typical for tickets with comment threads) are piped on standard input while the positional argument points at the prompt file in the run folder, so the command line never exceeds the operating system’s argument limit.

steps

Everything loop runs around a session is a step list in loop.yaml. There are no hidden hook directories and no global configuration. Each step is exactly one of:

Optional keys: name, model and timeout (agent steps).

steps:
  setup:
    - script: hooks/setup.sh
    - run: npm ci
  verify:
    - name: tests
      run: npm test
    - name: self-review
      agent: prompts/self-review.md
  merged:
    - run: echo "merged $LOOP_PR_URL" >> "$LOOP_PROJECT_DIR/merged.log"
  blocked:
    - script: hooks/notify-slack.sh   # reads LOOP_RUN_ERROR and LOOP_PR_URL
  failed:
    - script: hooks/notify-slack.sh

Steps see this environment: LOOP_PROJECT, LOOP_PROJECT_DIR, LOOP_WORKDIR, LOOP_BRANCH, LOOP_BASE, LOOP_ITEM_ID, LOOP_ITEM_TITLE, LOOP_ITEM_URL, LOOP_RUN_ID, LOOP_RUN_DIR, LOOP_SUMMARY_FILE, LOOP_PR_URL, LOOP_PR_NUMBER, LOOP_RUN_PHASE, LOOP_RUN_ERROR (the reason a run parked), plus agent.env.

pr

workflow

Run state

Each run lives in .loop/runs/<run id>/: