@0xtiby/looper

What Is Looper?

A standalone engine for looping an AI coding CLI against a prompt until it signals it's done:

1. You give Looper a prompt and pick a CLI (claude, codex, opencode, or pi).
2. Looper spawns the CLI, streams its output, and watches for a sentinel string.
3. It re-spawns from scratch each iteration until the sentinel fires, maxIterations is reached, or the CLI exits non-zero.

Looper is stateless — every iteration is a fresh spawn with no shared conversation state. It has no opinions about specs, plans, trackers, git, or project structure. The prompt is the instruction.

Under the hood, Looper drives the CLIs via @0xtiby/spawner.

Prerequisites

• Node.js 20+
• At least one supported AI CLI installed and authenticated:
  • Claude Code (claude)
  • Codex CLI (codex)
  • OpenCode (opencode)
  • pi (pi)

Quick start

1. Install the package:

   pnpm add @0xtiby/looper
   # or: npm install @0xtiby/looper
   

2. Scaffold a .looper/config.json with sensible defaults:

   looper init
   

3. Run a loop with an inline prompt:

   looper run -p "Refactor src/auth to remove dead code. Emit :::LOOPER_DONE::: when finished."
   

The package ships both a looper binary and a library (import { loop } from "@0xtiby/looper"). Both ESM and CommonJS are supported.

CLI

looper init

Creates .looper/config.json populated with the built-in defaults.

looper config

Prints the resolved config (defaults merged with your file).

looper run

Runs a loop. Exits 0 on clean completion, non-zero on CLI error, and 130 on SIGINT (Ctrl+C).

# Inline prompt, or a path to a file (auto-detected)
looper run -p ./plan.md --cli claude --max-iterations 5

# Or pipe in
cat plan.md | looper run --prompt-stdin

Flag	Description
-p, --prompt <value>	Inline string OR path to an existing file (auto-detected).
--prompt-stdin	Read the prompt from stdin.
--cli <name>	One of claude, codex, opencode, pi. Overrides config.
--model <name>	Model override (e.g. opus, sonnet).
--max-iterations <n>	Cap the number of iterations.
--sentinel <string>	String the AI must emit to stop the loop.
--cwd <path>	Working directory passed to the spawned CLI.
--var KEY=VALUE	Template variable (repeatable — see Template variables).

looper resume

If a session is aborted with Ctrl+C, the session file is marked interrupted. Continue it with:

looper resume              # lists interrupted sessions
looper resume <session-id> # resumes the specific session

Resume reuses the original prompt, CLI, and model and runs the remaining iterations (up to maxIterations). New iterations are appended to both the session JSON and the transcript log. Stdin-origin prompts cannot be resumed.

Library usage

Basic

import { loop } from "@0xtiby/looper";

const result = await loop({
  cli: "claude",
  prompt: `
    1. Run: gh issue list --repo {{REPO}} --state open --json
    2. Pick the next unblocked issue labeled "ready".
    3. Implement it: write code, tests, commit, open a PR,
    4. Exit.
    When no unblocked issues remain, emit :::DONE:::
  `.trim(),
  cwd: process.cwd(),
  maxIterations: 20,
  sentinel: ":::DONE:::",
  vars: { REPO: "0xtiby/looper" },
});

console.log(result.stopReason); // "sentinel" | "max_iterations" | "error" | "aborted"

The library is stateless and does no file I/O. Callers own persistence; the looper CLI is a thin consumer of the library.

All options

import { loop } from "@0xtiby/looper";

const result = await loop({
  cli: "claude",
  prompt: "Fix the failing tests. Emit :::DONE::: when finished.",
  cwd: process.cwd(),
  model: "opus",
  maxIterations: 5,
  sentinel: ":::DONE:::",
  vars: { PROJECT: "my-app" },
  onOutput: (chunk) => process.stdout.write(chunk),
  signal: AbortSignal.timeout(60_000),
});

