ClearFrame Docs — Install, agents, checkpoints and the Store

How ClearFrame works in practice: installing it, running a first task, reviewing what an agent produced, recovering files, bounding usage, and extending agents. Each section states the limits that apply.

Getting started

ClearFrame is a desktop application for Apple silicon Mac. Intel Mac, Windows, Linux and the phone companions have waitlists on the download page. Join for an email when access opens. The page lists the exact version, byte size and SHA-256 for every artifact it does offer, so you can verify what you installed.

In the current desktop builds, sign in through Settings → Account to use Free's included starter AI use. With Pro, you can choose to connect your own model provider. That provider can apply its own limits or bill separately under its terms; see pricing before choosing that route. The web waitlist accepts your email address so we can tell you when access opens.

1. Install the build for your platform and launch ClearFrame.
2. Open Settings → Account and sign in with your email to use the included starter AI use.
3. Pick or create a project folder in Settings → General, then open a session for your first task.

Your first agent task

A task is a goal plus the project it works on. Describe the outcome rather than the steps — "make the settings page work offline" rather than "edit settings.js" — because the agent decides which files to touch and reports what it did.

Choose the access level for the task before you start it. Changing the access level mid-task is supported: ClearFrame closes the task's persistent shell before the change takes effect, so the new level always applies to the next command rather than appearing to be stuck on the previous setting.

Reviewing and integrating changes

Agents work in isolated copies of your project, so a suggestion does not land in your working tree until you integrate it. Review the proposed files, edit them directly if you want, and then integrate. Running the app beside the conversation is the intended feedback loop: you see the result rather than inferring it from a diff.

Parallel tasks each get their own isolated copy, which is what makes running two agents on related work safe. Integration is explicit, so you decide when two lines of work meet.

Recovering files

ClearFrame snapshots eligible project files before a task first uses a tool. This works independently of Git, so projects that are not yet version controlled are still recoverable, and manual edits made outside the agent are covered too as long as they touch files inside the snapshot set.

Restoring selected files saves a "Before undo" checkpoint, so an undo is itself undoable. Snapshots exclude generated and dependency folders, files outside the project, and external services. Limits apply: 30,000 files or 512 MiB. This is file recovery rather than full conversation rewind.

Managing usage and limits

The Active panel shows usage as a percentage remaining and offers two kinds of stop: a token ceiling, and a stop at a selected percentage of managed-plan usage. Set them before starting unattended work.

These are measured usage stops, not a guarantee of zero overshoot — work already in flight can still consume usage. Remote execution, where enabled, shows its additional usage estimate before you start, and charges on provider accounts you connected yourself are separate from ClearFrame usage.

Project memory and instructions

Project instructions persist between tasks and are inspectable in the Memory panel, so you can see what the agent carries forward instead of guessing. Bounded project memory is how a lesson from one task reaches the next without re-explaining your conventions every time.

For the opt-in Self-Host workflow, proposed skills require two passing evaluations before installation, which keeps an unverified lesson from becoming permanent behaviour.

Extending agents

Agents can be extended three ways: the Store for packaged abilities, project skills for reusable instructions, and MCP servers for connecting external tools and data.

MCP servers let an agent reach systems outside the project — a database, an issue tracker, a browser. Each connection is configured deliberately rather than discovered automatically, because an agent's reach is also its risk surface.

Use Observatory to inspect the public MCP Safety Index, upload a local scan receipt, or review your saved checks. The setup guide includes local scan and CI commands. Results describe the checks that ran; they are not a security certification.

The Self-Host workflow

Self-Host is an opt-in capability, currently validated on macOS, that lets ClearFrame work on its own source: edit, run tests, verify the installed beta, then promote and resume. Its improvements live in code, skills and runtime configuration.

Tests control continuation. A failed evaluation holds the next automatic step rather than pushing forward, and a promotion must survive startup, renderer health and a fresh-activity check; a failed check can restore the previous build.

ClearFrame in your terminal

Download the Apple silicon Mac CLI, unzip it, then open Terminal in the extracted folder:

./clearframe-cli/install.sh
export PATH="$HOME/.local/bin:$PATH"
clearframe login
clearframe account
clearframe models
clearframe run "Explain this project" -C /path/to/project
clearframe run "Fix the failing tests" -C /path/to/project --access workspace-write

login opens ClearFrame’s browser sign-in and displays a verification code. Use your existing account, finish authorization, and return to Terminal. For email sign-in in Terminal, use clearframe login --email you@example.com and enter the emailed code at the prompt. The credential is saved in macOS Keychain; clearframe logout removes the CLI sign-in. Your existing plan and usage apply. The download includes Node.js and the agent runtime.

Tasks default to read-only access. Choose --access workspace-write for project edits or --access full for unrestricted tool access. --json returns a result for scripts. clearframe doctor checks setup, and run --dry-run checks your account, available model and runtime configuration without calling a model. Ctrl-C cancels a task; --timeout sets its deadline in milliseconds.

Team members can inspect billing contexts with clearframe account and choose --context personal or --context team:ID. To uninstall, sign out, remove ~/.local/bin/clearframe and the version folder under ~/.local/lib/clearframe/.

Getting help

Email support@clearframecode.com for account or installation problems. The FAQ answers the questions that come up before adopting ClearFrame, and Security covers how your code, credentials and account data are handled. Release notes for every version are published under Updates.