ai-blame 0.2.0

Extract provenance from AI agent execution traces

ai-blame

Extract provenance from AI agent execution traces.

Like git blame, but for AI-assisted edits.

Why?

AI coding assistants modify your files, but git blame only shows who committed the changes—not which AI model actually wrote them. ai-blame fills this gap by extracting provenance from execution traces and embedding it in your files.

Features

• Automatic trace discovery — Finds Claude Code traces based on your project directory
• Multiple output modes — Append to files, create sidecars, or embed as comments
• Configurable per file type — Different policies for YAML, JSON, Python, etc.
• Dry-run by default — Preview changes before applying
• Flexible filtering — By file pattern, change size, or time range

Installation

pip install ai-blame

# Or with uv
uv pip install ai-blame

Quick Start

# Check what traces are available
ai-blame stats

# Preview what would be added (dry run)
ai-blame mine --initial-and-recent

# Apply changes
ai-blame mine --apply --initial-and-recent

# Filter to specific files
ai-blame mine --pattern ".py" --apply

Output Examples

YAML/JSON files — Append directly

# config.yaml
name: my-project
version: 1.0

edit_history:
  - timestamp: "2025-12-01T08:03:42+00:00"
    model: claude-opus-4-5-20251101
    agent_tool: claude-code
    action: CREATED

Code files — Sidecar or comments

# main.py (with comment policy)

def hello():
    print("Hello, world!")

# --- edit_history ---
# - timestamp: '2025-12-01T08:03:42+00:00'
#   model: claude-opus-4-5-20251101
#   action: CREATED
# --- end edit_history ---

Or use sidecar files: main.py → main.history.yaml

Configuration

Create .ai-blame.yaml in your project root:

defaults:
  policy: sidecar
  sidecar_pattern: "{stem}.history.yaml"

rules:
  - pattern: "*.yaml"
    policy: append
  - pattern: "*.json"
    policy: append
    format: json
  - pattern: "*.py"
    policy: comment
    comment_syntax: hash
  - pattern: "tests/**"
    policy: skip

Supported Agents

Agent	Status
Claude Code	✅ Supported
OpenAI Codex	🔜 Planned
Others	PRs welcome!

Documentation

Full documentation: ai4curation.github.io/ai-blame

• Getting Started
• Configuration Guide
• CLI Reference

Contributing

We welcome contributions! See CONTRIBUTING.md.

PRs especially welcome for additional agent support (Cursor, Aider, Copilot, etc.).

License

BSD-3-Clause