anomalyco / anomalyco/opencode

Custom agent with "name" field breaks 'opencode run --agent <key>' resolution (agent=undefined -> Unexpected server error)

Open
#42,507 2 comments 1 reaction 1 assignee View on GitHub

@jlongster is already working on this.

Since Aug 14, 2026.

Dominant language
TypeScript
Stars
209k
Forks
27.5k
PR merge metrics
PR metrics pending

Description

Bug: custom agent with a name field breaks opencode run --agent <key> resolution

Symptom

Defining a custom agent in opencode.json with a name field (display name different from the config key) makes opencode run --agent <key> fail with:

Error: {
  "name": "UnknownError",
  "data": { "message": "Unexpected server error. Check server logs for details.", "ref": "err_..." }
}

The created session is logged with agent=undefined. Passing the display name instead (--agent "<display name>") gives "agent not found. Falling back to default agent".

Repro
// opencode.json (with or without plugins — reproduces with `--pure`)
{
  "agent": {
    "tmp-ocb": {
      "mode": "primary",
      "name": "Tmp OCB Display",
      "description": "test"
    }
  }
}
opencode run --agent tmp-ocb "Reply OK"        # → Unexpected server error (agent=undefined)
opencode run --agent "Tmp OCB Display" "Reply OK"  # → "agent not found. Falling back to default agent"

Removing the name field fixes it: --agent tmp-ocb then resolves and runs normally.

Isolation

Reproduces with --pure (no external plugins loaded), so this is an opencode core issue, not plugin-related.

Notes
  • name is not documented in the AgentConfig schema (https://opencode.ai/config.json) yet packages/opencode/src/agent/agent.ts reads it (item.name = value.name ?? item.name). The run-path agent lookup does not handle a key whose display name differs from the key.
  • Environment: opencode 1.18.18 (standalone binary), Linux.
Expected

Either opencode run --agent <key> resolves the agent regardless of a differing name field, or the name field is documented/validated explicitly (rejected if unsupported) instead of silently breaking the lookup.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.