Deffier Autopilot
Autopilot runs agent jobs without you watching. You write a job file once and it runs on a schedule, on new commits, or when you click Run. Deffier checks every result before accepting it, and a run that needs a permission it doesn't have waits for your answer.
What a run cannot do:
- Change your checkout. Every run works in its own git worktree at a pinned commit. The result is a commit
on a branch named
autopilot/<run id>. You merge it, or you don't. - Grade its own work. The checks in the job file run after the agent stops. A run is accepted only if every check passes.
- Quietly gain permissions. A Claude Code agent can only use the tools the job lists. Anything else is refused and recorded. The run then pauses as Parked until you choose Allow or Deny.
Quick start
- Open the panel: the robot button in the header, Ctrl+P →
:autopilot, or Ctrl+5 when focus is not in a terminal. - This repo ships
.dewwie/autopilot/example-demo.json. It runs a tiny Node script instead of an AI agent, so it costs nothing. Click Run on it. You'll see the run go through Preparing › Running › Verifying › Accepted › Delivered, and the result lands onautopilot/example-demo-…. - Inspect the result with
git log autopilot/<run id>. Delete the branch if you don't want it.
From a terminal:
deffier autopilot list # jobs in your registered projects, and their last run
deffier autopilot run example-demo --wait
deffier autopilot runs # newest first
deffier autopilot show <run id> # lifecycle, checks, summary, result branch
deffier autopilot diff <run id> # what a delivered run changed (files + diff, read-only)
deffier autopilot approve <run id> [--deny]
deffier autopilot cancel <run id>
run, approve and cancel are carried out by the Deffier app, which must be running. If it isn't, the
request waits and runs when the app starts. list, runs and show read the run logs directly.
Job files
A job is <project>/.dewwie/autopilot/<id>.json. The id is the file name: lowercase letters, digits and -.
Job files are meant to be committed and reviewed like code. A broken file shows up in the panel as
invalid, with each error and where it is in the file. It never stops other jobs from running.
{
"name": "Nightly dependency check", // optional, shown in the panel
"enabled": true, // false: never triggers, Run disabled
"trigger": [ // optional; Run is always available
{ "cron": "CRON_TZ=Asia/Bangkok 0 3 * * *" }, // 5-field cron, optional CRON_TZ (any IANA zone)
{ "git": { "branch": "main", "debounceSec": 600 } } // new commits, after 10 min with no new push
],
"task": {
"goal": "What the agent must achieve, in plain words.", // required
"allowed_paths": ["src/**", "package.json"], // files the run may change (default: everything)
"acceptance": [ // all must pass for the run to be accepted
{ "run": "npm test", "timeoutSec": 600 }, // a command, run in the run's worktree
{ "diff_max_files": 5 }, // at most N changed files
{ "diff_not_empty": true }, // "nothing changed" is a failure
{ "no_secrets": true } // no API keys / tokens / private keys added
]
},
"agent": {
"adapter": "claude", // or "command"
"model": "sonnet", // claude only, optional
"allowed_tools": ["Bash(npm test:*)"], // claude only, added to Read/Edit/Write/Glob/Grep
"command": ["python", "agent.py", "{prompt}"] // command only: argv, no shell; {prompt} {cwd} {runId} {attempt}
},
"isolation": { "base": "main", "ports": true }, // commit/branch to start from; give each run its own PORT
"policy": { "on_permission_request": "park" }, // "park" (ask you) or "deny" (continue without it)
"budget": { "wall_minutes": 30, "attempts": 2, "max_cost_usd": 2 },
"concurrency": "skip", // "skip" | "queue" | "cancel-previous" while a run is active
"deliver": { "keep_branch": true, "notify": ["room"] } // "room": post finish/park to the room; "toast" is accepted, not shown yet
}
Defaults: no triggers, allowed_paths: ["**"], no acceptance checks, adapter: "claude", base: "main",
on_permission_request: "park", wall_minutes: 30, attempts: 2, no cost cap, concurrency: "skip".
Agents
clauderuns Claude Code headless:- flags:
claude -p --output-format json --permission-mode dontAsk --allowedTools …. Tools outside the list are denied without asking, never granted. max_cost_usdbecomes--max-budget-usd.- It never uses
--dangerously-skip-permissions. - If you allow a parked request, the run resumes the same Claude session with that tool added.
- It uses your normal Claude Code login, so real runs cost real money. Set
max_cost_usd.
- flags:
commandruns any program:- The argv list is run directly, with no shell.
- To ask for a permission, print a line
DEWWIE_PERMISSION_REQUEST <what>. Granted items arrive on the next attempt in theDEWWIE_AUTOPILOT_GRANTEDenvironment variable, one per line. - The summary is the last stdout line that is JSON with a
"summary"field, or else the last line.
The agent's environment drops variables whose names look like secrets (*_TOKEN, *_KEY, *SECRET*, …),
except the ones Claude Code needs to log in. It also gets DEWWIE_AUTOPILOT=1, DEWWIE_AUTOPILOT_RUN, and its
own PORT / API_PORT.
The run lifecycle
Queued → Preparing → Running → Verifying → Accepted → Delivered
│ ↑ │
↓ │ └─ checks failed → Queued (next attempt, with the failures as feedback)
Parked … or Failed when attempts run out
(Allow → Running, Deny → Failed)
Any active state → Cancelled · Running → TimedOut · app closed mid-run → Interrupted → Failed
- Retries: on a retry, the agent receives the checks that failed and the tail of their output. Each run also receives the previous delivered run's summary.
- Delivered: the result is committed on
autopilot/<run id>. The worktree is removed and the branch is kept. In the Runs panel you can View changes, Merge into your branch or Discard it; see Review and merge. - Failed or timed-out: these runs keep their branch too, as evidence.
- Old worktrees: gc removes worktrees older than 7 days.
- Notifications: finished and parked runs post to the room as Autopilot.
Triggers
- cron:
- Checked every 15 s while Deffier is running.
- Fires once per matching minute.
- If the app was busy, it catches up on at most the last 5 minutes. A laptop that slept all night does not replay the night.
- Times that pass while Deffier is closed are skipped.
- git:
- The branch head is polled. The first value seen is only a baseline.
- After a new head, the run fires once the branch has been quiet for
debounceSec. A new push restarts the wait.
- Duplicates: every trigger has an event key, so the same minute or the same commit never starts two
runs. While a run is active,
concurrencydecides what happens to a new trigger.
Where things live
| What | Where |
|---|---|
| Job files | <project>/.dewwie/autopilot/*.json (committed) |
| Run event logs (source of truth) | ~/.swarmherd/autopilot/runs/<run id>/events.jsonl |
| CLI requests / answers | ~/.swarmherd/autopilot/requests/, responses/ |
| Run worktrees | <project>/.worktrees/autopilot-<run id> (git-excluded locally) |
| Result branches | autopilot/<run id> |
| Code | desktop-ui/electron/autopilot/: spec, runlog, machine, workspace, adapters, verify, cron, engine, triggers, supervisor |
Only the Deffier app writes run state, so there is a single writer. The CLI only reads logs and drops requests.