anomalyco / anomalyco/opencode
Docs: hidden is documented as subagent-only, but the TUI applies it to every mode
@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 withhidden: 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: subagentagents.
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 configas
{"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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.