Choosing an agent

edhil does not write code itself. It hands each work item to a coding agent, and the agent is a program you already use: GitHub Copilot, Claude Code, Codex or opencode. This page helps you choose one, set it up for yourself or for the team, and switch between setups. The keys of the configuration are described in Configuration; the details and the limits of each tool are in the section of that tool on the same page.

Two words are used all through the book. A tool is a program edhil knows how to run. An agent is a named setup of one tool: which tool, which program, which model, which extra arguments. Without any configuration the agent is copilot, the tool with its own defaults.

The four tools

Tool Program The model is written What edhil passes The answer The transcript
claude claude --model sonnet, an alias or a full name -p, --permission-mode acceptEdits, --permission-prompts none, --allowedTools Bash, --session-id Standard output The session file that claude keeps
codex codex -m MODEL, as your account of codex offers it exec, --sandbox workspace-write, -o Standard output, else the final message file The session file that codex keeps, else its log
copilot copilot --model MODEL -p, -s, --no-ask-user, --allow-all-tools, --deny-tool, --share Standard output The file that Copilot shares
opencode opencode -m PROVIDER/MODEL, as opencode models lists it run, --auto Standard output What opencode printed, without its colors

Every tool also gets the instruction to read the prompt file of the step, and then the extra_args of the agent, after everything else. The model is only passed when the agent has one; without it the tool uses its own default.

Copilot is the default because it was the first. Nothing in edhil makes one tool better than another: the choice is about the account you have, the models you want and the cost.

What is the same for every tool

  • The agent only edits files. It cannot commit, switch branches or push, whatever the tool: a program in front of git on its PATH refuses those commands, and edhil checks the repository itself after every step. See How edhil works.
  • The permission settings of a tool are not a sandbox. Each tool is started so that it never waits for an answer, and for every tool that means it is allowed to do more than edit files. Do not run edhil in a repository, or on a computer, where an agent that writes outside the repository or reaches the network would be a problem.
  • A step without an answer is not a success. The answer is read from what the tool prints. A tool can end with exit code 0 and say nothing useful, for example when a permission was denied. The run then pauses, and the log of the step shows what the tool printed.
  • Your own configuration of the tool applies. Its plugins, instruction files and settings are read as when you use the tool yourself, because edhil does not isolate the run from them.
  • Stopping kills what the tool started. When a step times out or you stop the run, the tool and the commands it started are killed.

Setting up an agent

The simplest setup is no setup: edhil implement 123 --agent claude runs claude with its own defaults, and so do codex and opencode.

To choose a model, or to keep several setups, write agents. A team can agree on some in edhil.yaml, which is committed:

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

integration:
  agents:
    fast:
      tool: copilot
      model: gpt-5
    strong:
      tool: claude
      model: sonnet

and each person adds their own in edhil.user.yaml, which is not committed, and chooses the one to use:

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

With both files, local is the agent of this person, and fast and strong are there as well. If both files define an agent with the same name, the personal one replaces the other as a whole.

Switching

Which agent runs, in this order:

  1. The option --agent NAME on implement or commit, before or after the command: edhil implement 123 --agent strong, edhil commit --agent fast.
  2. The setting integration.agent.
  3. copilot.

One agent is used for a whole command. NAME is an agent from agents or the name of a tool. An unknown name stops the command before anything starts and lists the names that exist.

Before implement asks anything, and before commit stages anything, edhil checks that the agent exists, that its options are acceptable and that its program can be found. To see which agent did the work of a run afterwards, look at the line Agent: in the report of the run, with edhil log 12.

When it does not work

What you see What it means
The agent 'x' needs the program 'y', which cannot be found. The tool is not installed, or not on the PATH. Install it, set command of the agent to its path, or choose another agent with --agent.
An unknown agent, with a list of the names that exist The name is not one of the agents of the two files and is not a tool. Check the spelling.
The agent 'x' passes ... in extra_args An option that would change what the tool prints, so that edhil could not read the answer, or that edhil sets itself. Remove it from extra_args. The section of the tool names the options.
The run pauses with The agent did not give a usable description of the change The tool ended without an answer in the form edhil needs. edhil log N --item I --step S shows what it printed: a model that does not exist, a login that expired and a permission that was denied all end up here.
edhil commit says The agent exited with code 1 The tool failed. Run edhil commit --no-agent to write the message yourself, and look at the tool on its own.