Skip to content

unloop v0.1.0: The Time-Travel Debugger & Anti-Oscillation Watchdog for AI Agents

Choose a tag to compare

View all tags
@github-actions github-actions released this 17 Oct 06:19
· 9 commits to main since this release
v0.1.0
9e1c9e8

unloop v0.1.0: The Time-Travel Debugger & Anti-Oscillation Watchdog for AI Agents

unloop is an open-source, interactive time-travel debugger and trajectory flight-recorder for autonomous AI agents.

It breaks multi-turn agents out of infinite critique/retry loops, lets engineers rewind cognitive turns like a video player, inspect state diffs, fork alternate execution branches, and capture reproducible single-file .unloop CI replay cassettes.

⚡ 60-Second Quickstart

pip install unloop

Wrap Any CLI Agent Without Code Changes

Flight-record agents like Claude Code, Copilot, or Aider with automatic loop protection:

unloop wrap -- claude

Drop-In Python Function Tracing

from unloop import trace, Session

@trace
def my_agent_step(prompt: str, session: Session = None):
    # Every cognitive turn, tool call, and state delta is persisted
    return run_turn(prompt)

Interactive Terminal Debugger (TUI)

Launch the full-screen terminal inspector:

unloop tui session.unloop
  • Navigate cognitive turns with arrow keys.
  • Inspect JSON state deltas and tool argument hashes.
  • Rewind, mutate corrupt context, and fork alternative reasoning trajectories.

🛡️ Core Capabilities & Architectural Invariants

  • Deterministic Trajectory Persistence (SQLite WAL):
    • Append-only event store with sub-2ms write tax.
    • Encrypted at rest via optional AES-256 and PII redaction rules.
  • OscillationWatchdog:
    • Detects agent death-spirals (repetitive tool calls, ping-pong state cycles, oscillatory self-critique loops) before token budgets are exhausted.
    • Freezes execution or drops into an interactive breakpoint when loop threshold is exceeded.
  • State Deltas & Dynamic Forking:
    • Calculates semantic state diffs between arbitrary cognitive turns.
    • Supports branching: rewind to turn $N$, modify prompt or tool output, and execute an alternate path without starting over.
  • CI Replay Cassettes:
    • Package multi-turn failures into portable .unloop files for deterministic regression tests and bug reports.

🧪 Quality Gates & Verification Suite

  • Unit & Integration Suite: 42/42 tests passing in 4.73s.
  • Code Coverage: 94.56% coverage (exceeding strict 90% threshold).
  • Multi-Platform Verification: Tested across Ubuntu, macOS, and Windows on Python 3.10–3.14.
  • Packaging: Built wheel and sdist distributions attached.

Full Changelog: https://github.com/invarcore/unloop/commits/v0.1.0

Assets 5
Loading