Skip to main content
@obversa/engine-claude-cli runs Claude Code as an engine: every request is one fresh claude process, so every step starts with a clean context and nothing leaks from one step to the next. Use it for the Claude seats in a team.

​
Install

Included in @obversa/obversa. Each process runs Claude Code clean by default: with your own login and the repository’s settings and instruction files, but without your own settings, hooks, plugins, skills and MCP servers. Set clean: false to run it the way you run it, with your own settings too. The plugin adds only what the step needs, through Claude Code’s own flags.

​
Requirements

  • Claude Code installed and signed in. The plugin accepts any version the CLI reports. It was run by hand against Claude Code 2.1.286. Its unit tests use a stand-in CLI. The claude command must be on your PATH, or you pass its path as cliBinary. The plugin has no API key option.

​
Identity

The plugin reports provider: 'anthropic' and model family claude. It runs the model the request names, or defaultModel when the request names none.

​
Quickstart

claude(model) is the seat helper a workflow() role takes:
examples/teams/writer-reviewer-pair.ts (excerpt)
The seat starts Claude Code unattended and able to write files. It doesn’t use the mode that only accepts edits, because that mode would block the commands a headless run needs; pass ClaudeSeatOptions to choose another permissionMode. new ClaudeCliEngine(options) is the same engine without the seat identity, for a job or a graph binding you assemble yourself.
Run a Claude seat in a directory you’re happy for a model to change. It runs with permission prompts off, so it can run any command the process can.

​
Options

​
permissionMode

default, acceptEdits, bypassPermissions, plan, dontAsk or auto, passed to the CLI. In the read workspace mode Claude gets only the Read, Grep and Glob tools the request names; in none it gets no tools. Both modes block Bash, Edit, Write, the sub-agent tools and every MCP tool. With clean: false Claude Code also loads your own settings, and they can’t restore those tools. Your own hooks run too, though, and a hook can write files; a clean run leaves your hooks out.

​
clean

true runs Claude Code with --setting-sources project and --strict-mcp-config. Your own settings, hooks, plugins, skills, MCP servers and ~/.claude/CLAUDE.md stay out. The repository’s settings and instruction files still apply, and the run keeps your login. ClaudeSeatOptions takes the same clean option. Its row in the engines table: runs on your setup, clean mode available, read-only held in clean mode. On your own setup the model’s tools stay read-only, but your own hooks still run and can change files. Clean mode also leaves out the repository’s own MCP servers, because the switch that keeps yours out keeps every server out.

​
The rest

​
Errors

  • EngineError of kind missing-cli when the executable can’t run.
  • A usage or rate limit is read from what the CLI printed when a run fails, so the failure is typed as a limit rather than a plain error.

​
API

  • claude(model, options?): a TeamSeat for a workflow role. Quickstart.
  • ClaudeCliEngine: the engine class. ClaudeCliEngineOptions, ClaudeSeat, ClaudeSeatOptions: its types.
  • buildClaudeArgs, classifyCliLimit, parseResetAt: the argument builder and the limit readers, exported for tests.

​
Next steps