@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
@obversa/obversa; install it on its own.
Requirements
- The Devin CLI installed and signed in with your own account. The
devincommand must be on yourPATH, or you pass its path ascliBinary.
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
npx tsx engine-devin-cli-seat.ts in a git repository that holds
an a.js with two exports. One run printed:
Output
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. Withclean: 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 reportsprovider: '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 underaccept-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 withauto. 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 topermissions.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()andnew DevinCliEngine()throw aTypeErrorthat names the entry. - The record. An attempt records the step’s tools.
devin()adds each command asExec(<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. Withnew 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.
A refused tool in a read step
When Devin refuses a tool in a read step, the plugin continues the same Devin session withdevin -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:
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.
refusalRetriessets how many times the plugin continues the session in one attempt. It is 2 by default. - Turning it off.
devin(model, { refusalRetries: 0 })ornew 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 TODOfor the commandrg 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 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
toolslist is recorded, not enforced. - No step without a folder.
workspaceMode: 'none'andtools: []fail withinvalid-configbefore Devin starts. - No system prompt. Devin has no flag for one, so a request’s
systemtext goes at the top of the prompt. - No structured result. The final message is text. A request’s
jsonSchemais 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
EngineErrorof kindmissing-cliwhen the executable can’t run.EngineErrorof kindinvalid-configfor a step without a folder, a step withtools: [], a step that setseffort, a read step with apermissionModeother thanauto, or adevin --versionoutput the plugin cannot read. Withclean: falseand commands in a read step, also when your Devin config file is not a JSON object or itspermissions.allowis not a list.TypeErrorwhenrefusalRetriesis not a whole number of 0 or more.EngineIncompleteResultErrorwhen 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.EngineErrorwhen Devin times out, exits with another code, or writes no readable conversation export, and has no final answer.- Other
EngineErrorkinds, such asauthorrate-limit, are read from Devin’s own error message.
API
devin(model?, options?): aTeamSeatfor a workflow role. Quickstart.DevinCliEngine: the engine class.DevinCliEngineOptionsandDevinSeat: its types.buildDevinArgs: the argument builder, exported for tests.
Next steps
- Runtime: the roles a seat fills.
- Codex CLI Engine: another CLI seat.