Agent-agnostic loop engineering for projects that must be played with, tested, repaired, verified, and improved until they are actually healthy.

A loop is not a timer. A real loop knows the current process, PID, log path, step, speed, ETA, verifier result, baseline result, and when to stop.

OpenLoop is a small Python toolkit and prompt pack for building monitored feedback loops around any software agent. It turns vague requests such as “keep trying, find bugs, fix them, and do not stop until the project works” into a concrete workspace with state, logs, verification gates, baseline checks, circuit breakers, and reproducible reports.

OpenLoop does not depend on a specific model, editor, IDE, or agent platform. Any agent that can be called from a shell command can be plugged into commands.fix or commands.improve.

Mission
  ↓
Play / use the project
  ↓
Scan for bugs
  ↓
Repair through any agent or script
  ↓
Verify with deterministic checks
  ↓
Compare against baseline, if enabled
  ↓
Persist heartbeat, progress, logs, artifacts
  ↓
Continue, complete, or block safely

Every command can be a shell command: unit tests, browser tests, load tests, benchmark scripts, package checks, local agents, cloud agents, or custom repair scripts.

python -m venv .venv
source .venv/bin/activate
pip install -e .

openloop init .openloop/demo --project-root examples/demo_project \
  --mission "Keep the demo project working and above baseline"

cp examples/openloop.demo.json .openloop/demo/openloop.json
openloop doctor .openloop/demo
openloop run .openloop/demo --max-rounds 1
openloop status .openloop/demo

Without installing the package, run from the repo root:

PYTHONPATH=src python -m openloop --help
PYTHONPATH=src python -m openloop init .openloop/demo --project-root examples/demo_project

OpenLoop workspaces are driven by openloop.json:

{
  "version": 1,
  "mission": "Keep the project playable, verified, and above baseline.",
  "total_rounds": 3,
  "project_root": ".",
  "commands": {
    "play": "python app.py",
    "scan": "python -m unittest discover -s . -p 'test_*.py'",
    "fix": "your-agent-cli --workspace {project_root} --task 'Fix the latest failure in {workspace}'",
    "verify": "python -m unittest discover -s . -p 'test_*.py'",
    "improve": "your-agent-cli --workspace {project_root} --task 'Improve until baseline passes'"
  },
  "baseline": {
    "enabled": true,
    "command": "python benchmark.py",
    "metric_name": "score",
    "regex": "score=([0-9]+(?:\\.[0-9]+)?)",
    "value": 0.9,
    "direction": "greater_equal"
  },
  "limits": {
    "command_timeout_seconds": 900,
    "stall_timeout_seconds": 300,
    "max_consecutive_failures": 3
  }
}

Template variables available inside commands:

• {workspace}: absolute OpenLoop workspace path.
• {project_root}: absolute target project path.
• {round}: current round number.
• {last_error}: latest known failure string.

Environment variables injected into every command:

• OPENLOOP_WORKSPACE
• OPENLOOP_PROJECT_ROOT
• OPENLOOP_ROUND
• OPENLOOP_STEP

.openloop/my-task/
  openloop.json        # executable loop config
  mission.md           # objective, non-goals, definition of done
  loop_contract.md     # play → scan → fix → verify → baseline protocol
  eval_criteria.md     # machine-checkable completion and blocking rules
  heartbeat.json       # compact current state with PID/log/step/speed/ETA
  progress.md          # append-only timeline
  logs/                # raw command logs
  artifacts/           # per-round JSON reports
  knowledge/           # durable lessons and debugging notes
  output/              # user-defined outputs

openloop init WORKSPACE [--project-root PATH] [--mission TEXT] [--force]
openloop doctor WORKSPACE
openloop run WORKSPACE [--max-rounds N]
openloop status WORKSPACE [--json]

Creates the workspace files and directories.

Validates that the workspace and config are present.

Runs the monitored loop. Each command writes a dedicated log file. The heartbeat is updated before and after each command with the active process, PID, log path, current round, current step, recent speed, ETA, and normality.

Prints the latest heartbeat and validation state.

OpenLoop marks a mission complete only when:

1. the required verify command passes;
2. play and scan pass when configured;
3. the baseline metric passes when enabled;
4. no timeout, stall, OOM marker, or abnormal exit is present in the latest command result;
5. logs and artifacts have been written.

If repeated failures exceed limits.max_consecutive_failures, OpenLoop marks the workspace as blocked instead of retrying forever.

The file agent-instructions/OPENLOOP_AGENT.md contains a portable instruction block for any coding agent. Copy it into your agent’s project instructions when you want the agent to follow the OpenLoop monitoring-first workflow.

The file prompts/PROMPTS.md contains copy-paste prompts for creating and running loop workspaces.

scripts/run_tests.sh

or:

PYTHONPATH=src python -m unittest discover -s tests -p 'test_*.py'

• Native JSONL event stream for dashboards.
• Optional adapters for popular agent CLIs without making the core platform-specific.
• Browser-play mode with screenshot artifact capture.
• Built-in diff-size and changed-file policy gates.
• Multi-loop coordinator for independent tasks.
• Web UI for heartbeat, logs, and artifact review.

Project-owned logo assets are in assets/:

assets/openloop-logo.png          # README hero image
assets/openloop-social-preview.png # GitHub social preview
assets/openloop-mark.png          # square repository avatar
assets/openloop-icon.png          # small square icon
assets/openloop-logo.svg          # scalable wordmark
assets/openloop-mark.svg          # scalable mark

These assets are for OpenLoop project branding and do not use third-party product marks.

Apache-2.0. See LICENSE.