Underworld Piggy Bank

Category: folklore / personal ritual reminder (not financial or legal advice).

Premise: A lighthearted standing joke—pre-funding an informal "underworld wallet" by tracking how much the user claims to have burned (paper offerings tradition, framed as savings for the hereafter). The agent does not perform real rituals; it stores numbers the user reports and nudges them on a configurable schedule.

Configuration

Work from this skill’s root (folder with config.json, scripts/, state/).

config.json fields:

| Field | Meaning | |--------|---------| | reminder_interval_days | Minimum days between delivered reminders (default 30, roughly monthly). Must be ≥ 1. | | currency_label | Human-readable label for totals (e.g. informal hell-bank notes). |

Override reminder frequency without editing the file:

• UNDERWORLD_PIGGY_REMINDER_DAYS — positive float days; takes precedence over reminder_interval_days.

Timestamps for reminders are stored in UTC (state/last_reminder_at.txt).

When to check reminders

Run at session start, once per day, or per your platform policy:

python3 scripts/should_remind.py

• REMIND — It is time to surface the ritual prompt (see dialogue below). After you actually show the reminder to the user, run:

  python3 scripts/mark_reminder_delivered.py
  

  Do not mark delivered if the user never saw the message (e.g. abandoned session).

• SKIP — Inside the quiet period; do not nag.

The first run (no last_reminder_at.txt) returns REMIND so the user gets an initial onboarding prompt.

Reminder dialogue (when REMIND)

1. Gently remind the user to set aside / burn symbolic offerings for themselves on whatever cadence fits their tradition or humor.

2. Ask explicitly: Roughly how much did you last burn for yourself? (They may answer in any informal unit; store the numeric portion they confirm.)

3. If they give a number, record it:

   python3 scripts/record_contribution.py --amount <number> [--note "optional note"]
   

4. Show the updated running total:

   python3 scripts/summary.py
   

If they decline to report a number, still run mark_reminder_delivered.py after the reminder was shown, unless your product policy says to retry sooner—default is to respect the interval.

Ad-hoc entries (no reminder)

Whenever the user volunteers an amount outside the schedule, run record_contribution.py the same way, then summary.py.

Corrections

If the user says a past entry was wrong, add a correcting entry with a negative amount and a --note explaining the adjustment (e.g. --amount -500 --note duplicate entry). The running total is the sum of all transactions.

Ledger storage

• File: state/ledger.json (created automatically).
• The directory state/ is git-ignored by default—users should back it up if they care about the tally.

Tone and boundaries

• Keep it optional, playful, and respectful of varied beliefs; never shame the user for skipping.
• This is not a bank, not tax advice, and not a claim about the afterlife—only a personal log of numbers the user provides.

Quick commands

python3 scripts/should_remind.py
python3 scripts/mark_reminder_delivered.py
python3 scripts/record_contribution.py --amount 1200 --note "Qingming stack"
python3 scripts/summary.py