devin-cli

Files (3)

• SKILL.md
• protocol.md · references/
• devin_acp.py · scripts/

SKILL.md (first lines)

# Devin CLI

Devin CLI is a separate coding agent on the same machine. `devin acp` speaks
the Agent Client Protocol over stdio; the bundled helper
[scripts/devin_acp.py](scripts/devin_acp.py) drives one turn, answers
permission requests from a local policy, and records everything in a run
directory. It uses only the Python standard library (3.10+). Resolve the
script relative to this installed skill, not the project being worked on.

Devin must already be installed and signed in. Signing in opens a browser,
so the user does it with `devin auth login`; the helper never authenticates
and never changes Devin's configuration. If `devin` is missing, signed out,
or out of quota, report that and the work that remains instead of quietly
doing the task yourself.

## Run a task

```sh
python <script> run --cwd <absolute-workspace> --prompt-file <brief.md> [--run-dir <dir>]
python <script> progress --run-dir <dir>
python <script> run --cwd <absolute-workspace> --resume <session_id> --prompt-file <follow-up.md>
```

`run` blocks until Devin ends its turn, so start it with your own background
facility (a background shell command, `nohup ... &`, `Start-Process`) when
you have other work. It prints JSON lines: `started` with the run directory,
`session` with Devin's session ID, and `finished` with the summary. It exits
0 only when the turn ended normally. Each run gets its own owner-only run
directory holding `final.md` (Devin's final message), `summary.json`,
`events.jsonl`, and `devin.stderr.log`; `run` refuses a directory that
already holds a run. The files contain the brief and Devin's output, so keep
them out of shared or tracked locations. `--help` lists every flag;
[references/protocol.md](references/protocol.md) covers the ACP details.

## Write the brief

Devin sees none of your conversation. A brief that works on the first try
states, in this order:

1. The goal and why it matters, in a paragraph.
2. The current state: what already exists, what is committed, where.
3. Files to read first, including the project's conventions.
4. The environment: absolute paths to interpreters and tools, environment
   variables, and the exact commands that build, test, and validate.
5. Scope: the files or modules this task owns, and what other workers own.
6. Rules: leave changes uncommitted; no branch, stash, reset, or push; the
   directories it must not touch.
7. Done means: commands that must pass and numbers that must hold (for
   example, the test count must not drop).
8. What the final message must contain: files changed, counts, every
   intentional deviation, and anything left unfinished.

Use a UTF-8 prompt file rather than shell-quoted text. Size each task so its
"done" can be checked in one pass; split a large port into steps whose
acceptance does not depend on work still in flight.

## Isolate and integrate

- Give every writing task its own git worktree, created from a commit that
  contains what Devin needs. If the base has uncommitted work, copy it in
  (`git ls-files -m -o --exclude-standard` lists it; in Git Bash on Windows
  pass `--force-local` to `tar` so `C:` paths are not read as remote hosts).
- Never let two writers edit the same files. Parallel tasks get explicit
  ownership lists in their briefs, and a module both need is ported first,
  on its own.
- Devin leaves its changes uncommitted. Review them, copy them into the
  integration tree, and commit there. Files changed on both sides need a
  manual merge.
- Restore or discard only named paths. `git checkout -- .` or
  `git reset --hard` in a tree with other uncommitted work destroys it.
- Remove the worktree and its branch after integrating.

## Permissions

The helper answers each request with a single-use option: `allow_once` or
`reject_once`. It never selects `allow_session`, `allow_always`,
`allow_always_global`, or `switch_bypass`, because those persist in Devin's
configuration or change the session's mode. By default it rejects git
operations that rewrite history or switch branches and worktrees, publishing
through `gh`, and edit, delete, or move requests whose target is outside
`--cwd` or missing. Adjust with `--deny <regex>`, `--no-default-deny`, and
`--allow-write-root <dir>`.

Shell commands are matched only against the deny patterns; a command can
write anywhere, so no path check applies to it. For a task that must not
change anything, pass `--read-only`: it rejects every edit, delete, move, and
shell-command request and starts the session in `ask` mode (`plan` is also
accepted).

The policy only sees what Devin asks about. In `accept-edits`, Devin's usual
default, it applies workspace edits and runs read-only tools without asking. Pick
the mode for the job with `--mode`: `ask` answers without editing, `plan`
plans first, `smart` auto-approves more, and `bypass` approves everything.
Use `bypass` only when the user explicitly authorizes it. None of this is an
OS sandbox; isolation comes from the worktree.

`permissions_denied` in the summary lists what Devin tried outside the
policy. Read it: a denial usually means the brief left a gap.

## Model and effort

`--model` takes the names `devin models list` shows; many include the effort
as a suffix (for example `-high`). Without it, Devin's configured default
applies. The summary's `config` reports the effective `model`,
`thought_level`, and `speed`; confirm them after the run. Use
`--agent-type review` for Devin's code-review agent, which reads and runs
shell commands but does not edit.

## Monitor

`progress` reports the tool-call count, recent tool titles, the latest plan,
denials, failed tools, the length of the answer streamed so far,
`seconds_since_last_event`, and the summary once finished. Large tasks routinely run for an hour or more; judge a stall by
`seconds_since_last_event`, not by elapsed time. `--timeout` (default 3600
seconds) cancels the turn; if Devin does not acknowledge, the helper stops
its process tree. Cancelling does not undo edits already made.

## Follow-ups

From scarletkc/agents, Apache-2.0.

More from scarletkc/agents