clean: false on an engine or a seat
when a run should use your own setup, the way you run the tool yourself.
Every engine also takes effort, the reasoning level a step runs at:
see Reasoning effort.
The default
On every engine that can run clean,clean is on by default, so a workflow
behaves the same for everyone who runs it. Set clean: false to run on your
own setup. Grok has no clean mode, so it always runs on your setup unless
you pass authFile. The API, Mastra and OpenAI Agents SDK engines load no setup and have no
clean option. The engines table shows each one.
What a clean run leaves out
- Your own setup stays out. Your personal settings, hooks, plugins,
skills, MCP servers and global instruction files, such as
~/.claude/CLAUDE.md, don’t load. - The repository’s setup still applies. Its
AGENTS.md,CLAUDE.mdand project config are part of the code the run works on. - Your login stays. The run still uses your own sign-in and subscription.
Turn it off
The option has the same name on every engine. Clean is the default; this is how to run on your own setup instead:- Claude CLI.
claude(model, { clean: false })ornew ClaudeCliEngine({ clean: false }). - Claude Agent SDK.
new AgentSdkEngine({ clean: false }). - Codex CLI.
codex(model, { clean: false })ornew CodexEngine({ clean: false }). - OpenCode CLI.
opencode(model, { executable, clean: false })ornew OpenCodeCliEngine({ ...options, clean: false }). - Devin CLI.
devin(model, { clean: false })ornew DevinCliEngine({ clean: false }). - Grok CLI. Always runs on your setup;
clean: truethrows an error that says why. Grok has no clean mode.
The engines
“Read-only held” means a step in theread workspace mode was asked to
create a file, and no file in the repository changed.
Where an engine falls short
- Claude CLI and Claude Agent SDK. On your own setup, your own hooks still run during a read-only step, and a hook that writes files still writes. Clean mode also leaves out the repository’s own MCP servers.
- Codex CLI. Your own skills and command rules still load in clean mode.
- Devin CLI. Your own MCP servers, skills and personal rules can still
load in clean mode: clean mode replaces only your Devin settings file.
In a read step, Devin refuses a write and no file changes. Devin then
ends the whole run without an answer. The plugin continues the run, up to
refusalRetriestimes, 2 by default. When Devin is still refused, the step fails and says why. A read step that only reads answers normally. The default write mode,accept-edits, edits files but refuses a command; a builder that runs its tests needsdevin(model, { permissionMode: 'dangerous' }). - OpenCode CLI. Your own skills in
~/.claude/skillsand~/.agents/skillsstill load in clean mode. OpenCode’s switch that skips them also skips the repository’s own skills. Clean mode moves the whole config folder, so commands the step runs lose their settings in it too. - Grok CLI. No clean mode: Grok’s strict sandbox reads no login outside
its own home folder. Your own MCP servers start in every run; a step that
declares no MCP tool keeps their tools from the model. Grok’s workspace
sandbox lets a write step also change files in Grok’s own home folder,
~/.grok, and in temporary folders.
Check it on your own machine
From a clone of the repository, build the packages and run the proof. It runs each installed CLI the ordinary way, with your own logins, so it spends a little of each subscription. It isn’t part of CI.- Engine. The engine the row is about. Its first row shows the version of its CLI.
- Run. The mode: your setup or clean, and read or write.
- Answered. Whether the engine replied with the word from the file.
- Files changed. Whether the step asked to create a file changed any
file in its scratch repository.
-means that step failed without changing a file, so it shows nothing about read-only. - Note. Which files a step changed, or why a step failed.
Input limits and login errors
An engine may declare how much input one request may hold, in characters or in tokens. The runtime measures a limit in tokens as one token per two characters. That ratio is lower than any measured on a real prompt, so a prompt measured as fitting does fit. A step whose input is larger than its engine’s limit pauses before the call, and its reason names the size and the limit. A review step first lists data files instead of inlining them; see What a reviewer reads. An engine that declares no limit is treated as having none.
A login error is an
auth failure. The runtime runs the same seat once
more, then the seat’s next candidate. The Grok engine stops an attempt at
once when Grok prints a login error and keeps running. Before a call under
Grok’s strict sandbox it refreshes a login that would expire during the
call. Each engine’s own page says what it does.
Reasoning effort
effort sets how hard the model thinks. Every engine takes it under the
same name. Set it on a seat or an engine for every step, or on one
agentJob or workflow agent stage for that step only. A step’s effort
wins over the seat’s. A fallback route does not take the step’s effort;
give the route its own.
Each tool has its own levels, so the engine passes the level you give it
unchanged. When you leave effort unset, the engine passes nothing and the
tool’s own default applies, such as the level in your own Codex config.
An engine with no effort setting refuses effort with an error that says
why. When an engine runs with an effort, the
node attempt record names it in the engine’s
requested and effective identities, next to the model. An excerpt of one
identity:
Next steps
- Claude CLI Engine: the
cleanoption and the read workspace mode. - API: how the conformance kit checks an engine’s clean mode.