Configuration

Where the file is

The configuration is a YAML file called edhil.yaml. edhil looks for it in the top directory of the git repository that contains the current directory, and then in the current directory itself, so every command works from any directory of the repository. --config FILE names the file explicitly and skips the search.

The file is read by every command that talks to the forge or runs the agent. edhil log reads only the journal, and edhil commit --no-agent needs no file at all.

A file that cannot be read, that is not valid YAML, that has a key edhil does not know, or that has a value that would make a run fail in a confusing way (see the limits below) stops the command with a message that names the file and the key.

The personal file

edhil.yaml is for what the team agrees on, and it is committed. What only you need, such as a model or a longer timeout, goes in a second file: edhil.user.yaml, in the same directory. edhil reads it when it is there, and its settings win over the ones of edhil.yaml. With --config ci.yaml the personal file is ci.user.yaml, next to ci.yaml. It is not searched for anywhere else.

# edhil.user.yaml
integration:
  agent: mine
  agents:
    mine:
      tool: copilot
      model: gpt-5
  agent_timeout_minutes: 90

The rules are short:

  • The file has the same keys as edhil.yaml, and any of them can be set in either file.
  • Sections are merged key by key. In the example, everything else in integration still comes from edhil.yaml.
  • A value you give replaces the value of edhil.yaml, and so does a list: git_blocked_subcommands: [push] replaces the whole git_blocked_subcommands of edhil.yaml, it is not added to it.
  • A key with nothing after it changes nothing. A section whose lines are all commented out is harmless.
  • Every value is read as you wrote it, exactly as in edhil.yaml: no or 4.10 are not turned into a boolean or a number.
  • The file may be missing, and then only edhil.yaml counts.

Git must not commit this file. The .gitignore of this repository lists it, and edhil.user.yaml.example shows what to put in it. When the file is there and git does not ignore it, edhil prints a warning on stderr; add the name to the .gitignore of your repository, or to .git/info/exclude if you do not want to touch the shared one.

When a setting is wrong, the message tells where to look. A syntax error names the file it is in. A wrong value or an unknown key in the combined settings names both files and the setting:

Invalid settings in 'edhil.yaml' combined with 'edhil.user.yaml': integration.fix_attempts: invalid u32

Unknown keys are errors

A key that edhil does not know stops the command, so that a misspelled setting does not go unnoticed. The message names the key and lists the keys that are allowed there:

error: line 7 column 3: unknown field `fix_atempts`, expected one of agent, backend, agents, copilot, verify, verify_strict, fix_attempts, ...

This applies to both files. If a file that used to load now stops with this message, it had a setting that was never read; correct the name or remove the line. The only names that are accepted without being used are the ones of older versions, see the end of this page.

The forge

The epics and the work items live in the issues of a forge: GitLab or Forgejo. edhil.yaml has exactly one section for it, gitlab or forgejo, and the section that is there decides which forge every command talks to. The sections are described below and after it. A file with both, or with neither, stops the command:

The settings must have exactly one of the sections 'gitlab' and 'forgejo', and they have both
The settings must have exactly one of the sections 'gitlab' and 'forgejo', and they have neither

The rest of the book says “the forge” and names GitLab or Forgejo only where they differ; What differs between the forges lists those places.

The token

The token is never written in the file. The setting gitlab.token_env or forgejo.token_env is the name of an environment variable, and edhil reads the token from it when a command needs the forge. If the variable is not set the command fails and names the variable and the setting:

Environment variable 'FORGEJO_TOKEN' is not set (configured as forgejo.token_env)

On GitLab the token is a personal access token with the api scope. On Forgejo it is an access token that can read and write the issues of the repository. The check by hand against a Forgejo server was made with a token that had the scopes read:organization, write:issue and write:repository; creating an organization label needs write:organization as well.

A complete example

Every value in the integration section is the default, so the whole section can be left out. With Forgejo the first section is the forgejo section, shown in its own example.

gitlab:
  url: "https://gitlab.com"
  token_env: "GITLAB_TOKEN"
  default_group: "mygroup"
  default_project: "mygroup/myproject"
  connect_timeout_seconds: 10
  request_timeout_seconds: 30
  read_retries: 2

