Project settings
Zekoder settings come in two scopes:
- Project settings apply to one repository. Open a workspace, select + → Zekoder settings.
- Machine defaults apply to every repository on the host. Select Zekoder in the sidebar → Defaults.
Project settings are stored in the repository's .zekoder/config.json, which is not committed, so each developer keeps their own. Every control saves as soon as you change it. A field you leave unset shows the value Zekoder uses instead, with "Not set — using default".
You can also change every setting from the chat with /zekoder-config.
Basic
Default branch
The branch plans and implemented work land on. Leave it empty to auto-detect: the remote's default branch, then main or master. Select Save to set it or Clear (auto-detect) to reset it. The branch must exist locally.
Merge
| Setting | Options | Meaning |
|---|---|---|
| Default merge mode | Open a PR, Merge locally, Ask each time | How finished work lands. Open a PR opens one pull request for you to review and merge. Merge locally merges into the default branch without a pull request and pushes nothing. |
| Worktree cleanup | Always, Never, Ask each time | Whether task worktrees are removed after they merge. |
| Branch deletion | Always, Never, Ask each time | Whether task branches are deleted after they merge. A branch is kept while its worktree is. |
The same merge mode decides how an approved plan lands. If your main checkout is not on the default branch, only Open a PR works.
Planning
| Setting | Options | Meaning |
|---|---|---|
| Planning tier | Auto, Always full | Auto lets the planner offer a light plan for small changes. Always full plans everything in full. |
| Reviewer policy | Tiered, Always Opus | Tiered reviews light plans with the shorter checklist. Always Opus uses the full checklist for every plan. Both use the session's model. |
| Max packages per feature | a number | The most packages a full feature may split into. Empty means no limit. |
Coding
Simplify
After each task merges, a simplify pass can clean up the merged code. A failed pass never blocks the merge.
| Simplify mode | When the pass runs |
|---|---|
| Auto | When a task's files overlap another task's in the same run (the default). |
| Always required | After every task. Slower: one more agent and another round of checks. |
| Never required | Never. |
| Smart (thresholds below) | Like Auto, plus when a task crosses one of the thresholds. |
With Smart, set the thresholds: Max judgment passes (0 turns them off), Min fix-forwards, Min new files, Min changed lines, and Min gate retries.
Prompts
Custom prompt adds up to 2,000 characters of extra instructions to every planning and coding prompt in this repository, for example your team's commit message style.
Agent defaults
The Planning session (on the Planning tab) and Coding session (on the Coding tab) sections choose what agents start with:
- Planning applies to Promote and Migrate on the Issues screen.
- Coding applies to Implement.
Each has Provider, Model, Effort, and Access mode. Leave a field at Provider default to use the provider's own default. Changing the provider clears the model, effort, and mode for that session.
A model can be a family name such as opus or sonnet on Claude Code. Zekoder starts the newest model in that family at launch.
Role defaults
Under Role defaults you can set the model and effort for each Zekoder agent role, such as the planner, the plan reviewer, the supervisor, and the coding agent, per provider. Agent default (unset) uses the role's own default. Inherit session model keeps the model of the session that starts the role. Models are checked when the role starts.
Which value wins
Values resolve field by field, highest first:
- The active execution profile, if you use one.
- The project setting.
- The machine default.
- The provider's own default.
Each value shows where it comes from, such as opus · repo or opus · machine. Select Reset planning defaults or Reset coding defaults to clear the project's values so the machine defaults show through.
If a model, effort, or mode set at the project level is not offered by the provider, the launch stops with an error naming the setting. A value inherited from a lower level is dropped instead, and the provider default is used.
Telemetry
On the Zekoder page → Telemetry, choose Opt in or Opt out of anonymous usage events. The choice applies to every repository on this machine.