Sign up
View stargazersSign up

[Bug]: OpenCode project-local agents are missing from the agent picker#11871

openedSep 15, 2026byKKostasKgr

Before submitting

  • I searched existing issues and did not find a duplicate.
  • I included enough detail to reproduce or investigate the problem.

Area

apps/server

Steps to reproduce

  1. Create a project-local OpenCode agent at .opencode/agent/readonly.md inside a project's folder, not global config:

    markdown
    1---
    2description: Read-only agent for inspecting the project.
    3mode: all
    4permission:
    5 edit: deny
    6 bash: deny
    7 todowrite: deny
    8---
    9
    10You are a read-only agent.

  2. From the project directory, run:

    shell
    1opencode agent list

  3. Confirm that OpenCode reports the project-local agent:

    text
    1build (primary)
    2plan (primary)
    3readonly (all)

  4. Add or open the same directory as a project in T3 Code.

  5. Select the OpenCode provider and open the agent selector.

Expected behavior

T3 Code should include visible project-local OpenCode agents whose mode is primary or all.

The readonly agent should appear alongside the built-in build and plan agents, matching the agents OpenCode reports when invoked from that project directory.

Actual behavior

The project-local readonly agent is absent from the T3 Code agent selector.

The OpenCode provider cache contains only the globally discovered build and plan agents, even though:

  • The chat session is started with the correct project directory.
  • opencode agent list from that directory reports readonly (all).
  • The agent definition is valid and available in the native OpenCode interface.

This appears to happen because OpenCode agent capabilities are cached at the provider-instance level using a discovery directory that can differ from the selected project's directory. Project-local agents are therefore not represented in the cached model capabilities used by the composer.

Impact

Major degradation or frequent failure

Project-specific agents are a supported OpenCode configuration mechanism. Their absence means workflows and permission profiles defined by individual projects cannot be selected through T3 Code.

Version or commit

  • T3 Code: 0.0.40
  • OpenCode: 1.18.31

Environment

Linux, T3 Code web/server mode, OpenCode provider.

Logs or stack traces

shell
1# From the affected project:
2$ opencode agent list
3
4build (primary)
5compaction (primary)
6explore (subagent)
7general (subagent)
8plan (primary)
9summary (primary)
10title (primary)
11readonly (all)
12
13# Agent options represented in ~/.t3/caches/opencode.json:
14[
15 "build",
16 "plan"
17]

The corresponding OpenCode session metadata confirms that T3 starts the chat with the affected project as its working directory.

Related issues

  • #7853 reported globally configured custom agents being omitted. It was closed after #8480 changed discovery to OpenCode's native app.agents API. This report is different: globally available built-ins are discovered, but agents defined under a specific project's .opencode/agent/ directory are still absent.
  • #9833 concerns the separate client-side feature flag that hides the built-in plan agent. It does not cover project-local agent discovery.

Workaround

Use the project-local agent through the native OpenCode tui or web ui. No T3 Code workaround is currently known.

JJulius MarmingeSep 15, 2026

Triage

Confirmed bug in OpenCode agent catalog discovery, not the picker UI.

T3 already filters correctly (!hidden and mode of primary or all). A project-local agent such as .opencode/agent/readonly.md with mode: all would appear if it were in the inventory. It never gets there.

Why

OpenCode agent options are baked into the provider-instance model snapshot during checkOpenCodeProviderStatus, using ServerConfig.cwd (the T3 process working directory), then written to ~/.t3/caches/opencode.json. That cache is one file per instance and does not include workspace snapshots.

Per-project refresh exists only for skills:

  • OpenCodeDriver.snapshotForCwd reloads app.skills with the project directory
  • ServerProviderWorkspaceSnapshot stores skills / slashCommands only
  • composers resolve skills per cwd, but read the agent selector from instance-level models[].capabilities

Chat sessions already start with the correct project directory (adapter path). Catalog discovery does not follow that directory. That matches the report: opencode agent list shows readonly (all), while the cache only has build and plan.

This is the same class of cwd bug skills already fixed, left unfixed for agents after #8480 switched discovery to app.agents.

Not a duplicate

  • #7853 / #8480 — global custom agents / app.agents. Built-ins are discovered; project .opencode/agent/ is not.
  • #9833 — client flag hiding built-in plan. Unrelated to project-local discovery.
  • No open PR clearly fixes .opencode/agent/ listing.

Suggested fix

Reload agents in snapshotForCwd via app.agents with the project directory, persist cwd-scoped agent options (workspace snapshot / contracts), and have web + mobile composers resolve the agent picker from that cwd the same way they resolve skills. Changing only the initial probe cwd is not enough: T3 is multi-project and the instance cache would still be a single list.

