# Shadow Sentinel – Linux filesystem revision guard with loop-coupling

> Source: <https://github.com/automatician/shadow-sentinel>
> Published: 2026-10-17 11:43:01+00:00

**Autonomous OS-Level Revision & Backup Daemon with Decentralized Marker Control and Loop-Coupling.**

Shadow Sentinel monitors directory trees in real-time via the Linux kernel (`inotify`), captures
atomic `.bak` revisions and unified diffs (`.diff`) on every file modification, and provides
instant 1-command restores with loop-coupling safety.

Autonomous AI coding agents, Copilots, and LLM automation pipelines are transforming development.
However, they introduce a terrifying new failure mode: **silent, automated destruction of code**.

Large Language Models have a notorious habit of code "laziness" and structural truncation:

- Replacing hundreds of lines of critical logic with:
`// ... rest of implementation remains unchanged ...`
- Overwriting multi-thousand-line configuration files with incomplete, summarized snippets.
- Truncating files or writing empty 0-byte files when token limits, parser errors, or API timeouts occur.
- Hallucinating breaking parameter changes across multiple scripts simultaneously.

- **If you catch it immediately:** You still waste stressful hours digging through editor undo buffers,
stash queues, or attempting to manually reconstruct what the model wiped out.
- **If you catch it hours or days later:** The damage is catastrophic. The agent continued running,
git working trees are dirty, commits were never made, and the original, working code is gone forever.
Regular backups taken once a day or once a week cannot save intraday edits.

Shadow Sentinel runs silently in the background directly under the agent's feet at the OS level.
The microsecond an AI agent or automated script calls `write()` or overwrites a file:

1. Sentinel's kernel-level inotify intercept catches the write before the file closes.
2. The previous working version is sealed into an atomic, timestamped `.bak` revision.
3. A human-readable unified `.diff` is generated showing exactly what the agent altered or removed.
4. If an agent ruins a file, you restore it with a single command: `sentinel restore <ID>` .

1. 
**Decentralized Marker Control (`sentinel_marker`)** :
  - No tedious editing of central configuration files.
  - Simply run `sentinel init [MB]` in any directory or place a`sentinel_marker` file.
  - Sentinel automatically discovers all marked roots on startup and monitors them and all nested subdirectories recursively.
2. 
**Retroactive Legacy Backup Onboarding** :
  - On service startup, Sentinel scans for pre-existing `.bak` revisions on the drive and
silently indexes them into its catalog. Legacy backups become immediately restoreable via`sentinel restore <ID>` .
  - Backup storage directories are isolated to prevent recursive self-monitoring loops.
3. On service startup, Sentinel scans for pre-existing 
4. 
**Dynamic File-Size Ceiling (Self-Pruning Vault)** :
  - The value inside `sentinel_marker` sets the protected size ceiling (e.g.`5` for 5 MB).
  - If a file (such as a runaway logfile) exceeds this ceiling, it is automatically ejected from the shadow vault. Small scripts, configurations, and source code stay 100% protected.
5. The value inside 
6. 
**Loop-Coupling (Undo-Safe Restore)** :
  - Restoring a file with `sentinel restore <ID>` overwrites the target file.
  - The running inotify daemon immediately intercepts this write and seals the overwritten version into a brand-new backup revision. Mistaken restores can instantly be undone!
7. Restoring a file with 
8. 
**Flapping & Cooldown Debounce** :
  - Rapid consecutive writes are debounced with a 3-second quiet window to prevent spam.
9. 
**Zero Dependencies** :
  - Pure Python standard library with native `ctypes` bindings directly to`libc.so.6` .
  - No external tools like `inotifywait` or background Git daemons required.
10. Pure Python standard library with native 

Sentinel guarantees that it will never exhaust disk space through a 4-tier automated policy:

1. 
**Version Cap per File (Max 10 Revisions)** :
Only the 10 most recent`.bak` and`.diff` files per target are kept. Older versions are deleted.
2. 
**Version Age Expiration (14 Days)** :
Revisions older than 14 days are automatically pruned.
3. 
**Log Expiration (30 Days)** :
Daily audit diff logs (`diff-YYYYMMDD.log` ) are removed after 30 days.
4. 
**Emergency Storage Ceiling (500 MB Cap)** :
If total backup directory size exceeds 500 MB, an emergency purge trims the oldest backups
across all files until total disk usage drops back down to 80% (400 MB).
5. 
**Active Vault Ejection** :
Files that grow beyond the MB ceiling in`sentinel_marker` are immediately removed from
the`.shadow_vault` to recover disk space instantly.

*The pruning engine runs automatically every 6 hours and immediately upon service startup.*

```
pip install shadow-sentinel
```

Set up and start the systemd background service in one step:

```
sudo sentinel service install
```

Navigate to the directory and run:

```
sentinel init 5
```

*(Creates `sentinel_marker` with a 5 MB file size limit).*

Simply type in any terminal:

```
sentinel
```

Automatically detects the nearest marker upwards and lists all protected revisions. Optionally pass a search filter:

```
sentinel .py
sentinel restore 3
sentinel diff 3
sentinel markers
sentinel help
```

- **Root Daemon:**`/var/lib/shadow-sentinel/`
- **User Daemon:**`~/.local/share/shadow-sentinel/`

To store backups, vaults, and indices in a custom directory, create:
`/etc/shadow-sentinel/config.json` (for root) or `~/.config/shadow-sentinel/config.json` (for user):

```
{
    "storage_dir": "/custom/path/to/backups"
}
export SENTINEL_STORAGE_DIR=/custom/path/to/backups
```