Skip to main content
An engine runs clean by default: your own setup stays out, your login and the repository’s setup stay in. Set 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.md and project config are part of the code the run works on.
  • Your login stays. The run still uses your own sign-in and subscription.
Not every CLI can leave all of your setup out. Where an engine falls short says what stays in.

​
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 }) or new ClaudeCliEngine({ clean: false }).
  • Claude Agent SDK. new AgentSdkEngine({ clean: false }).
  • Codex CLI. codex(model, { clean: false }) or new CodexEngine({ clean: false }).
  • OpenCode CLI. opencode(model, { executable, clean: false }) or new OpenCodeCliEngine({ ...options, clean: false }).
  • Devin CLI. devin(model, { clean: false }) or new DevinCliEngine({ clean: false }).
  • Grok CLI. Always runs on your setup; clean: true throws an error that says why. Grok has no clean mode.

​
The engines

“Read-only held” means a step in the read 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, so the step fails and says why. A read step that only reads answers normally.
  • OpenCode CLI. Your own skills in ~/.claude/skills and ~/.agents/skills still 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.
Each run gets a fresh scratch repository. In each mode, one read-only step is asked to create a file, and a second one reads a word back from a file. A write-mode run on your own setup is the control: it shows the same prompt does make the engine write when writing is allowed. The proof prints one table, with one row for each engine in each mode:
  • 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.

​
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 clean option and the read workspace mode.
  • API: how the conformance kit checks an engine’s clean mode.