integration:
  agent: copilot
  agents: {}
  copilot:
    command: "copilot"
    extra_args: []
  fix_attempts: 1
  agent_timeout_minutes: 60
  max_output_mb: 10
  git_blocked_subcommands:
    - commit
    - commit-tree
    - push
    - pull
    - reset
    - rebase
    - merge
    - cherry-pick
    - revert
    - am
    - stash
    - switch
    - checkout
    - branch
    - tag
    - update-ref
    - symbolic-ref
    - fast-import
    - worktree
    - filter-branch
    - filter-repo
    - reflog
    - config
    - update-index
    - read-tree
    - replace
    - gc
    - prune
    - maintenance

The gitlab section

Key Meaning
url The address of the GitLab server, such as https://gitlab.com.
token_env The name of the environment variable that holds the access token.
default_group The group of the project.
default_project The project, with its group: mygroup/myproject. Issue links printed by import are built from the URL and this value.
connect_timeout_seconds Optional, 10. How long connecting to GitLab may take. From 1 to 600.
request_timeout_seconds Optional, 30. How long one request may take in all, from the start to the last byte of the answer. From 1 to 600. A request that takes longer fails with a network error.
read_retries Optional, 2. How many times a read is tried again when it fails with a network error, a server error (HTTP 5xx) or too many requests (HTTP 429), with a wait of 0.5 s, then 1 s, and so on up to 4 s. From 0 to 5. Requests that create or change something (import, closing an issue) are never repeated, because a repeat could do the change twice.

The first four are required.

The forgejo section

Key Meaning
url The address of the Forgejo server, such as https://forgejo.example.com, without /api/v1.
token_env The name of the environment variable that holds the access token.
repository The repository whose issues hold the epics and the work items, written owner/repo. Each part has letters, digits, -, _ or .. Issue links printed by import are built from the URL and this value.
connect_timeout_seconds Optional, 10. How long connecting to Forgejo may take. From 1 to 600.
request_timeout_seconds Optional, 30. How long one request may take in all, from the start to the last byte of the answer. From 1 to 600.
read_retries Optional, 2. How many times a read is tried again when it fails with a network error, a server error (HTTP 5xx) or too many requests (HTTP 429). From 0 to 5. Requests that create or change something are never repeated.

The first three are required.

forgejo:
  url: "https://forgejo.example.com"
  token_env: "FORGEJO_TOKEN"
  repository: "myowner/myrepo"
  connect_timeout_seconds: 10
  request_timeout_seconds: 30
  read_retries: 2

The integration section

Key Default Meaning
agent copilot The agent used when --agent is not given: the name of an agent in agents, or the name of a tool. The older name backend is still read. See Agents.
agents none Named setups of the tools, each with a tool, and optionally a command, a model and extra_args. See Agents.
copilot.command copilot The program of the built-in agent copilot. It is looked up on the PATH. It must not be empty. Older than agents, and still read.
copilot.extra_args [] Arguments added after the ones edhil always passes to the built-in agent copilot. Older than agents, and still read.
fix_attempts 1 How many times the agent may try to repair a change that failed the verification, from 0 to 3. With 0 a failed verification pauses the run at once.
agent_timeout_minutes 60 How long one agent step may take. At least 1.
max_output_mb 10 How much output one agent step or verification keeps, in megabytes, from 1 to 1024. Over the limit the beginning and the end are kept and [output truncated: N bytes left out] marks the gap, in the journal and in the output on the screen. A single line longer than 64 KiB is cut into pieces.
verification none Which commands the Verification steps of a work item may run, and how long each may take. See Verification. Only read from edhil.yaml.
git_blocked_subcommands the list above The git subcommands the agent is not allowed to run. Remove a name to allow it. Some of them keep their read-only forms (git config user.name, git reflog, git branch --list).

Verification

A work item says in its own Verification steps section how it is verified: the commands to run. The verification section of edhil.yaml is where the project says which of those commands may run, and how long each may take. It is optional. Without it every command is allowed and none has a time limit.

gitlab:
  url: "https://gitlab.com"
  token_env: "GITLAB_TOKEN"
  default_group: "mygroup"
  default_project: "mygroup/myproject"

integration:
  verification:
    restrict: true
    commands:
      - command: ["yet", "prepush"]
        timeout_minutes: 30
      - command: ["yet", "cleanify"]
        timeout_minutes: 10
      - command: ["cargo", "test"]
Key Default Meaning
restrict false With true, a work item may only run commands that an entry matches. A work item with any other command is refused when the plan is built, before the run starts.
commands none The entries. Each has a command, a list of words, and optionally a timeout_minutes.

