anomalyco / anomalyco/opencode

Docs: hidden is documented as subagent-only, but the TUI applies it to every mode

Open
#44,751 0 comments 1 reaction 1 assignee View on GitHub

@kommander is already working on this.

Since Aug 24, 2026.

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

Description

Summary

The Agents documentation says hidden applies only to subagents. The TUI applies
it to every mode, and the built-in agents rely on that.

What the docs say

From https://opencode.ai/docs/agents/ under Hidden:

Hide a subagent from the @ autocomplete menu with hidden: true. Useful for
internal subagents that should only be invoked programmatically by other agents
via the Task tool.

This only affects user visibility in the autocomplete menu. Hidden agents can
still be invoked by the model via the Task tool if permissions allow.

Note: Only applies to mode: subagent agents.

What the code does

The Tab-cycle list is built at packages/tui/src/context/local.tsx:77:

const agents = createMemo(() => sync.data.agent.filter((agent) => agent.mode !== "subagent" && !agent.hidden))

The !agent.hidden clause is evaluated for every mode. It is also the only
mechanism excluding the built-in system agents from the cycle: compaction,
title, and summary are each declared mode: "primary" with hidden: true
at packages/opencode/src/agent/agent.ts:221-259, and the docs describe them as
"not selectable in the UI".

So hidden on a primary or all agent is both supported and load-bearing,
while the documentation states it has no effect.

Verified behavior on 1.18.22

A markdown agent declared mode: all with hidden: true:

  • survives configuration resolution, reported by opencode debug config as
    {"mode": "all", "hidden": true}
  • is still resolved by opencode run --agent <name>, with no fallback warning
    and the correct executor in the output header
Why it matters

An agent dispatched programmatically through opencode run --agent must be
primary-capable, because run mode refuses mode: subagent:

! agent "probe-sub" is a subagent, not a primary agent. Falling back to default agent

A project shipping several such agents therefore pushes all of them into the
user's Tab cycle. hidden: true solves this cleanly, but the documentation's
note says it will not work, so the option is not reached.

Suggested change

In the Hidden section, replace the subagent-only note with the actual scope:
hidden removes a subagent from @ autocomplete, and removes any agent from the
primary-agent Tab cycle, and does not affect opencode run --agent resolution or
Task-tool invocation. A sentence noting that the built-in system agents use this
mechanism would make the intent clear.

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.