How edhil works
How edhil works
The idea
edhil does the part of the work that is the same for every work item: hand the item to an agent, check what comes back, commit it, and write down what happened. The rules are simple and they do not change:
- The agent only edits files. It does not commit, switch branches or push.
- edhil runs the checks, builds the commit message, validates it and makes the commit.
- edhil never closes an issue and never pushes.
- Everything that happens is written to a journal you can read afterwards.
A run
edhil implement 123 starts a run. A run is a list of work items that are implemented one after the other, in ascending order of their issue numbers, each ending in one commit on the branch you started on.
Before anything starts, edhil checks that it can:
- you are inside a git repository, on a branch (not on a detached HEAD);
- the working tree is clean: no changed, staged or untracked files other than
.edhil/. The files that are in the way are listed; - no other
edhil implementoredhil commitis running in this repository; - every number you gave is an open epic or an open work item in the forge.
If any of these fails, nothing is started and the exit code is 1.
For each work item the run goes through these phases, and prints one line for each:
| Phase | What happens |
|---|---|
| implementing | The agent gets the title and the description of the work item and the rules, and edits the working tree. It ends its answer with a short summary of the change between two markers. |
| verifying | edhil runs the commands of the Verification steps of the work item in the repository, one after the other, each as a step of its own. The first command that fails stops the verification. |
| fixing | If the verification failed, the agent is shown the failure and tries again, up to integration.fix_attempts times. Then the verification runs again, always from the first command, so that a fix for one command cannot break an earlier one. |
| summarizing | The summary of the agent is checked. |
| committing | edhil checks that the files are still the ones that passed the verification, builds the commit message, validates it and commits all changes. The hooks of the repository run. |
| committed | The short hash of the commit. |
When a work item is committed the run goes on with the next one, starting from a clean tree.
Pauses
When something goes wrong that edhil cannot judge, the run pauses and asks you. The reasons are:
- the verification could not be started, or failed after the fix attempts;
- the agent failed, took too long, said it cannot do the work item, or changed nothing;
- the agent gave no usable summary;
- the branch is not the one the run started on;
- the files changed after the verification passed (the summary step edited them, say);
- the commit message is invalid, or git or a hook refused the commit;
- git failed in a way edhil cannot judge;
- the journal could not be written (the only answer is then abort).
The question is usually (r)etry, (i)gnore, (a)bort?. Retry runs the step again, ignore goes on with the failure (edhil asks once more, because it goes on with a failure), and abort ends the run and leaves the work in the working tree. When the commit failed or git failed in a way edhil cannot judge, the question is (r)etry, (d)iscard, (a)bort? instead: discard lists the files that go, asks once more, then restores the tracked files and removes the new files (the .edhil/ directory is kept) before going on with the next work item. A commit is marked as verified only if it contains exactly the files that passed all the commands in the same verification. If the files changed afterwards, retry verifies them again, and ignore commits them without the verified mark. When there is nobody to ask (the input is not a terminal, or --no-input is given) a pause aborts the run. The tree is then left as it is, so you can look at the change, fix it by hand and use edhil commit.
Stopping
The first Ctrl-C while a step is running stops the run: the step is cancelled, nothing is committed for it, the tree is left as it is, and the exit code is 130. A second Ctrl-C leaves the process at once. Ctrl-C at the question of a pause aborts the run.
What the agent can and cannot do
The agent is started with a thin program in front of git on its PATH. The program lets read-only git commands through and refuses the subcommands in integration.git_blocked_subcommands (commit, push, reset, rebase, checkout, branch and the like, and the low level commands that can make a commit or move HEAD), also when they are hidden behind an alias from the repository configuration. A refusal is explained to the agent in a message it can read. Commands that have a form that only looks stay allowed in that form: git reset -- file, git checkout -- file, git branch --list, git reflog, git config user.name. A form that names no file does not count: git reset HEAD~1 -- and git checkout other -- move or switch the branch, and are refused. Abbreviated options (--har for --hard) are recognized.
The program is a guardrail, not a sandbox. An agent that calls git by its full path (/usr/bin/git) or through a library does not pass through it. What really protects the repository is the check that edhil makes itself after every step: if the branch or HEAD moved, or something changed that should not have, the run pauses.
The prompt also tells the agent the rules: do exactly what the work item says, leave the changes uncommitted, do not touch .edhil, do not leave notes or scratch files, and do not ask questions.
When a step takes longer than integration.agent_timeout_minutes, or the run is stopped, edhil kills the agent and everything it started, including the commands that the agent put in process groups of their own, so no sleep or build is left running.
Which agent runs
The agent is a coding tool that you choose: Copilot, Claude Code, Codex or opencode. Which one runs is the setting integration.agent or the option --agent on implement and commit, see Choosing an agent. Every run records the name, the tool and the model of its agent in the journal, and edhil log shows them in the report of the run.
Four things are the same whichever tool it is:
- It never waits for an answer. Each tool is started so that nothing asks it a question, and for every tool that means it may do more than edit files. The permission settings of a tool are not a barrier; the program in front of git and the check after every step are.
- The answer is read from what the tool prints. A step without a usable answer pauses the run, whatever the exit code of the tool was.
- The transcript of a step in the journal comes from the tool: the file that Copilot shares, the session file that Claude or Codex keeps, or, for Opencode, what it printed on both streams without its colors. When no session file of Claude or Codex can be found, what Claude printed, or the log of Codex on standard error, is used instead.
- Your own configuration of the tool applies. Its plugins, instruction files and settings are read as when you use the tool yourself.
The commit message
Every commit made by edhil has the same shape:
Title in one line, ending with a full stop.
A description of 1 to 10 lines, up to 800 characters.
Issues: #123
The title comes from the title of the work item, the description from the summary of the agent, and the last line is the issue number. A commit that belongs to no work item (made with edhil commit without a number) ends with Issues: None. A message that does not have exactly this shape is refused before git is asked to commit.
Numbers
Two kinds of numbers appear in the commands:
edhil implementandedhil import --epictake issue numbers: the number of an epic or of a work item, such as123.edhil logtakes a run number, such as12, the one it shows at the start of every line.
Both accept a leading #. In a shell a word that starts with # is a comment, so write '#123' with quotes or leave the # out.
The journal
Every run is written to .edhil/journal.db, a SQLite file at the top of the repository. It holds, for every run, the work items with their phases, every step with its prompt, the transcript of the agent and the full output with the time and stream of each line, the events (pauses, answers, stops), the commit message and the patch of each commit. edhil log reads it. The commands that only read can run while a run is writing.
edhil work-items also reads it, to mark the work items that an earlier run committed. edhil implement leaves those out of an epic the next time (use --include-committed to run them again).
A run that was never ended, because the process was killed, is closed as aborted the next time implement or commit takes the lock.
The lock
implement and commit hold a lock on the repository for as long as they run (the file .edhil/run.lock). A second one in the same repository fails at once and says so. The operating system releases the lock when the process dies, so there is never a stale lock to clean up. log, work-items and import do not take it.
Exit codes
| Code | Meaning |
|---|---|
| 0 | The command did what was asked; a run is done (every work item committed). |
| 1 | An error or a failed precondition. The message is on stderr. |
| 2 | Wrong command line. |
| 3 | A run was aborted, by you or because it paused with nobody to ask. |
| 130 | A run was stopped with Ctrl-C. |
Output
Results go to stdout and warnings, questions and logging to stderr, so edhil log 12 > report.md and edhil work-items | grep work. Long output of log goes through a pager when stdout is a terminal. Colors are used only on a terminal. No command moves the cursor, so redirected output stays readable.