Skip to main content
@obversa/engine-devin-cli runs Devin as an engine: every request starts a fresh devin -p process. Use it to put a Devin model in a writing, checking or review seat.

Install

Not in @obversa/obversa; install it on its own.

Requirements

  • The Devin CLI installed and signed in with your own account. The devin command must be on your PATH, or you pass its path as cliBinary.

Quickstart

devin(model?) is the seat helper a workflow() role takes, as claude(model) is for Claude. This file runs the seat once on a read-only question:
examples/engine-devin-cli-seat.ts
Run it with npx tsx engine-devin-cli-seat.ts in a git repository that holds an a.js with two exports. One run printed:
Output
The answer is Devin’s own text, as Devin wrote it. In a workflow, write devin('swe-2-max') to name the model. devin models list prints the models your account can use.

How it runs Devin

Devin runs clean by default: with your home folder and your Devin login, but with an empty config file in place of your Devin settings. With clean: false it runs as you run it yourself, with your Devin settings too. Either way it reads the repository’s own instruction files and rules. Your own MCP servers, skills and personal rules can still load in clean mode; the engines table has the detail. The plugin adds only these flags: Each attempt starts a new process and a new Devin conversation. The plugin never continues an earlier attempt’s conversation. In a read step, it can continue the attempt’s own conversation in a new process after Devin refuses a tool.

Identity

The plugin reports provider: 'cognition'. The model family is the first part of the model name: swe-2-max gives swe, and claude-opus-5-5-max gives claude. The result’s effective record names the model Devin reports for the run, so a seat with no model still records which model answered. Without a model, the seat records the model as default. Devin reports token counts in its conversation file, and the result carries them. If Devin reports none, usage is unknown.

Workspace modes

A step that names no workspace mode runs as read. A read step runs only with auto. When permissionMode names any other mode, a read step fails with invalid-config before Devin starts, so read-only holds.

A builder that runs commands

A write step under accept-edits can edit files, but it cannot run a command such as a test or a build. Devin refuses the command and ends the run without an answer. A builder that runs commands needs dangerous: devin('swe-2-max', { permissionMode: 'dangerous' }). dangerous auto-approves tool calls. A deny or ask rule from your organisation or your own Devin setup can still refuse one, and the run then ends without an answer. Run it in a directory you’re happy for a model to change. smart runs only the commands a fast model judges safe, so it can still refuse a command and end the run.

A reviewer that runs commands

