Metadata-Version: 2.4
Name: loop-agent
Version: 1.1.0
Summary: loop-agent: an embeddable loop engine for agents (gather -> act -> verify -> repeat, with composable stop conditions, persisted state, limited human gates, and an outer Reflexion loop).
Project-URL: Homepage, https://github.com/happy-ryo/loop-agent
Project-URL: Repository, https://github.com/happy-ryo/loop-agent
Project-URL: Changelog, https://github.com/happy-ryo/loop-agent/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/happy-ryo/loop-agent/issues
Author: happy-ryo
License: MIT License
        
        Copyright (c) 2026 happy-ryo
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent,agent-loop,agentic,human-in-the-loop,llm,loop,loop-engineering,observability,react,reflexion,self-improving
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: tomli>=1.1.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: opentelemetry-api>=1.20; extra == 'dev'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
Provides-Extra: redis
Requires-Dist: redis>=4.2; extra == 'redis'
Provides-Extra: test
Requires-Dist: opentelemetry-api>=1.20; extra == 'test'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'test'
Requires-Dist: pytest>=7; extra == 'test'
Description-Content-Type: text/markdown

# loop-agent

[![PyPI](https://img.shields.io/pypi/v/loop-agent.svg)](https://pypi.org/project/loop-agent/)
[![Python](https://img.shields.io/pypi/pyversions/loop-agent.svg)](https://pypi.org/project/loop-agent/)
[![CI](https://github.com/happy-ryo/loop-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/happy-ryo/loop-agent/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

loop-agent is a small Python runtime for practicing Loop Engineering. Inside an agent or an existing application, it runs the following process:

1. Use `gather` to retrieve the next task to work on
2. Use `act` to execute that task
3. Use `review` to accept or reject the artifact before verification
4. Use `verify` to validate the result against ground truth
5. If successful, end the loop; if not yet complete, continue to the next iteration
6. Stop when a limit is reached, such as the maximum number of iterations, time, budget, or stagnation

What matters in Loop Engineering is not having a person instruct an agent one step at a time, but designing the loop: what to gather, how to execute it, how to verify it, and when to stop.
loop-agent is the engine for running that loop. It lets users focus on the events inside the loop: what to work on, how to work on it, how to verify that it is complete, and under what conditions to stop when things are not going well.

A defining feature is that loops can be expressed as Python functions or through the CLI. You can have coding agents such as Claude Code or Codex implement and run loops for you. The loops they write remain as Python code, so you can inspect the code and deepen your understanding.

## What It Is For

Use loop-agent when you want to safely repeat processes like the following. The result of each iteration is kept in history, and the final result is returned as something like "succeeded", "stopped at a limit", or "stopped pending approval".

- Process accumulated GitHub issues
- Have a coding agent keep fixing code until tests pass
- Process multiple files one by one, recording each completed item
- Run an external CLI or model call, then move to the next attempt if it fails
- Persist long-running work in state.db and resume it after interruption
- Require manual approval only for irreversible operations such as commit / push

## Installation

```bash
pip install loop-agent
```

If you want coding agents such as Claude Code / Codex / Cursor to write loops for you, also install the skill for loop-agent.

```bash
loop-agent install-skills
loop-agent install-skills --target-agent codex
loop-agent install-skills --target-agent cursor
```

## Minimal Example

```python
from loop_agent import ActOutcome, MaxIterations, ReviewOutcome, VerifyOutcome, run_loop

n = {"value": 0}

def act(_ctx):
    n["value"] += 1
    return ActOutcome(observation=f"step {n['value']}")

def verify(_outcome):
    return VerifyOutcome(goal_met=n["value"] >= 3)

def review(_outcome):
    return ReviewOutcome(approved=True, feedback="small local loop")

result = run_loop(
    act=act,
    review=review,
    verify=verify,
    conditions=[MaxIterations(5)],
)

print(result.status, result.reason)
```

When `verify` returns `goal_met=True`, the loop stops as a success. Even if it does not succeed, stop conditions such as `MaxIterations` ensure that the loop will stop.

## Loop Components

A loop-agent loop is mainly composed of six elements.

| Name | Role |
|---|---|
| `gather` | Selects the next target to execute |
| `act` | Performs the actual work |
| `review` | Accepts or blocks the artifact before verification |
| `verify` | Checks whether the work succeeded |
| `conditions` | Stops based on count, time, budget, stagnation, and similar limits |
| `gate` | Inserts manual approval only for operations that need it |

If you omit `gather`, the current state is passed directly to `act`. `review` is required by the API; use `skip_review("reason")` only when artifact review is intentionally unnecessary, such as a tiny deterministic local loop.

## Create a Loop Template

You can generate a loop template from the CLI.

```bash
loop-agent init-harness --template light  --output ./harness-light
loop-agent init-harness --template claude --output ./harness-claude
loop-agent init-harness --template codex  --output ./harness-codex
```

This generates a short `harness.py` and README. After generation, edit the prompt, review policy, verification command, stop conditions, and targets for manual approval to fit your use case. Generated harnesses include a required review stub that blocks by default; set `SKIP_REVIEW=True` with a reason only when review is intentionally unnecessary. The Claude and Codex templates include resumable state, JSONL progress events, and a repeated-failure cutoff so long runs can be observed and resumed.

Reflexion is intentionally not in the starter harness. Start by making the inner
loop observable and verifiable. Add Reflexion after the run shows a repeated,
lesson-shaped failure; adding it before the prompt, verifier, and review are clear
can turn noisy first attempts into bad stored lessons.

## Using It with Coding Agents

loop-agent is also designed for workflows where coding agents such as Claude Code, Codex, or Cursor write loops from prompts like this:

```text
Using loop-agent, write a loop that fixes failing pytest tests.
For act, delegate the fixes to a coding agent, and for verify, judge success by the pytest exit code.
Stop after at most 5 attempts, and keep commit and push outside the loop.
```

Installing the skill makes it easier for coding agents to find loop-agent APIs and design patterns.

## Main Features

- Synchronous / asynchronous loop execution: `run_loop`, `async_run_loop`
- Stop conditions: maximum iterations, time, tokens, stagnation detection, and more
- Required artifact review with an explicit skip helper
- Verification helpers: `CommandVerifier`, `PytestVerifier`, `RegexVerifier`
- State recording and resume: progress file / state.db
- Manual approval: pause / resume only for irreversible operations
- Adapters: `ClaudeCodeAct`, `CodexAct`
- Processing multiple targets: `WorkListGather`
- Observation and operations: summary, dashboard, spike scan
- Outer improvement loop: Reflexion for repeated, lesson-shaped failures

## Fit Criteria

loop-agent is well suited to work whose completion can be judged mechanically, such as by tests or command results.

Good examples:

- `pytest` passes
- Only specific files have changed
- A command exits with code 0
- String or AST conditions are satisfied
- All N tasks become done

Poor fits:

- "Make the writing better"
- "Generally improve the quality"
- Work where success judgment depends on human intuition every time

You can still use loop-agent for ambiguous goals, but in that case, designing `verify` becomes the central concern.

## Documentation

| Document | Contents |
|---|---|
| [docs/quickstart.md](./docs/quickstart.md) | Run your first loop |
| [docs/first-harness-api.md](./docs/first-harness-api.md) | APIs to use first |
| [docs/seams.md](./docs/seams.md) | Details of `gather` / `act` / `review` / `verify` and related components |
| [docs/verifiers.md](./docs/verifiers.md) | Verification helpers |
| [docs/recipes/](./docs/recipes/README.md) | Concrete loop examples |
| [docs/adapters/README.md](./docs/adapters/README.md) | Claude Code / Codex adapters |
| [docs/persistence-and-resume.md](./docs/persistence-and-resume.md) | State persistence and resume |
| [docs/safety.md](./docs/safety.md) | Stop conditions and manual approval |
| [docs/cli.md](./docs/cli.md) | CLI |
| [docs/stability.md](./docs/stability.md) | Compatibility contract |
| [docs/api-reference.md](./docs/api-reference.md) | API reference |

## Status

**1.0.0 Stable**. The canonical compatibility contract is [docs/stability.md](./docs/stability.md).

This README is kept short as an entry point, with detailed specifications split into docs.

## License / Development

The license is [MIT](./LICENSE).

Issues / PRs are handled in English. The default branch is `main`.
