Incident Replay Agent Failure Forensics

Post-mortem analysis for AI agent failures. Capture state, reconstruct timelines, identify root causes. When your agent breaks, know what happened, why, and how to prevent it.

When your agent breaks, you need to know what happened, why, and how to prevent it next time. Incident Replay captures workspace state at points in time, detects when things go wrong, reconstructs the sequence of events, and classifies root causes with actionable remediation steps.

The Problem

Your agent crashed overnight. Files are missing. The config looks wrong. The logs are a wall of text. What happened? When? Why?

Without forensics tooling, post-mortem analysis is manual detective work: diffing files by hand, grepping logs, guessing at causation. Incident Replay automates the mechanics so you can focus on understanding.

What It Does

1. Capture (incident_capture.py)

• - Take point-in-time snapshots of your workspace (files, sizes, hashes, content)
• Configurable include/exclude patterns (track what matters, ignore noise)
• Automatic snapshot pruning (keep last N)
• Compare any two snapshots to see exactly what changed
• Trigger detection — automatically flag incidents based on:

2. Replay (incident_replay.py)

• - Build chronological timelines from snapshots, file changes, and triggers
• Extract decision chains from agent logs and memory files
• Heuristic root cause classification:

• - Remediation suggestions tailored to each root cause category
• Incident database with persistent storage and pattern tracking

3. Report (incident_report.py)

• - Full incident reports with timeline, changes, triggers, and remediation
• Summary reports across all incidents with severity and root cause breakdowns
• Decision chain visualisation (what the agent decided and why)
• Export markdown or JSON

Quick Start

CODEBLOCK0

Programmatic Usage

CODEBLOCK1

Use Cases

• - Overnight failure analysis: Agent ran unattended and broke — what happened?
• Config change impact: Track exactly what changed after a config update
• Drift detection: Compare weekly snapshots to catch gradual degradation
• Secret leak detection: Catch credentials or sensitive data in agent outputs
• Regression forensics: Agent used to work, now it doesn't — find the divergence point
• Team incident management: Track incidents over time, find recurring patterns

What's Included

Requirements

• - Python 3.8+
• No external dependencies (stdlib only)
• Works on any OS
• Platform-agnostic (works with any file-based AI agent workspace)

Configuration

See config_example.json for the complete reference. Key areas:

• - WORKSPACE_ROOT — Directory to monitor
• INCLUDE/EXCLUDE_PATTERNS — What files to capture
• TRIGGERS — Conditions that flag incidents (log patterns, file changes, content scans)
• ROOT_CAUSE_CATEGORIES — Classification categories with descriptions and remediation
• DECISION_MARKERS — Regex patterns to extract agent decisions from logs
• LOG_FILES — Which files to scan for decision chains

quality-verified

License

MIT — See LICENSE file.

⚠️ Security Note — Config File

Configuration is loaded from a JSON file. This is safe to share — no code execution.

• - Config path is validated for existence and size (1MB cap) before loading
• Must be a .json file — raises ValueError if given a non-JSON path
• Keep your config under version control; it defines what triggers are watched and what's protected

⚠️ Disclaimer

This software is provided "AS IS", without warranty of any kind, express or implied.

USE AT YOUR OWN RISK.

• - The author(s) are NOT liable for any damages, losses, or consequences arising from

• - This software does NOT constitute financial, legal, trading, or professional advice.
• Users are solely responsible for evaluating whether this software is suitable for

• - No guarantee is made regarding accuracy, reliability, completeness, or fitness

• - The author(s) are not responsible for how third parties use, modify, or distribute

By downloading, installing, or using this software, you acknowledge that you have read
this disclaimer and agree to use the software entirely at your own risk.

DATA DISCLAIMER: This software processes and stores data locally on your system.
The author(s) are not responsible for data loss, corruption, or unauthorized access
resulting from software bugs, system failures, or user error. Always maintain
independent backups of important data. This software does not transmit data externally
unless explicitly configured by the user.

Support & Links

Built with OpenClaw — thank you for making this possible.