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 TypeRetention DaysDecision RuleImportant files14 daysSystem 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 files7 daysAll 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/:

text

~/.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:

text

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:

text

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:

text

# 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:

text

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:

text

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#

FieldTypeDescriptionrecordIdstringUnique record ID (millisecond timestamp)filePathstringRelative or absolute pathactionstringMODIFY / DELETE / BINARY_BACKUP / RESTORED / ROLLED_BACK``timestampnumberCreation time (milliseconds)datetimestringCreation time (human-readable)isImportantboolWhether the file is importantretentionDaysnumberRetention days (7 or 14)expireAtnumberExpiration time (milliseconds)expireAtDatetimestringExpiration time (human-readable)diffFilestringDiff patch path (MODIFY only)snapshotFilestringPre-modification snapshot path (only present when MODIFY has a snapshot)trashFilestringTrash backup path (DELETE only)backupFilestring.bak copy path (BINARY_BACKUP only)summarystringChange summary

---

Full Operation Flow Diagram#

text

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