The rules are these:

  • An entry matches a command when its words are the first words of the command. ["cargo", "test"] matches cargo test -p edhil and does not match cargo build. ["yet"] matches every command of yet.
  • The time limit of a command is the timeout_minutes of the longest matching entry that has one. In the example yet prepush has 30 minutes, and cargo test has none: a command that no entry with a timeout_minutes matches runs without a limit, and there is no limit for the verification as a whole. A command that goes over its limit is stopped, and the run pauses at the work item.
  • The words of an entry are compared with the words of the command as the importer splits them, so quotes and spaces do not matter: cargo test -p 'my crate' is the words cargo, test, -p and my crate.
  • An entry needs at least a program name, and timeout_minutes is at least 1. A section with an unknown key, or with a value that does not fit, stops the command with a message that names the entry, for example integration.verification.commands[1].timeout_minutes must be at least 1.
  • The section is only read from edhil.yaml. A personal file edhil.user.yaml that sets integration.verification stops the command: the setting decides what runs on every machine of the team, so a personal file cannot widen it or turn restrict off. A verification: with nothing after it is harmless.

The commands of a work item are read from its description in the forge when edhil implement builds the plan, not from the document that was imported, so a work item can be corrected in the forge before it is implemented. See edhil implement for the plan, and edhil import for the format of the section in a document.

Agents

edhil drives a coding agent in two words. A tool is a program edhil knows how to run: claude, codex, copilot or opencode. An agent is a named setup of one tool: which tool, which program, which model, which extra arguments. edhil implement 12 --agent strong runs the agent called strong; without --agent the agent is the one named by integration.agent, which is copilot unless you change it. Choosing an agent compares the tools and explains how to set them up and switch between them; this page has the keys and the details of each tool.

The agents are written under integration.agents:

gitlab:
  url: "https://gitlab.com"
  token_env: "GITLAB_TOKEN"
  default_group: "mygroup"
  default_project: "mygroup/myproject"

integration:
  agent: fast
  agents:
    fast:
      tool: copilot
      model: gpt-5
    careful:
      tool: copilot
      command: /opt/bin/copilot
      extra_args: ["--some-flag"]

Each agent has these keys, and no others:

Key Required Meaning
tool yes claude, codex, copilot or opencode.
command no The program to start. Without it, the name of the tool. It is looked up on the PATH, or used as a path if it has a directory part. It must not be empty.
model no The model. edhil gives it to the tool in the way that tool takes it. Without it the tool uses its own default. It must not be empty.
extra_args no Arguments added after the ones edhil always passes.

The name of an agent has 1 to 64 letters, digits, - or _.

The four tool names are agents too, without being written anywhere: --agent copilot is the tool with its own defaults. For copilot those defaults are the settings copilot.command and copilot.extra_args of the section above, which are the older spelling: new setups are better written as agents. An agent in agents with the name of a tool takes the place of the built-in one. A name that is neither gives an error that lists the names that exist.

Which agent runs, in this order: the one given with --agent, the one named by integration.agent, and copilot.

If both edhil.yaml and edhil.user.yaml have an agent with the same name, the one in edhil.user.yaml replaces the other as a whole, so a personal definition has to be complete. The agents that only one of the files has are all available. Everything else is merged as described above.

# edhil.user.yaml
integration:
  agent: careful
  agents:
    careful:
      tool: copilot
      model: gpt-5

Here careful is now the personal definition and has no extra_args, and fast from edhil.yaml is still there.

All four tools can be run. Each is described below. Choosing an agent compares them.

Before implement asks anything, and before commit stages anything or asks the agent for a draft, edhil checks the agent: that it exists, and that its program can be found. The message names the agent, the program and the setting to change. The model is not checked; a wrong model is reported by the tool when it runs.

Claude

edhil runs claude -p, with the instruction to read the prompt file, --permission-mode acceptEdits, --permission-prompts none, --allowedTools Bash and --session-id with a new UUID for every step, then --model MODEL if the agent has a model, then the extra arguments of the agent. Nobody is asked anything. The model is an alias such as sonnet or a full name.

# edhil.user.yaml
integration:
  agent: strong
  agents:
    strong:
      tool: claude
      model: sonnet

