back
loading skill details...
Provide file protection while users work with openclaw. All file operations are version-indexed and support delete recovery and modification rollback.
---
name: mmxagent-guardian
version: 1.0.3
description: Provide file protection while users work with openclaw. All file operations are version-indexed and support delete recovery and modification rollback.
---
# File Protection and Version Management
This Skill uses MiniVCS to track all file operations with version history.
**Runtime requirement**: Python 3 is required to run `scripts/minivcs/minivcs.py`.
**Script location**: `scripts/minivcs/minivcs.py` in the same directory as this `SKILL.md`
(Before executing, first determine the directory containing this file. It is referred to as `$SKILL_DIR` below.)
**Core mechanism:**
- **Modify**: Saves an incremental diff plus a full snapshot from before the modification, **supporting rollback**
- **Delete**: Moves the full file into `~/.openclaw/minivcs/trash/`, **supporting restore**
- **All files are indexed**, with different retention periods based on importance
- **After every operation, the full record table is scanned automatically** to find expired records and ask the user for confirmation
**Usage limitations:**
- **Binary files (images, PDFs, audio/video, etc.)**: Text diffs cannot be generated. For binary-file protection, MiniVCS stores a full local `.bak` copy instead. This applies to binary-file backup/rollback protection, and deletion protection also stores a full local copy in `~/.openclaw/minivcs/trash/`. The user must be informed before the operation because storage usage may be relatively high.
- **The first record cannot be rolled back**: When a file is recorded for the first time, there is not yet any historical baseline, so that record has no snapshot. After that, each call to `record_modify` following an edit automatically saves a snapshot, allowing rollback to the state before any edit.
- **Local storage notice**: Protection data is stored locally under `~/.openclaw/minivcs/`. This Skill does not provide encryption or remote sync.
---
## Prerequisite Check: Confirm Python Is Installed
**Before performing any operation, you must first check whether Python 3 is installed in the user's environment. This Skill requires Python 3 and should not run without it.**
### How to check
```bash
# macOS / Linux
python3 --version
# Windows (PowerShell)
python --version
```
- If the output is `Python 3.x.x`, it is installed and you can continue
- If it says `command not found` or `is not recognized as an internal or external command`, stop and tell the user that this Skill requires Python 3
### Dependency boundary
If Python 3 is missing:
- Do **not** run dependency installation commands from this Skill
- Do **not** run remote install scripts such as `curl | bash`
- Do **not** write to shell config files such as `~/.zshrc` or `~/.bash_profile`
- Do **not** modify global environment variables on the user's behalf from this Skill
- Tell the user that Python 3 is required, and ask them to install it first or explicitly authorize a separate environment-setup flow
> **Note**: On some Windows systems the command is `python`, while on macOS/Linux it is `python3`.
> In all commands below that use `python`, replace it with the correct command for the actual environment.
---
## Retention Policy
| File Type | Retention Days | Decision Rule |
|---------|---------|---------|
| Important files | **14 days** | System paths (`/etc/`, `/root/`, `/usr/local/etc/`, `/opt/`), user config directories (`~/.ssh/`, `~/.gnupg/`, `~/.config/`, `~/.openclaw/`, `~/.kube/`, `~/.docker/`, `~/.aws/`, `~/.azure/`, `~/.local/share/`), Windows system directories (`C:\Windows\`, `C:\ProgramData\`, `C:\Program Files\`), config files (`.yaml/.toml/.env`, etc.), entry files (`main.py/index.ts`, etc.) |
| Normal files | **7 days** | All other files |
When each record is created, the `expireAt` (expiration timestamp) and `expireAtDatetime` (human-readable time) fields are set automatically.
---
## Excluded Paths (Auto-Skip)
Files whose path contains any of the following segments are **automatically skipped** by `record_modify` and `record_delete`. These are generated, vendored, or cache directories that should not be version-tracked:
`node_modules`, `.git`, `__pycache__`, `.venv`, `venv`, `.tox`, `.mypy_cache`, `.pytest_cache`, `.ruff_cache`, `dist`, `build`, `.next`, `.nuxt`, `.turbo`
When a file is skipped, the return value will contain `"skipped": true` and a `"reason"` field. The Agent should inform the user that the file was not tracked and explain why.
---
## Binary File Size Warning
When a binary file exceeds **50 MB**, the return value from `record_modify` (binary backup) will include:
- `"sizeWarning": true`
- `"sizeWarningMessage"`: a human-readable description of the file size and threshold
**When `sizeWarning` is present, the Agent must explicitly inform the user of the file size and ask for confirmation before proceeding with any further binary backup operations on similarly large files.**
---
## Operation Flow
### Step 1: Initialize the MiniVCS Working Directory
On first use, the storage directory is created automatically. No extra action is required:
```bash
python "$SKILL_DIR/scripts/minivcs/minivcs.py" history --project-root <project_root>
```
All data is stored uniformly in `~/.openclaw/minivcs/`:
```
~/.openclaw/minivcs/
logs.json # operation log (includes the expireAt field)
diffs/ # incremental patches for text file modifications
bases/ # baseline for the next comparison (named by full relative path, so no same-name conflicts)
snapshots/ # full snapshots before text file modifications (used for rollback)
trash/ # full backups of deleted files (used for restore)
backups/ # full `.bak` copies of binary files (used for rollback)
```
---
### Step 2: Ask the User for Confirmation Before the Operation
**Before deleting or modifying a file, you must explain the following to the user and wait for confirmation:**
1. The file path to be operated on
2. The operation type (modify / delete)
3. The purpose and intent of the operation
4. The possible impact
5. **Explain the local storage behavior: this Skill stores protection data under `~/.openclaw/minivcs/`**
6. **For text-file modifications, explain that MiniVCS stores diffs and snapshots so the file can be rolled back**
7. **For deletions, explain that MiniVCS stores a full local copy in `~/.openclaw/minivcs/trash/` so the file can be restored**
8. **If the file is binary, explicitly explain that protection uses a full local copy rather than a text diff, and ask whether the user wants that local copy to be stored before deletion or binary-file protection**
9. **If a binary backup returns `sizeWarning: true`, the Agent must display the file size and warning message to the user, and ask for explicit confirmation before proceeding**
If the file is binary and the user does **not** want a local stored copy, do not treat the operation as a protected delete/rollback flow under this Skill.
If the path is auto-skipped (return contains `"skipped": true`), inform the user that the file was not tracked and state the reason.
Example before the operation:
```
I am about to operate on the following file. Please confirm:
- File: /path/to/file.py
- Operation: delete
- Reason: This file has been replaced by a newer version and is no longer used
- Impact: Need to confirm that no other module imports this file
- Local storage: A full local copy will be stored under ~/.openclaw/minivcs/trash/ so the file can be restored later
- Protection: The stored copy will be retained for 7 days (14 days for important files), and can be restored at any time during that period
Do you want to continue?
```
Example for a binary file before deletion:
```
I am about to delete the following binary file. Please confirm:
- File: /path/to/file.pdf
- Operation: delete
- Reason: This file is no longer needed
- Impact: The original file will be removed from its current location
- Local storage: To protect this binary file, I need to store one full local copy under ~/.openclaw/minivcs/trash/
- Note: Binary files are protected with full copies rather than text diffs, so this may use more disk space
Do you want me to keep that local backup before deletion?
```
After the operation completes, **you must inform the user of the record result**, for example:
```
# After a modification is completed
The modification to path/to/file.py has been completed, and this change has been recorded (Record ID: 1710000000000).
- Change summary: +5 lines, -2 lines
- Retention period: 7 days (expires at: 2026-03-20 10:00:00)
- Rollback available: yes (use restore 1710000000000 to recover the state before the modification)
If you want to view the diff or roll it back, let me know.
# After a deletion is completed
path/to/file.py has been moved to the trash and backed up (Record ID: 1710000001000).
- Retention period: 14 days (expires at: 2026-03-27 10:00:00) [important file]
If you want to restore this file, let me know.
```
---
### Step 3: Operate on Files with MiniVCS
#### Modify a file (supports rollback)
**Just call `record` once after each edit**. The snapshot chain is formed automatically and supports rolling back to any historical state:
```
First time using this file → record() → base established (no snapshot, first record cannot be rolled back)
Edit → C1 → record() → snapshot=initial content, R1 rollback available
Edit → C2 → record() → snapshot=C1, R2 rollback available → restoring R2 gives C1
Edit → C3 → record() → snapshot=C2, R3 rollback available → restoring R3 gives C2 (that is, the state at time t2)
```
```bash
# Run once after each edit is completed
python "$SKILL_DIR/scripts/minivcs/minivcs.py" record <file_path> --project-root <project_root>
# Output containing "Rollback: available" means the snapshot has been saved and can be rolled back
```
Python API:
```python
import sys, os
sys.path.insert(0, os.path.join(SKILL_DIR, "scripts", "minivcs"))
from minivcs import MiniVCS
vcs = MiniVCS(project_root="/path/to/project")
# Call once after each edit
result = vcs.record_modify("path/to/file.py")
# result includes:
# {
# "success": True,
# "recordId": "...",
# "summary": "+5 lines, -2 lines",
# "canRollback": True, # True when a snapshot exists; False for the first record
# "snapshotFile": "...",
# "isImportant": False,
# "retentionDays": 7,
# "due_for_cleanup": [...]
# }
```
#### Delete a file (supports restore)
**Do not delete the file directly**. Use `record_delete` instead, and the file is moved into `trash` automatically.
Before running `record_delete`:
- Tell the user that a full local copy will be stored in `~/.openclaw/minivcs/trash/`
- If the file is binary, explicitly ask whether they want that local copy to be stored
- Only proceed with protected deletion after the user confirms the local storage behavior
```bash
python "$SKILL_DIR/scripts/minivcs/minivcs.py" delete <file_path> --project-root <project_root>
```
Python API:
```python
result = vcs.record_delete("path/to/file.py")
# result includes:
# {
# "success": True,
# "recordId": "...",
# "trashFile": "~/.openclaw/minivcs/trash/1234567_file.py.bak",
# "isImportant": True,
# "retentionDays": 14,
# "due_for_cleanup": [...]
# }
```
#### Restore / Roll back
The same `restore` command handles both scenarios:
```bash
# DELETE record -> restore the file to its original path
# MODIFY record (with snapshot) -> roll back to the state before the modification
python "$SKILL_DIR/scripts/minivcs/minivcs.py" restore <record_id> --project-root <project_root>
```
Python API:
```python
result = vcs.restore_file(record_id="...")
# After DELETE succeeds: the record is marked as RESTORED and no longer appears in the trash list
# After MODIFY succeeds: the record is marked as ROLLED_BACK
# Repeated restore: returns {"success": False, "error": "already been restored/rolled_back"}
```
---
### Step 4: Handle Expired Cleanup Notifications (must be done after every operation)
After each call to `record_modify` or `record_delete`, the return value contains the `due_for_cleanup` field.
**If `due_for_cleanup` is not empty, the Agent must:**
1. Show the user the list of expired records (sorted from earliest to latest)
2. Ask which ones can be deleted and which ones need an extension
Example display format:
```
The following N historical records have expired. Please confirm whether they can be cleaned up:
[1] ID=1710000000000 File=src/old.py Action=MODIFY
Recorded at=2026-03-01 10:00:00 Expires at=2026-03-08 10:00:00
[2] ID=1710000001000 File=config.yaml Action=DELETE [important file]
Recorded at=2026-02-28 09:00:00 Expires at=2026-03-14 09:00:00
Can these records be deleted? (delete all / specify which ones to extend)
```
Handling after the user responds:
```python
# The user confirms deleting all
result = vcs.delete_due_records(record_ids=["id1", "id2"])
# The user says not to delete one record yet -> extend by one retention cycle (7 days or 14 days)
result = vcs.extend_record_expiry(record_id="id1")
```
Command line:
```bash
# View all expired records
python "$SKILL_DIR/scripts/minivcs/minivcs.py" cleanup --project-root <project_root>
# Confirm cleanup
python "$SKILL_DIR/scripts/minivcs/minivcs.py" cleanup --confirm --project-root <project_root>
# Extend one record
python "$SKILL_DIR/scripts/minivcs/minivcs.py" extend <record_id> --project-root <project_root>
```
---
## Other Common Operations
```bash
# View operation history (records marked [rollback available] can be rolled back)
python "$SKILL_DIR/scripts/minivcs/minivcs.py" history --project-root <project_root>
python "$SKILL_DIR/scripts/minivcs/minivcs.py" history <file_path> -d --project-root <project_root>
# View files in trash that have not yet been restored
python "$SKILL_DIR/scripts/minivcs/minivcs.py" trash --project-root <project_root>
# Delete a specified record (clean both the log and the physical file)
python "$SKILL_DIR/scripts/minivcs/minivcs.py" remove <record_id> --project-root <project_root>
```
---
## Record Field Reference
| Field | Type | Description |
|------|------|------|
| `recordId` | string | Unique record ID (millisecond timestamp) |
| `filePath` | string | Relative or absolute path |
| `action` | string | `MODIFY` / `DELETE` / `BINARY_BACKUP` / `RESTORED` / `ROLLED_BACK` |
| `timestamp` | number | Creation time (milliseconds) |
| `datetime` | string | Creation time (human-readable) |
| `isImportant` | bool | Whether the file is important |
| `retentionDays` | number | Retention days (7 or 14) |
| `expireAt` | number | Expiration time (milliseconds) |
| `expireAtDatetime` | string | Expiration time (human-readable) |
| `diffFile` | string | Diff patch path (MODIFY only) |
| `snapshotFile` | string | Pre-modification snapshot path (only present when MODIFY has a snapshot) |
| `trashFile` | string | Trash backup path (DELETE only) |
| `backupFile` | string | `.bak` copy path (BINARY_BACKUP only) |
| `summary` | string | Change summary |
---
## Full Operation Flow Diagram
```
The user requests a modification/deletion
│
▼
[Ask for confirmation] Explain the purpose, impact, and existing protection -> wait for user confirmation
│
├─── Modify file ───────────────────────────────────────────────┐
│ 1. Perform the actual modification │
│ 2. record_modify (Diff + snapshot -> canRollback=True) │
│ snapshot = content before this modification, so │
│ historical states can be rolled back step by step │
│ │
└─── Delete file ──────────────────────────────────────────────┤
record_delete (move to trash, do not delete directly) │
│
┌─────────────────────────────────────────┘
▼
Tell the user: Record ID / retention period / rollback or restore availability
│
▼
Check the returned value `due_for_cleanup`
│
┌───────────┴───────────┐
Expired records exist No expired records
│ │
▼ ▼
Show expired records Operation complete
(from earliest to latest)
Ask the user for confirmation
│
┌───────┴──────────┐
Confirm deletion Do not delete yet
│ │
▼ ▼
delete_due_records extend_record_expiry
(extend by one retention cycle)
------- When the user needs rollback/restore -------
User: "Help me restore/roll back xxx"
│
▼
restore_file(record_id)
├── DELETE record -> restore from trash and mark as RESTORED
└── MODIFY record (with snapshot) -> write back snapshot content and mark as ROLLED_BACK
```
don't have the plugin yet? install it then click "run inline in claude" again.