A read step runs with auto. Devin decides by itself which commands auto runs. It runs some commands that only read, and refuses others, such as rg. In print mode a refused command ends Devin’s run without an answer. The plugin then continues the run, as A refused tool in a read step describes. The commands option lists more commands a read step may run, besides those auto runs by itself. Each entry is the start of a command. The plugin adds each entry to Devin’s allow list as Exec(<entry>), in the config file it writes for each attempt. Devin then runs a command that starts with the entry as whole words. Devin still refuses a command chained with && or ;, a redirect, or command substitution, and it checks each part of a pipe. There are no commands by default. A step can carry its own list. A read step whose allowedTools hold entries of the form Exec(<entry>) runs with those entries in place of the engine’s commands. The plugin checks them the same way. A read step with no Exec(...) entry runs with the engine’s commands. A list for review steps: devin('swe-2-max', { commands: ['git diff', 'git log', 'git show', 'git status', 'rg', 'grep', 'ls', 'cat', 'head', 'tail', 'wc'] }). Name the commands in the reviewer’s prompt. Devin may refuse a command outside the list. The plugin then continues the run with a message that names the list.
  • Clean mode. The commands go in the empty config file.
  • clean: false. The plugin writes a copy of your own Devin config file (~/.config/devin/config.json, or {} when it does not exist) with the commands added to permissions.allow, and passes the copy. Your own file is never written.
  • Write steps. A write step does not get the commands, in either mode. Its permission mode decides what it may run.
  • Refused entries. An entry that is empty, or holds &, ;, |, <, >, `, $ or a newline, cannot be one read-only command. devin() and new DevinCliEngine() throw a TypeError that names the entry.
  • The record. An attempt records the step’s tools. devin() adds each command as Exec(<entry>) to the seat’s tools, so a step on that seat lists them in its tools, and a reviewer’s record shows the commands it could run. A write step on that seat records them too, because the seat declares them, although Devin does not get them in a write step. With new DevinCliEngine({ commands }) and a step whose tools leave the rules out, Devin gets the commands but the record does not show them. The record lists the seat’s commands, and a step whose own list differs runs with its own list.
In print mode Devin cannot ask you. When Devin wants a tool that its permission mode does not approve, it refuses the tool and does not wait. Devin then ends the whole run without an answer.

A refused tool in a read step

When Devin refuses a tool in a read step, the plugin continues the same Devin session with devin -r <session id>. The continued run has the same config file, permission mode and flags. Its prompt is this message, here for a step with the commands git diff and git log:
For a step with no commands, the message ends with This step may run no shell command. Finish the task with your file reading tools only. The answer of the continued run is the step’s answer.
  • How many times. refusalRetries sets how many times the plugin continues the session in one attempt. It is 2 by default.
  • Turning it off. devin(model, { refusalRetries: 0 }) or new DevinCliEngine({ refusalRetries: 0 }). The first refusal then ends the step.
  • Limits. Every run in the attempt counts against the step’s one time limit and one output limit.
  • Usage. Devin’s export of a continued session holds the token counts of every run in the session, so the result’s usage covers every run in the attempt.
  • The record. Each continuation sends a tool event named devin --resume. Its target says what the refused tool call acted on: refused: rg TODO for the command rg TODO src, a file for a write, or the tool’s name.
  • Write steps. A write step is never continued. Its permission mode decides what it may do.
Read-only holds in a read step. A read step that only reads answers normally. A read step whose model tries to write gets the write refused, and no file changes. Devin then stops the run, and the plugin continues it. When Devin is refused again after the last continuation, the attempt fails with EngineIncompleteResultError. It fails the same way when Devin’s export names no session. The message says that Devin refused a tool in read mode, with the number of refusals, which ends its run without an answer, and that no file changed. It also repeats Devin’s last warning. A run in either mode that exits 0 and writes its conversation export, but has no final answer for any other reason, fails with the same error, and its message names the permission mode. A timeout, a non-zero exit or a missing export fails with its own error instead. A time limit that runs out during a continued run is a timeout.

What Devin cannot do through the plugin

  • No list of named tools. Devin has no flag that limits a step to named tools. The permission mode is the only limit, and a seat’s tools list is recorded, not enforced.
  • No step without a folder. workspaceMode: 'none' and tools: [] fail with invalid-config before Devin starts.
  • No system prompt. Devin has no flag for one, so a request’s system text goes at the top of the prompt.
  • No structured result. The final message is text. A request’s jsonSchema is not sent to Devin.
  • No live events. The plugin reads the conversation after Devin exits, so a run’s text and tool events arrive together when the run ends.
  • No folder trust check. The plugin skips it, for the reason in the table above.

Options

By default Devin runs with --config pointed at an empty config file for each attempt, or one that holds only the commands allow rules in a read step, so your own Devin settings file (~/.config/devin/config.json) stays out. The repository’s instruction files and rules still apply, and the run keeps your login. Its row in the engines table: runs on your setup, clean mode available, read-only held in both modes. Your own MCP servers and skills still load in clean mode, because Devin has no switch to leave them out.

Errors

  • EngineError of kind missing-cli when the executable can’t run.
  • EngineError of kind invalid-config for a step without a folder, a step with tools: [], a step that sets effort, a read step with a permissionMode other than auto, or a devin --version output the plugin cannot read. With clean: false and commands in a read step, also when your Devin config file is not a JSON object or its permissions.allow is not a list.
  • TypeError when refusalRetries is not a whole number of 0 or more.
  • EngineIncompleteResultError when Devin exits 0 and writes its conversation export, but has no final answer, for example when it refuses a tool in a read step and the plugin does not continue the run again.
  • EngineError when Devin times out, exits with another code, or writes no readable conversation export, and has no final answer.
  • Other EngineError kinds, such as auth or rate-limit, are read from Devin’s own error message.

API

  • devin(model?, options?): a TeamSeat for a workflow role. Quickstart.
  • DevinCliEngine: the engine class. DevinCliEngineOptions and DevinSeat: its types.
  • buildDevinArgs: the argument builder, exported for tests.

Next steps