Self-Host · Architecture

Letting an agent modify its own source code

ClearFrame 1.15.9 changed how a task switches access levels. The change was made by the agent, tested, checked against the installed build, and promoted — the workflow the product uses on its own source.

Last updated September 28, 2026

September 18, 2026 · Self-Host · Architecture · 6 min read

Self-Host is disabled by default. It has to be enabled and confirmed before the agent will work on the repository it is running from.

The loop

Once enabled, the loop has four stages, and the order is the design.

Edit source

The agent changes the project it is running from.

Run tests

The change must pass the project's own evaluation before the loop continues.

Verify the installed build

Startup, renderer health and fresh activity in a restored task.

Promote and resume

The change becomes the running build.

A failed evaluation halts the loop

The agent does not decide that its change was probably adequate and continue. The evaluation result determines whether the loop proceeds, and a failure stops it. In an ordinary agent loop the model's judgement is the gate; here an external and deterministic check is the gate, and the model's judgement produces only the candidate change.

Tests are not sufficient

A change can pass every unit test and still leave the application unable to open. That failure is the one that makes self-modification dangerous, and a test suite does not observe it. Promotion therefore checks the application itself: that it starts, that the renderer is healthy, and that a restored task shows fresh activity rather than a frozen pane.

A failed check can restore the previous build. The gate is not only whether a change passes, but whether a way back exists when it does not.

Approvals when the repository is the product

Self-Host raises a question that ordinary agent work does not. When the project being modified is the tool performing the modification, which changes proceed without review? The capability has its own settings for this, including how approvals behave for the repository being self-hosted and whether parallel child tasks are permitted.

The distinction is worth preserving in the control surface. "The agent may work on itself" and "the agent may work on itself without asking" are different permissions, and a single switch covering both would grant the second while describing the first.

The ordinary machinery applies

Changes to ClearFrame's own source pass through the same review, checkpoint and commit path as any other project. The recovery layer described in file recovery covers the agent's own code, which is the reason the capability rests on existing machinery rather than a separate engine.

Stated limits

Validated on macOS. The capability is documented for the platform on which it has been validated.
Opt-in. Disabled by default, enabled and confirmed deliberately.
Improvements live in code, skills and runtime configuration. Self-Host changes the product. It is not a general mechanism for rewriting the agent's behaviour.
A passing evaluation is not a proof of correctness. It means the project's own checks passed and the build survived promotion. That is a stronger claim than "the model reported success" and a weaker claim than "this change is correct".

The problem tests cannot cover

A test suite runs against source. The application runs against a built artefact inside a packaged bundle, started by the operating system, rendering through a process the tests never instantiate. The gap between those two things is where a self-modifying tool fails, because a change can satisfy every assertion in the repository and still produce an application that does not open.

That is why promotion checks properties no unit test observes. Startup is the first: does the process reach a running state. Renderer health is the second: is the interface actually rendering rather than present and blank. Fresh activity in a restored task is the third, and it is the most specific of the three. A task restored from saved state has to show that it is doing something, which distinguishes a working restore from a frozen pane that looks like a loaded task.

The three checks share a property worth naming: each one is observable from outside the process being verified. A check that asked the newly built application whether it was healthy would be asking the code under test to grade itself.

What restoration means

The previous build can be restored when a promotion fails. This is the property that makes the workflow reasonable to attempt at all, because it converts a failed promotion from a broken installation into a repeated iteration. A loop that can only move forward is a loop that has to be right every time; a loop with a way back can be wrong occasionally.

The settings, and why they are separate

Self-Host has its own configuration rather than borrowing the ordinary task defaults. Enabling it requires a second confirmation, so the capability cannot be switched on by a single misread toggle. Beyond that, the settings cover how approvals behave for the repository being self-hosted and whether parallel child tasks are permitted.

Those two settings exist because a self-hosting repository is a different risk profile from an ordinary project. A change to an application someone else wrote can be reviewed against the specification. A change to the application performing the review has no external reference point, which is precisely why the gates are external and deterministic rather than a matter of the agent's confidence.

The narrower claim

Self-Host is often described as an agent that improves itself. The more accurate description is narrower: an agent whose candidate changes to its own source are subject to the same evaluation and promotion gates as any other change, with a recovery path when a gate fails. The improvement is not a property the agent possesses. It is a property of the loop, and the loop is built so that the agent cannot decide when it has passed.