The Self-Healing OS

# The Self-Healing OS: how to make your AI fix its own mistakes overnight

Your AI assistant makes the same mistakes over and over — not because it can't do better, but because nothing remembers what went wrong. This is the exact setup I use to give it a memory of its own bugs and a way to quietly fix the safe ones while I sleep. By the end you'll have a three-part system running on any machine with Claude Code, including a $5 server.

The kit is free. On Instagram you can also comment HEAL and the bot will DM it to you; everywhere else the download button above is it.

It's three small pieces that work together — no database, no account, no subscription:

• The flag ledger (FLAGS.md): one plain-text file. Every time the assistant notices a bug, a stale path, or a rough edge it can't fix right now, it writes ONE line here instead of forgetting it.
• **The self-heal skill**: teaches the assistant two habits — *flag* problems as it works, and *heal* the safe ones on demand.
• **The nightly-repair cron**: a scheduled headless run that works the backlog while you sleep, applies only the safe fixes, and marks each one done forever.

The trick that makes it compound: every healed flag moves to a ## Healed section and is never re-processed. The same mistake never gets fixed twice, so the backlog only ever shrinks.

1. Drop in the ledger. Copy FLAGS.md into ~/.claude/FLAGS.md. This is your single source of truth — newest flag on top, one line each.

2. Install the self-heal skill. Put SKILL.md in ~/.claude/skills/self-heal/. Now /self-heal in any session reads the ledger and fixes the safe items in front of you, and the assistant starts flagging problems on its own as it works.

3. Turn the habit on. Add two lines to your CLAUDE.md so the flag habit is always active (they're in the kit's README). One tells it to append a flag instead of derailing; the other tells it to heal only the safe set on /self-heal or at session end.

4. Schedule the nightly repair. Set the one variable at the top of nightly-repair-cron-example.sh (the project to repair), then add it to cron to run at 3am. It runs Claude Code headless, bounded to a handful of safe fixes, and logs a one-line summary each morning.

The whole thing is safe to run unattended because it only ever auto-applies reversible edits. Everything else is *routed* — named with the right tool and left for you to approve.

The nightly script will never on its own push to git, deploy, delete files, run sudo, or make any outward change — even if a flag asks for it. That boundary is the entire reason you can let it run while you sleep.

Every flag is one line so it stays a pointer, not an essay:

- DATE [sev] [area] <the flag, one line> · fix:<skill/action> · status:open

sev is 🔴 blocking / 🟡 should / 🟢 nice. When a flag is healed, the line moves to ## Healed with the date and what changed — that's the permanent memory that stops repeat work.

• [Claude Code](https://docs.claude.com/en/docs/claude-code) — the assistant that runs the flags, the skill, and the nightly cron. The only requirement.
• cron — already on any Mac or Linux box; schedules the overnight repair. On a $5 VPS it costs nothing extra.
• The kit itself — the flag ledger template, the self-heal skill, and the nightly-repair script, all in one zip: download it here.

They try to make the AI fix *everything* automatically — and then it deletes a file or pushes a broken commit at 3am, and they turn the whole thing off. The fix is the opposite: only auto-apply the boring, reversible stuff, and *route* everything with real risk back to a human. A self-healing OS earns trust by being conservative, not clever. That's why the safe set is short on purpose.

Create ~/.claude/FLAGS.md and add the two CLAUDE.md lines. Even before you schedule anything, your assistant will start banking the bugs it notices instead of forgetting them — and you'll have a running list of exactly what your OS keeps getting wrong. The overnight healing is just the payoff on top.