Surfaces

Server snapshot + cache first. Agent pickers on web, desktop (wraps web), and mobile all consume that catalog.

Ddaniel0x0018d ago
Synced from GitHub

This issue/bug is quite critical for us. We have invested a lot of time in opencode harnessing with a primary agent and many subagents; but the main agent is not possible to be picked and saved as default in T3.

JJulius Marminge8d ago

Existing fix: #21532 covers workspace-local OpenCode agent discovery and explicitly fixes this issue. It is open and awaiting human approval for agent-default/execution behavior. No duplicate fix PR is needed; leaving this issue open until that work lands. On main b5a226e49c, OpenCode 1.18.18 lists the reported readonly (all) fixture from its project directory; the T3 picker comparison was not completed before locating the existing fix.

JJulius Marminge8d ago

Reproduced on current main 3b95e7831b, Linux web/server mode with OpenCode 1.18.18. Created the reported .opencode/agent/readonly.md, ran opencode agent list from that project, added the same folder in T3, selected OpenCode / Big Pickle, and opened the agent menu. Native OpenCode lists readonly (all); T3 offers Build and omits readonly. The isolated server cache contains only build/plan agent options.

Runtime discovery transcript

Current main: project-local readonly agent missing from the Agent menu

Existing fix #21532 remains open; added bugfix while preserving its other labels. It has 31 successful checks, reports conflicts against current main, and its existing report requires human review of agent-default/execution behavior. No duplicate fix PR or branch changes. Leaving this issue open for that fix.

Tthe-data-sherpa2d ago
Synced from GitHub

Adding evidence that on OpenCode 2 this bug is broader than project-local agents. With OpenCode 2.2.0, no agents reach the picker at all, including globally defined primary agents. The agent dropdown cannot offer anything beyond the default.

Environment

  • T3 Code (Beta) 0.1.3, macOS desktop
  • OpenCode 2.2.0 (provider cache reports status: ready, "OpenCode 2.2.0 lists 88 models")

Setup

A global (not project-local) primary agent at ~/.config/opencode/agents/lead.md:

markdown
1---
2description: Coordinate scoped work across coder, verifier, and specialized reviewers; ...
3mode: primary
4...
5---

OpenCode's own API reports it. The agent qualifies on every filter T3 applies (mode: primary, hidden: false):

text
1$ opencode api agent.list
2lead mode=primary hidden=False
3build mode=primary hidden=False
4plan mode=primary hidden=False
5general mode=subagent hidden=False
6... (25+ subagents)

Actual

~/.t3/caches/opencode.json (refreshed today) contains zero agent option descriptors on every model. The custom agent is missing, and so are build and plan:

text
1lead in cache: False
2No agent optionDescriptor found on any model

The T3 agent dropdown therefore has no agents to offer, and the globally defined lead agent is unselectable. This differs from the original 1.x report, where the global built-ins (build, plan) were discovered and only project-local agents were missing.

Likely cause

OpenCode 2 replaced the v1 REST paths with an operation-ID API surface. GET /agent on a 2.2.0 server now returns the web app's HTML shell rather than JSON. The working call is the agent.list operation (opencode api agent.list). If catalog discovery still requests the v1 path, it silently receives HTML and bakes an empty agent catalog into the provider cache. That matches what the cache shows.

Implication for the fix

#21532 scopes agent discovery to the workspace, which addresses the 1.x project-local symptom. If discovery itself gets nothing back from an OpenCode 2 server, workspace scoping alone will not restore the picker. Worth verifying that PR against OpenCode 2.x before this issue is closed on it.

Ssoares-daniel1d ago
Synced from GitHub

Cross-linking the OpenCode 2 half, since it is now reproduced independently.

On T3 Code main 5211acfe95, Linux web/server, OpenCode 2.2.0, with no project-local agents:

  • Every model in the provider cache has zero agent option descriptors. The picker only has its fixed Build default (Plan appears in plan mode).
  • The cause is separate from the 1.x cwd/discovery problem in this issue: the v2 snapshot path emits only the reasoning option, and the v2 adapter hard-codes build/plan instead of using a selected agent.

I verified a narrow v2 fix (agent.list plus the configured default_agent feeding the agent descriptor, then agentFor reading the selection) with focused tests and vp run check:changed (47 tests). Details and the patch are on #21532: https://github.com/pingdotgg/t3code/pull/21532#issuecomment-6490521672

This does not close the original project-local case here; #21532 remains the fix for that. I am not opening a duplicate PR.