The facts below that come from trying claude are observations of Claude Code 2.1.316 on Linux, made with its default model and each case run once; they can differ with another version, another model or another login. What to know when you use it:

  • The permission settings are not a sandbox. acceptEdits lets claude edit files in the repository, and its own write tool was refused outside it. --permission-prompts none denies whatever would ask, so nothing waits, and --allowedTools Bash lets the shell run. But the shell could still write anywhere and reach the network in the study. Claude’s own rules against git commit refused one form of it, and are not used. The git shim and the check of HEAD after every step are what protect the repository.
  • A refusal is only in the answer. When claude denies something, it says so in its text and still ends with exit code 0. A step whose output has no answer is not a success: edhil does not commit, shows what claude printed, and the run pauses.
  • extra_args can break the run. --output-format json and --output-format stream-json (also written with =) put the answer inside a JSON string, where edhil does not find it, and --session-id and --no-session-persistence are set by edhil to find the session file, so an agent that passes any of them is refused with a message. Other options are passed as they are, also those that loosen the permissions, such as --permission-mode bypassPermissions.
  • The answer is what claude prints on standard output in its text format.
  • The transcript in the journal is the session file that claude keeps for the run, projects/<folder>/<UUID>.jsonl in CLAUDE_CONFIG_DIR, or in .claude in your home directory. edhil looks for the UUID of the step in every folder under projects. CLAUDE_CONFIG_DIR was not tried in the study. If the file cannot be found, what claude printed is used. A very long transcript is cut like the output of a step, see max_output_mb.
  • A wrong model and no login. In the study a wrong model made claude end with exit code 1 after about two seconds, with the message on standard output, and a run without a login ended at once with exit code 1 and Not logged in - Please run /login on standard output. In both cases the output of the step shows the message, and the run pauses.
  • Your own configuration of claude applies to the runs, as it does when you use claude yourself: the init event of the study listed the plugins, skills and agents of the person who ran it. Whether --bare, --setting-sources or --settings switch this off was not tried, and neither were the project instruction files such as CLAUDE.md.
  • What it leaves on your computer. Session files, backups and caches in ~/.claude, and logs under ~/.cache.
  • Stopping. When a step times out or you stop the run, edhil kills claude and the commands it started; in the study a sleep started by its shell tool outlived the group of claude.

Codex

edhil runs codex exec, with the instruction to read the prompt file, --sandbox workspace-write, and -o to a file in the step folder, then -m MODEL if the agent has a model, then the extra arguments of the agent. Nobody is asked anything: codex exec never asks for approval, and what the sandbox does not allow simply fails.

# edhil.user.yaml
integration:
  agent: deep
  agents:
    deep:
      tool: codex
      model: gpt-6-luna

The names of the models are the ones your account of codex offers. The facts below that come from trying codex are observations of codex 0.166.0 on Linux; they can differ with another version, another login or another network. What to know when you use it:

  • Use the Linux install of codex. The Windows build (codex.exe, reached from WSL) is not supported, and edhil refuses it: before anything starts, an agent whose codex program is a file ending in .exe, or a link to one, stops the command with a message that says why. The study found that this build starts its commands with a PATH of its own, so the git shim is not in front and the agent can commit. edhil would undo such a commit afterwards, but that is the only protection left, and it is not enough.
  • extra_args can break or loosen the run. --json and --output-schema change what codex prints on standard output, where edhil reads the answer, so an agent that passes either is refused with a message. Other options are passed as they are, also those that change the sandbox or where commands run: --sandbox workspace-write is how edhil starts codex, not a restriction that cannot be changed. The git shim does not depend on the sandbox.
  • The sandbox is partial. In the study, workspace-write kept the writes of the agent in the working tree and also allowed /tmp, and a network request failed because names could not be resolved, so a work item that needs the network failed inside the work of the agent, not with a refusal. edhil does not rely on either; the git shim and the check of HEAD after every step are what protect the repository.
  • The answer is what codex prints on standard output. If that has no answer but the final message that codex wrote to its file has one, the message is used.
  • The transcript in the journal is the session file that codex keeps (sessions/YYYY/MM/DD/rollout-<time>-<session id>.jsonl in CODEX_HOME, or in .codex in your home directory), found with the session id from the header on standard error. If it cannot be found, the log that codex printed on standard error is used. A very long transcript is cut like the output of a step, see max_output_mb.
  • Your own configuration of codex (config.toml, plugins) applies to the runs, as it does when you use codex yourself.
  • A wrong model and no login. In the study a wrong model made codex end with exit code 1 after a couple of seconds, with the message on standard error, and a run without a login tried to reconnect five times, about 15 seconds, and ended with a 401. In both cases the output of the step shows the message, and the run pauses.

Copilot

edhil runs copilot -p, with the instruction to read the prompt file, then -s, --no-ask-user and --allow-all-tools, four --deny-tool flags, --share to a file in the step folder, then --model MODEL if the agent has a model, then the extra arguments of the agent. Nobody is asked anything.

