thu-nmrc/openloop

OpenLoop is a small Python toolkit for wrapping any AI agent in a monitored feedback loop. The idea is that instead of telling an agent to keep trying until something works, you set up a workspace that tracks exactly what the agent is doing, when each step succeeds or fails, and when it should stop. The core loop goes through a fixed sequence: run the project to see if it works, scan for bugs, attempt a fix via any shell command or agent, verify the result with automated checks, optionally compare against a performance baseline, then write a summary and either continue or stop. All of these steps are configured in a single JSON file where you specify what command to run at each stage. A key design choice is that OpenLoop does not tie you to any specific AI model or editor. The fix and improve steps are just shell commands, so you can plug in any agent that runs from a terminal. Each command gets its own log file, and the current state, including which process is running, how far along it is, and what went wrong last, is always written to a compact JSON file called a heartbeat. The toolkit also includes guardrails to prevent runaway behavior: timeouts, stall detection, a circuit breaker that marks the task as blocked if too many consecutive steps fail, and baseline checks that require a measurable score to stay above a threshold before the loop treats anything as done. The project ships with a CLI that handles initializing a workspace, validating the configuration, running the loop, and printing current status. It is in alpha and works on Python 3.11 or later.