File recovery for projects that are not Git repositories

September 18, 2026 · Recovery · Architecture · 6 min read

Version control answers the question of what a file said before it changed. A project that has never been placed under version control has no answer, and there is no repository to create one from until somebody decides the project is worth keeping.

ClearFrame's recovery layer addresses that interval. It records the state of a project before an agent first touches it, and it does so without requiring a repository.

What is recorded

Before a task uses its first tool, ClearFrame takes a snapshot of the project. The application lists the coverage in the review panel, in its own words: source files, untracked files, binary files, executable permissions and symlinks.

The last entry is the one that changes how the review reads. If recovery covered only the agent's edits, the review would show roughly half of what moved, and the rest would have to be recalled from memory. ClearFrame compares each file against the checkpoint regardless of which party changed it.

What is not recorded

The same panel states the exclusions. Generated and dependency folders are left out, and the list of them is named on screen rather than held in a configuration file. Two boundaries follow, and ClearFrame states both in the interface:

• External files are not rolled back.
• External services are not rolled back.

The second is a limit of the mechanism rather than an oversight. A snapshot operates on a file system. It cannot retract an HTTP request that has already been sent, revert a row already written to a database, or unsend a message.

Recovery restores a selection

The review panel presents the checkpoint as a list of files with the changes since it: "Changes since the selected checkpoint, including manual edits. Review before restoring or committing." Files are selected, then restored or committed.

Restoring is itself checkpointed. The application names that state "Before undo", so reversing a restore is available. The design choice is against a single project-wide undo, which would discard the work worth keeping along with the change worth discarding.

It restores files, not conversations

ClearFrame restores files. It does not rewind the conversation, the agent's memory, or the plan the task was executing. A restore returns the files to a known state; the context that explains how they reached the earlier state remains. The distinction matters because the two are frequently described as one capability.

Committing, where a repository exists

Snapshots do not replace version control. They cover the period before a repository exists, and the changes that never reach a staging area.

Where the project is a Git repository, the review panel can commit. The application states the property that matters on screen: committing writes to the repository, and "only the files selected here. Every other change in the project is left as it is, staged work included."

One condition is unavoidable. Committing requires a repository that already has a commit, "so a commit has nothing to build on". ClearFrame says so, and directs the user to make the first commit in a terminal. It does not create a root commit on the user's behalf.

Reading a checkpoint

A checkpoint is not a single opaque restore point. The review panel presents a selector listing every checkpoint taken for a task, and the first entry is named "Task start" rather than a timestamp. Selecting one shows the changes since it. The panel describes what is on screen in one line: "Changes since the selected checkpoint, including manual edits. Review before restoring or committing."

That wording is precise in two places. The selection is a diff rather than a snapshot viewer, and manual edits are inside it. A reviewer who trusts the panel sees every change to a covered file, whichever party made it.

Where a task has no checkpoints, the panel says so in a sentence that names the reason rather than leaving an empty list: "File checkpoints begin before this task uses its first tool. Earlier tasks have no retroactive backup." Checkpointing is not retroactive, and a task created before the feature existed has no coverage. ClearFrame states the boundary instead of implying coverage it does not have.

Why the exclusions are named on screen

The expansion list of excluded folders is rendered from the running configuration, not written into the copy. That matters because the list differs between projects: a Python project excludes a different set of directories from a Rust or Node project. Rendering it means the reader sees the boundary that applies to the project in front of them.

The alternative — documenting a fixed exclusion list — would be wrong for most projects and reassuring in the wrong way.

Where the design shows its history

Release notes record when these guarantees changed. Version 1.15.9 covers access levels rather than recovery, but it is an example of the same practice: the release note states the defect and the fix, and the note is published at a stable URL. The recovery layer's behaviour is documented in the same way, which is what makes a claim about it checkable rather than a matter of trust.

The property that makes it worth having

Snapshots are unremarkable until the moment they are needed, and the moment they are needed is the moment a project has no other record of what it looked like. The engineering decision is to take the record before knowing it is required, and to make the boundary of that record visible rather than implied.

Related reading: file recovery in the documentation, running two agents on one project, and the sourced capability comparison at ClearFrame vs Cursor, Claude Code and Codex.