owloop 0.4.0

Your code evolves while you sleep.

owloop is a spec-driven autonomous coding loop for Claude Code, Kimi Code CLI, Codex, Cursor, and other CLI-based coding agents. You write specs, start the loop, and wake up to clean commits.

Each iteration spawns a fresh agent with zero accumulated context, verifies every acceptance criterion with real shell commands, and only commits when they pass.

owloop run → pick spec → fresh agent → verify with shell → commit → next spec → 🌅

Quick Start

uv tool install owloop        # or: pip install owloop

owloop go "refactor error handling"   # one command: init → spec → review → run

That's it. owloop auto-initializes, scans your codebase, generates spec(s), asks for approval, and starts the loop.

Install as an Agent Skill

Owloop also ships as a set of composable agent skills for any agentskills.io-compatible agent:

# Claude Code
npx skills add caoergou/owloop --agent claude-code

# Kimi Code CLI / Codex / Cursor / etc.
npx skills add caoergou/owloop --agent '*'

Skills included:

How It Works

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#d4a025', 'primaryTextColor': '#0b1026', 'primaryBorderColor': '#3a4270', 'lineColor': '#3a4270', 'secondaryColor': '#121a2e', 'tertiaryColor': '#121a2e', 'fontFamily': 'Inter, system-ui, sans-serif' }}}%%
graph LR
    A["🦉 Pick spec"]:::owl --> B["fresh agent context"]:::neutral
    B --> C{"DONE?"}:::neutral
    C -- yes --> D["✅ Commit"]:::neutral --> E{"More specs?"}:::neutral
    C -- no --> R["🔄 Retry ≤3"]:::retry --> A
    E -- yes --> A
    E -- no --> F["🌅 Complete"]:::done

    classDef owl fill:#d4a025,stroke:#d4a025,color:#0b1026
    classDef done fill:#8fd19e33,stroke:#8fd19e,color:#f2ecd8
    classDef retry fill:#e0777d33,stroke:#e0777d,color:#f2ecd8
    classDef neutral fill:#121a2e,stroke:#3a4270,color:#f2ecd8

Specs

Specs are constraint-oriented: define what to do, what's off-limits, and make every acceptance criterion a shell command.

# Spec: Extract ValidationError Handling

## Priority: 1

## Requirements
- Extract repeated `except ValidationError` blocks into a single `@app.errorhandler`

## Acceptance Criteria
- [ ] grep -c "except ValidationError" backend/app/api/*.py  →  ≤ 5
- [ ] uv run ruff check backend/  →  0 errors

## Exclusions
- Do NOT change API response formats
- Do NOT touch models/, schemas/, services/

If you can write a shell command that verifies "done", it's a good owloop task. If "done" requires a human to look and decide, it's not.

Compared To

FAQ

Development

uv sync --group dev          # install dev dependencies
uv run pytest -q             # run tests with coverage
uv run ruff check src/owloop tests
uv run mypy src/owloop tests

Brand

owloop's identity — Ollie the owl, the night/amber palette, and the "your code evolves while you sleep" story — is documented in .github/BRAND.md.

Credits

Inspired by and built upon:

• Geoffrey Huntley's Ralph Wiggum methodology — the original "unattended coding loop" concept
• Florian Standhartinger's ralph-wiggum — the implementation owloop was forked from
• gnhf — multi-agent overnight runner, influenced owloop's fresh-context-per-iteration design

License

MIT