# edhil.user.yaml
integration:
  agent: quick
  agents:
    quick:
      tool: copilot
      model: gpt-5

This is the tool edhil was first written for, and the one it uses when nothing else is chosen. What to know when you use it:

  • The deny flags are a weak extra line. The four --deny-tool flags refuse git commit, git push, git reset and writes to .edhil, but an agent gets around them (git -C . commit, git commit-tree). The git shim and the check of HEAD after every step are what protect the repository, as for every tool. --allow-all-tools means the permissions of Copilot are not a sandbox either.
  • The answer is what Copilot prints on standard output.
  • The transcript in the journal is the file that Copilot writes with --share. If it writes none the step has no transcript, and what the step printed is still in the journal.
  • The older settings copilot.command and copilot.extra_args are the program and the extra arguments of the built-in agent copilot, and still work. An agent called copilot in agents takes their place.
  • A wrong model is not checked by edhil. Copilot reports it when it runs, and the output of the step shows the message. This tool was not part of the study that the other sections come from.
  • Your own configuration of Copilot applies to the runs, as it does when you use Copilot yourself.

Opencode

edhil runs opencode run, with the instruction to read the prompt file and --auto, then -m PROVIDER/MODEL if the agent has a model, then the extra arguments of the agent. Nobody is asked anything. The model is written the way opencode models lists it, with the provider in front.

# edhil.user.yaml
integration:
  agent: local
  agents:
    local:
      tool: opencode
      model: opencode/beam-free

The facts below that come from trying opencode are observations of opencode 1.19.5 on Linux, made with free models and with each case run once; they can differ with another version, another model or another login. What to know when you use it:

  • --auto is always passed, and it opens everything. Without it, a permission that opencode would ask for is rejected, and the run ends with exit code 0 and no answer. With it, opencode allows what is not denied, also writes outside the repository and network access. The git shim and the check of HEAD after every step are what protect the repository; the permissions of opencode are not a sandbox, and the study did not show its own deny rules working.
  • extra_args can break the run. --format json (also written --format=json) puts the answer inside a JSON string, where edhil does not find it, so an agent that passes it is refused with a message. Other options are passed as they are.
  • A run can end well and say nothing. In the study a rejected permission made opencode stop after its first sentence, with exit code 0. A step whose output has no answer is not a success: edhil does not commit, shows what opencode printed, and the run pauses.
  • The answer is what opencode prints on standard output. The trace of the run, with each tool call, is printed on standard error with colors.
  • The transcript in the journal is the trace on standard error followed by the output on standard output, without the colors, cut like the output of a step when it is long, see max_output_mb. opencode can export a session with more detail, but the id of the session is only known after the run, so edhil does not use it.
  • A wrong model made opencode end with exit code 1 after about a second, with an error on standard error that does not name the model. A wrong name with a correct provider, and a missing login with a paid model, were not tried.
  • What it leaves on your computer. opencode keeps a database (~/.local/share/opencode/opencode.db, shared by all its sessions, 440 MB at the end of the study), a snapshot of each repository and a cache of models in your home directory.
  • Your own configuration of opencode (instructions, plugins, servers) applies to the runs, as it does when you use opencode yourself. Whether --pure switches it off was not tried.
  • Stopping. When a step times out or you stop the run, edhil kills opencode and the commands it started.

Settings from older versions

Earlier versions of edhil were a web server. A file that still has the server or agent sections keeps loading; the sections are ignored and every command prints one warning for each file that says so. backend is read as agent. The settings integration.verify (and its older name verify_strict) and integration.verify_timeout_minutes no longer have any effect: the commands that verify a work item are the ones in its Verification steps. They are accepted, ignored, and every command prints one warning for each file that sets them. verify_relaxed is ignored without a warning. Their warning reads PATH sets integration.verify, which is not used any more, and says that integration.verification is where commands are restricted and given time limits. To keep the old limit, give the commands of your project a timeout_minutes there. The names server, agent (as a section of the file, not as the setting integration.agent), verify, verify_strict, verify_timeout_minutes and verify_relaxed are the only ones that edhil accepts without using them.

Other settings

These are not in the file:

Setting Meaning
-v, -vv, --verbose Log more to stderr: information, and with two the most detail.
EDHIL_LOG A log filter, such as debug. It wins over -v.
NO_COLOR Any non empty value turns colors off, like --no-color.
PAGER The program that long output is piped through when stdout is a terminal. The default is less -FRX. --no-pager prints directly.
GIT_EDITOR, core.editor, VISUAL, EDITOR The editor edhil commit opens, in the order git uses.