> ## Documentation Index
> Fetch the complete documentation index at: https://obversa.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude CLI Engine

> @obversa/engine-claude-cli: Claude Code as a seat, one fresh process per call.

`@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

<CodeGroup>
  ```bash npm theme={null}
  npm install @obversa/engine-claude-cli
  ```

  ```bash pnpm theme={null}
  pnpm add @obversa/engine-claude-cli
  ```
</CodeGroup>

Included in `@obversa/obversa`.

Each process runs Claude Code [clean](#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:

```ts examples/teams/writer-reviewer-pair.ts (excerpt) {2} theme={null}
    roles: {
      write: engines.claude('claude-sonnet-4-5'),
      review: [engines.codex('gpt-5.6-luna')],
    },
```

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.

<Warning>
  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.
</Warning>

## 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](/docs/packages/engines#the-engines): 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

| Field | Type | Default | Description |
| - | - | - | - |
| `defaultModel` | `string` | none | The model when the request names none. |
| `cliBinary` | `string` | `claude` on `PATH` | The executable to run. |
| `cliArgs` | `readonly string[]` | none | Extra arguments for every call. |
| `effort` | `string` | none | Passed as `--effort <level>`. A request's `effort` wins. Also a `ClaudeSeatOptions` field. See [Reasoning effort](/docs/packages/engines#reasoning-effort). |
| `clean` | `boolean` | [See the default](/docs/packages/engines#the-default) | On by default: your own setup stays out. `false` runs on your own setup. [`clean`](#clean). |

## 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](#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

* [A writer and a reviewer](/docs/patterns/writer-and-reviewer): a Claude seat
  writing and a Codex seat reviewing, with a real run.
* [Claude Agent SDK Engine](/docs/packages/engine-claude-agent-sdk): the same
  sign-in through the SDK instead of the CLI.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.