vivrecard 0.1.0

Crash capture and replay for async Python functions and background tasks

VivreCard 🏴‍☠️

Every crash leaves a card.

Crash capture and replay for async Python functions and background tasks.

When an async function fails silently, VivreCard saves everything — inputs, context, traceback — so you can understand and reproduce the failure instantly.

The Problem

background_tasks.add_task(process_feedback, db, session)
# crashes silently... score is always 5... no idea why

The Solution

from vivrecard import capture, attach

@capture
async def process_feedback(db, session):
    attach("session_id", str(session.id))
    attach("role", session.role)
    ...

When it crashes:

🏴‍☠️ VivreCard | Crash captured: process_feedback
   Exception: JSONDecodeError: Expecting value: line 1 column 1
   Saved to: .vivrecard/2026-03-29T21-14-03_process_feedback.json

Installation

pip install vivrecard

Usage

Capture crashes

from vivrecard import capture, attach

@capture
async def my_background_task(user_id: int, data: dict):
    attach("user_id", user_id)  # attach extra context
    ...

Redact sensitive fields

@capture(redact=["password", "api_key"])
async def my_task(password: str, api_key: str):
    ...

List captured crashes

vivrecard list

Replay a crash

vivrecard replay .vivrecard/2026-03-29T21-14-03_process_feedback.json

Crash Artifact

Every crash is saved as a JSON file in .vivrecard/:

{
  "function": "process_feedback",
  "module": "app.services.interview",
  "is_async": true,
  "timestamp": "2026-03-29T21:14:03Z",
  "args": [],
  "kwargs": {"session_id": 42},
  "context": [{"key": "role", "value": "Software Engineer"}],
  "exception": {
    "type": "JSONDecodeError",
    "message": "Expecting value: line 1 column 1"
  },
  "traceback": "..."
}

Why VivreCard?

In One Piece, a Vivre Card tracks someone's condition and location. VivreCard tracks your async task's state at the moment it starts falling apart.

License

MIT