Choosing an agent
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
PATHrefuses 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:
- The option
--agent NAMEonimplementorcommit, before or after the command:edhil implement 123 --agent strong,edhil commit --agent fast. - The setting
integration.agent. 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. |