https://github.com/alienzhou/agent-reloop
https://github.com/alienzhou/agent-reloop
Last synced: 13 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/alienzhou/agent-reloop
- Owner: alienzhou
- Created: 2026-04-11T11:33:07.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-05-17T10:46:19.000Z (about 2 months ago)
- Last Synced: 2026-05-17T12:42:47.258Z (about 2 months ago)
- Language: Python
- Size: 812 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Agent-Reloop
> **Imagine this:** It's 11 PM. You spend 10 minutes telling the framework what you want — a data pipeline, a set of API endpoints, whatever. You define a few evaluation criteria, hit run, and go to sleep. When you wake up at 7 AM, you open your laptop. The agent has gone through 6 rounds of execution and self-correction overnight. All L0/L1/L2 checks are green. Every round is committed to Git. The solution is sitting in `task/solution/`, ready for review. You just slept through the entire development cycle.
>
> That's the idea behind Agent-Reloop.
---
A universal self-iterating framework for AI Agents. It orchestrates an **execute → evaluate → iterate** loop so any task can run automatically until it passes acceptance criteria.
Reloop doesn't generate business logic — it provides the loop skeleton. Plug in any task, define what "done" looks like, and let the agents iterate until they get there.
## Key Features
- **Two-Phase Architecture** — human-in-the-loop initialization + fully automated iteration
- **Multi-Agent Support** — swap between Claude Code, Codex, Gemini, or any CLI-based agent via a unified Driver interface
- **Three-Layer Evaluation** — L0 (precondition) → L1 (deterministic) → L2 (semantic), with short-circuit logic
- **Auto-Commit per Round** — every iteration is checkpointed in Git for full traceability
## How It Works
The framework has two phases — **Init** (human-in-the-loop) feeds into **Iteration** (fully automated Python loop), all running on top of pluggable Drivers.
## Directory Structure
```
project-root/
├── task/ # Task zone
│ ├── INTENT.md # What to achieve
│ └── solution/ # The evolving solution (scripts/skills/project/...)
│
├── run-sets/ # Asset zone — one folder per iteration round
│ ├── run-001/
│ │ ├── logs/ # Execution logs
│ │ └── eval-report/ # L0/L1/L2 evaluation results
│ ├── run-002/
│ └── ...
│
├── drivers/ # Agent CLI adapters (Python)
├── specs/ # Design specifications
└── docs/ # Architecture & how-it-works documentation
```
## Quick Start
> **Status**: Core framework is implemented. Drivers available: Flick, Claude Code, Codex, Cursor, Mock.
### 1. Initialize a Task
The init phase is agent-driven and interactive. Three built-in **Meta Skills** walk you through:
| Step | Meta Skill | Output | Purpose |
| ---- | ------------------- | -------------------- | ---------------------------------- |
| 1 | INTENT Generator | `task/INTENT.md` | Define what the task is |
| 2 | Evaluator Generator | Eval Skill + scripts | Define how to verify success |
| 3 | Mocker | Mocked solution | Validate the evaluator makes sense |
### 2. Run the Iteration Loop
Once initialization is complete, create `reloop.yaml` (see
[`reloop.yaml.example`](./reloop.yaml.example)) and start the automated loop:
```bash
reloop run
```
The Python loop will:
1. Set up an empty `run-xxx/` directory
2. Call the **Executor** (Agent + INTENT + last eval feedback)
3. Call the **Evaluator** (Agent + solution + eval skill)
4. Call the **Checker** (Agent + eval report → pass/fail)
5. If failed, loop back; if passed, exit
### 3. Review Results
Each round is committed to Git and stored in `run-sets/run-xxx/`. You can inspect execution logs, artifacts, and evaluation reports for any round.
## Driver Interface
Drivers adapt different Agent CLIs to a unified interface:
```python
class Driver:
def run(self, prompt: str, workdir: str) -> str:
...
```
```bash
driver run --prompt "..." --workdir "..."
```
| Driver | Agent | Status |
| ----------- | --------------- | ------- |
| Flick | CodeFlicker Duet| Ready |
| Claude Code | Claude Code CLI | Ready |
| Codex | OpenAI Codex CLI| Ready |
| Cursor | Cursor Agent CLI| Ready |
| Mock | Test fixture | Ready |
Skills are injected directly into the prompt — no separate `--skill` parameter.
## Testing
Run `pytest tests/unit/ -q` after every code change. Smoke tests (`pytest tests/smoke/ --override-ini="addopts=" -m smoke`) cost real tokens — run only when needed.
## Design Docs
| Document | Content |
| -------------------------------------------- | ----------------------------- |
| [specs/00-overview.md](specs/00-overview.md) | Architecture overview |
| [specs/01-adr.md](specs/01-adr.md) | Architecture Decision Records |
| [docs/how-it-works.md](docs/how-it-works.md) | Core working principles |
## License
TBD