LoopOptions

Option	Type	Default	Description
cli	"claude" | "codex" | "opencode" | "pi"	—	Required. The AI CLI to spawn.
prompt	string	—	Required. Prompt string passed to the CLI.
cwd	string	process.cwd()	Working directory for the spawned CLI.
model	string	—	Model override (e.g. opus, sonnet).
maxIterations	number	10	Hard cap on iterations.
sentinel	string	":::LOOPER_DONE:::"	String the CLI must emit to end the loop.
vars	Record<string, string>	{}	Template variables for {{KEY}} substitution.
onOutput	(chunk: string) => void	—	Streaming callback for raw CLI stdout.
signal	AbortSignal	—	Aborts the loop between or during iterations.

LoopResult

Field	Type	Description
iterations	IterationResult[]	Per-iteration records, in order.
stopReason	StopReason	"sentinel" | "max_iterations" | "error" | "aborted".

IterationResult

Field	Type	Description
number	number	1-indexed iteration number.
exitCode	number	Exit code of the spawned CLI.
sentinelDetected	boolean	Whether the sentinel was observed in stdout.
stdout	string	Full captured stdout for the iteration.
startedAt	string	ISO timestamp.
durationMs	number	Wall-clock duration.
tokensIn	number	Input tokens reported by the CLI.
tokensOut	number	Output tokens reported by the CLI.

Template variables

Prompts can reference {{VAR}} placeholders. Substitution is flat (values are not themselves re-substituted). Unknown placeholders are left as-is.

Built-in variables:

Name	Value
ITERATION	Current iteration number (1-indexed).
MAX_ITERATIONS	Configured maxIterations.
SESSION_ID	UUID of the session (CLI only).

Precedence (higher wins): --var KEY=VALUE CLI flag → config vars → built-in.

Config (.looper/config.json)

{
  "cli": "claude",
  "model": "opus",
  "maxIterations": 10,
  "sentinel": ":::LOOPER_DONE:::",
  "vars": {}
}

All fields are optional. Missing fields fall back to the defaults shown above. CLI flags on looper run override the resolved config.

Sessions

Each looper run (and resume) writes two files under .looper/sessions/<uuid>:

• <uuid>.json — session metadata and per-iteration metrics.
• <uuid>.log — raw CLI stdout, separated by --- ITERATION N [ISO_TIMESTAMP] --- markers.

Session state machine: active → completed | interrupted. Session files are never auto-deleted.

Example session JSON:

{
  "id": "…",
  "prompt": "./plan.md",
  "cli": "claude",
  "model": "opus",
  "maxIterations": 10,
  "state": "completed",
  "startedAt": "2026-04-16T18:00:00.000Z",
  "completedAt": "2026-04-16T18:07:42.000Z",
  "stopReason": "sentinel",
  "iterations": [
    {
      "number": 1,
      "exitCode": 0,
      "durationMs": 45000,
      "tokensIn": 8000,
      "tokensOut": 12000,
      "sentinelDetected": true
    }
  ]
}

Pi integration

If you use pi, looper ships a built-in extension for fire-and-forget background runs inside Zellij panes or tmux sessions.

Install looper as a pi package:

pi install git:github.com/0xtiby/looper

Then in a pi session:

/looper-run

This opens an interactive wizard that walks you through picking a prompt (from .looper/*.md or writing a new one), choosing the AI CLI, and spawning looper in a background pane/session while you keep chatting with pi.

The LLM can also call the looper_run tool directly:

{
  "name": "looper_run",
  "parameters": {
    "prompt": "Refactor auth module. Emit :::LOOPER_DONE::: when finished.",
    "cli": "claude",
    "maxIterations": 5
  }
}

Features

• Auto-detects Zellij (preferred) or tmux
• Scans .looper/*.md for reusable prompts
• Zellij: pane direction and floating mode support
• tmux: new detached sessions

License

MIT