The Time-Travel Debugger for AI Agents.
Break out of critique death loops • Rewind cognitive turns like a video player • Mutate corrupted state in-flight • Fork alternative branches • Terminal TUI & CI Replay Cassettes
Debugging multi-turn AI agents today feels like programming with 1970s punch-cards:
- Your agent takes 8 sequential cognitive turns toward a complex goal ($1.50 in tokens, 3 minutes elapsed).
- On turn 9, a tool returns unexpected JSON or a subtle schema shift; the agent enters a circular critique loop or hallucinates.
- You hit
Ctrl+C, patch a prompt, and rerun from step 1—burning more money and waiting all over again.
Existing observability platforms (LangSmith, Arize Phoenix, AgentOps) are post-facto, read-only web dashboards. They tell you why your agent burned $50 after the money is already gone.
unloop is the interactive, terminal-native time-travel debugger:
| Scenario | Without unloop |
With unloop |
|---|---|---|
| Agent enters a circular retry loop | Kill with Ctrl+C, lose entire session, rerun from step 1 ($$$ & time wasted). |
Hit pause, step back 2 turns, patch the prompt/state, resume seamlessly. |
| Agent made a bad edit 3 steps ago | Manually clean up git commits, wipe agent history, re-prompt from scratch. | Select Turn #3 in TUI, hit [Fork], try an alternate prompt path. |
| Watchdog over runaway token costs | Discover the loop only after hitting an API quota or budget alert. | Automatic anti-oscillation watchdog freezes execution on turn 3 of a loop. |
| Debugging team agent failures in CI | Sifting through raw terminal logs and 30,000-line JSON dumps. | Interactive single-file replay cassette (.unloop) with timeline TUI. |
unloop supports multiple ways to debug and trace agents in production and daily developer workflows:
Wrap existing terminal agents (such as Claude Code, GitHub Copilot CLI, or Aider) without changing a single line of their code:
# Wrap any CLI agent with unloop flight-recording
unloop wrap -- claude
# Or with Copilot / Aider
unloop wrap -- aider --model sonnet- Silent Flight Recording: Every prompt, tool invocation (
git diff,npm test, file writes), and return value is streamed into a local.unloopcassette. - Break Loop Trigger: When an agent gets stuck in a loop, press
Alt+U(or let the automatic watchdog trigger) to drop into the interactive TUI, rewind turns, edit state, and resume.
Use unloop as a transparent Model Context Protocol (MCP) gateway for tools like Claude Code and Copilot Workspace:
# Add unloop MCP proxy to your agent configuration
claude mcp add unloop-proxy -- "unloop-mcp"- Policy Enforcement: Intercept destructive commands (e.g.,
rm -rfor unapproved schema migrations) before execution. - Automatic Checkpointing: Micro-snapshots taken before every tool execution allow instantaneous rollback of both agent memory and file system state.
Instrument your custom agent loops, LangGraph, or CrewAI pipelines with minimal Python code:
Wrap agent turn functions directly (supports both sync and async):
import unloop
# Automatically records prompt, memory deltas, durations, and returned reasoning
@unloop.trace()
def run_agent_turn(prompt: str, state: dict) -> str:
response = call_llm(prompt, state)
state["last_thought"] = response
return response
# Or asynchronously:
@unloop.trace()
async def async_agent_turn(prompt: str, state: dict) -> dict:
return await execute_agent_pipeline(prompt, state)Use fine-grained control for complex multi-tool loops:
import unloop
with unloop.session("research_assistant", db_path="run.unloop") as dbg:
# Set breakpoints on tool errors or specific dangerous tools
dbg.add_breakpoint(on_error=True)
dbg.add_breakpoint(tool_name="delete_database")
for turn_idx in range(10):
with dbg.step(prompt="Analyze research report", state=agent.memory) as step:
action, args = agent.decide()
step.set_response(f"Decided to invoke {action}")
result = run_tool(action, args)
step.record_tool(action, arguments=args, result=result)
agent.memory["last_action"] = action
# Time-travel rewind to prior turn if stuck
if dbg.current_turn_id and agent.is_stuck():
dbg.rewind_to(checkpoint_turn_id, new_branch_name="recovery")Context compression and prompt compaction are notorious for silently dropping negative constraints, schema rules, and critical facts:
- Raw Prompt Preservation: Every turn snapshot captures the full model input prompt, message sequence, and token telemetry.
- Silent Drop Detection: Run
unloop diff session.unloop --from 2 --to 3 --prompt(or--verify-slots) to compare pre- and post-compaction prompts against the 6-slot OpenClaw/SpecCompact schema (verify_compaction_checkpoint). - ARCBench Sidecar Export (
export_arcbench_lock_sidecar): Compiles surviving negative constraints,allowed_tools,forbidden_tools, normalizedforbidden_path_prefixes,pinned_arg_literals, andpinned_model_versioninto a deterministic@arcbench_lock:sha256:...sidecar consumed directly byintent-fabric. - Line-by-Line Diff: Highlights pruned constraints (in red
-), newly introduced summaries (in green+), and overall compression ratio.
Rewinding internal agent memory does not rewind the external world. If Turn 2 sent an email or wrote to a database before Turn 3 crashed, rewinding to Turn 1 and branching would normally re-fire that external call.
unloop introduces the Egress Replay Fence:
-
Automatic Mutating Tool Detection: Detects egress side-effects (
send_email,write_file,post_webhook,execute_sql,create_user) or accepts explicitis_side_effect=Trueandidempotency_key. -
Egress Ledger: When
dbg.rewind_to(turn_id)is invoked, side effects from abandoned turns ($T_{k+1} \dots T_{now}$ ) are automatically cataloged. -
Replay Policies:
-
policy="warn": Flagsrec.metadata["replay_fence_warning"]on duplicate execution. -
policy="stub": Prevents external network/disk execution and mocks the call using the cached prior response. -
policy="halt": Instantly halts execution (BreakpointHalt) before the duplicate side-effect leaves the box.
-
with unloop.session("production_agent", side_effect_policy="stub") as dbg:
with dbg.step(prompt="Dispatch report") as step:
# If rewound, the fence stubs duplicate call using previous result
step.record_tool(
"send_email",
{"to": "ops@example.com"},
is_side_effect=True,
idempotency_key="email:weekly_ops",
)Run headless agent benchmarks, automated PR bots, and evaluations with zero overhead:
# In your GitHub Actions workflow
- name: Run Autonomous Fixer Agent (Headless Flight Recording)
run: |
unloop record -o ./failure.unloop -- python run_agent.py "fix vuln-1049"
- name: Enforce Agent Quality Gate (Fail on loops, errors, or token blowups)
run: |
unloop check ./failure.unloop --max-turns 15 --no-oscillations --no-errorsWhen a CI agent fails:
- Download the single-file
failure.unloopartifact. - Run
unloop replay failure.unlooplocally. - Step through the exact mental state, prompt deltas, and tool calls the agent experienced in CI.
Run autonomous coding agents in isolated Copy-on-Write (CoW) Git worktree sandboxes with zero repository sprawl:
# Execute coding agent inside detached worktree jail
unloop jail --agent-id agent-worker-1 -- uv run pytest
# Keep jail intact for manual inspection
unloop jail --agent-id agent-worker-1 --keep -- npm test- Ephemeral Worktree Sandboxing: Spawns a detached Git worktree per agent (
.unloop/jails/<agent-id>), preventing working tree collisions across parallel agent runs. - Cross-Process Directory Locks: Atomic filesystem locks arbitrate simultaneous worktree creation and cleanup with stale lock recovery.
- Unified Diff & Digest Export: Automatically stages changes (
git add -N .), exports unified diffs, and computes canonical SHA-256 patch digests for downstream verification. - Clean Teardown: Worktrees and jail directories are safely pruned on process exit unless
--keepis explicitly set.
┌── Execution Timeline DAG ──┐┌── Turn Inspector ───────────────┐┌── State Delta & Memory ─────┐
│ ││ ││ │
│ [main] ││ Turn ID: a1a7ee52 ││ State Delta (vs Parent): │
│ ├── Turn #0 [a1a7ee] ││ Branch: recovery_fix ││ query: "broken" -> "fixed" │
│ ├── Turn #1 [f2c901] [!] ││ Turn Index: #1 ││ status: "init" -> "active" │
│ └── [recovery_fix] ││ ││ │
│ └── Turn #1 [e1fd91] OK ││ Prompt: Resume with fixed query ││ Current Memory State: │
│ ││ Response: Query resolved. ││ { │
│ ││ ││ "query": "fixed", │
│ ││ Tool Invocations: ││ "status": "completed" │
│ ││ * web_search OK ││ } │
└────────────────────────────┘└─────────────────────────────────┘└─────────────────────────────┘
Keys: [s] Next Turn | [u] Prev Turn | [f] Fork Branch | [m] Mutate State | [q] Quit
pip install unloop
# or with uv
uv tool install unloop# Headless flight recording runner (CI or local scripts)
unloop record -o run.unloop -- python agent.py
# CI Quality Gate assertion (assert loop-freedom, max turns, and zero tool errors)
unloop check run.unloop --max-turns 12 --no-oscillations --no-errors
# Side-by-side state, tool execution, and prompt diff between two turns
unloop diff run.unloop --from 0 --to 1
# Inspect line-by-line prompt diff and catch silent compaction drops
unloop diff run.unloop --from 0 --to 1 --prompt
# Display summary of recorded session metadata, tokens, and branches
unloop info run.unloop
# Inspect full turn execution timeline with colorized state diffs
unloop history run.unloop
# Export a clean, shareable Markdown post-mortem incident report
unloop export run.unloop -o post_mortem.md
# Launch 3-pane interactive terminal time-travel TUI
unloop replay run.unloop┌─────────────────────────────────────────────────────────────┐
│ unloop System Architecture │
└─────────────────────────────────────────────────────────────┘
[ AGENT APPLICATION ] (Claude CLI / LangGraph / Native Python)
│
▼ (@unloop.trace / unloop wrap / with dbg.step())
┌─────────────────────────────────────────────────────────┐
│ 1. Interception & Watchdog Engine │
│ • Anti-Oscillation Watchdog (Loop detector) │
│ • Breakpoint Evaluator (Errors & Conditions) │
└───────────────────────────┬─────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 2. Canonical Protocol & Models │
│ • TurnSnapshot (turn_id, parent_id, branch_id) │
│ • Cognitive & Memory Deltas │
└───────────────────────────┬─────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 3. Storage & DAG Branching Engine │
│ • Append-only SQLite WAL (.unloop file) │
│ • Microsecond commit latency (<2ms overhead) │
│ • Git-like branch forking & rewind │
└───────────────────────────┬─────────────────────────────┘
│
┌────────────────┴───────────────┐
▼ ▼
┌───────────────────────┐ ┌────────────────────────┐
│ 4. Interactive TUI │ │ 5. Headless CI Harness │
│ (Textual 3-Pane) │ │ (unloop CLI) │
└───────────────────────┘ └────────────────────────┘
| Framework / Tool | Integration Pattern | Status |
|---|---|---|
Claude Code (claude) |
Terminal wrapper & MCP Proxy | 🟢 Supported |
| GitHub Copilot CLI | Terminal wrapper & MCP Proxy | 🟢 Supported |
| Native Python Loops | Zero dependencies, with dbg.step() |
🟢 Supported |
| LangGraph / LangChain | Node checkpoint hook and state graph listener | 🟡 In Progress |
| FastMCP / MCP Servers | Wire-level tool interception middleware | 🟡 In Progress |
| CrewAI / AutoGen | Task execution listener and state serializer | 🔵 Planned |
Unloop maintains strict test coverage (>=90% enforced in CI) and a zero-live-HTTP CI architecture:
- Tier 1 (Golden Trajectory Fixtures): Real-world multi-turn developer debugging trajectories derived from SWE-bench (
encode__httpx-1422) checked intotests/fixtures/corpora/for deterministic, sub-second oscillation and time-travel validation. - Tier 2 (Opt-in Live Harness): Live cloud agent tracing verification against OpenRouter (
benchmarks/live_debugger_smoke_test.py --openrouter).
# Clone the repository
git clone https://github.com/invarcore/unloop.git
cd unloop
# Install with development dependencies using uv
uv sync --all-extras
# Run linter
uv run ruff check .
# Run test suite with strict coverage enforcement (>=90%)
uv run pytest --cov=unloop --cov-report=term-missing --cov-fail-under=90
# Run local hermetic end-to-end time-travel smoke test (<200ms)
uv run python benchmarks/live_debugger_smoke_test.py
# Optional: Run live tracing verification against OpenRouter Free Tier
uv run python benchmarks/live_debugger_smoke_test.py --openrouter --model openrouter/free
# Run hermetic containerized test suite via Docker Compose
docker compose -f docker-compose.test.yml up --build --abort-on-container-exit
# Run interactive loop recovery demonstration
uv run python examples/01_native_loop_agent.pyThis engine is part of the Invarcore enterprise verification fabric. Invarcore develops mathematical invariants, cryptographic policy contracts, and execution runtimes for autonomous AI systems.
- Official Website & Architecture: https://invarcore.com
- Technical Whitepapers & Invariant Specs: https://invarcore.com/#whitepapers
- GitHub Organization: https://github.com/invarcore
- Security & Vulnerability Disclosure: security@invarcore.com
MIT © VinayKumar KsheeraSagar
