diegopetrucci/tlh-gui/acp-provider

ACP providers

Known agents can be discovered automatically when their CLI is installed on the host: opencode, omp, grok, and hermes appear as acp-opencode, acp-omp, acp-grok, and acp-hermes-agent. Inspect the target host's catalog with bb provider list and bb provider models <provider-id> using its environment or machine selector.

Agents in the official ACP registry can be added without writing JSON. bb acp registry [--refresh] [--json] lists them with a status: available, added, update available, built in (bb already ships it), or manual install (the agent ships only as a downloadable binary). bb acp add <agent-id> adds the agent as provider acp-<agent-id>, or moves an added agent to the registry's current version while keeping the fields edited by hand. bb acp remove <agent-id> removes it. The plugin's settings page shows the same list. An added agent is an entry in the Custom agents setting that runs npx -y <package> or uvx <package> on the thread's host, so the host needs Node.js or uv. The list is cached for six hours; when the registry cannot be reached the saved copy is shown with the reason.

To hide a detected ACP agent, use bb provider disable acp-opencode, or Disable on Settings → Providers. Restore it with bb provider enable acp-opencode. This leaves other ACP agents and the host CLI intact. Disabled agents skip background capability probing. bb provider list --all includes disabled agents.

Cursor project skills come from .cursor/skills, which can link to .agents/skills. BB lists these linked skills as read-only under cursor-project.

ACP agents report their own models and may reject unlisted model IDs. For acp-opencode the list mirrors the OpenCode catalog, so add a model to the OpenCode config rather than bb's customModels:

bb provider models acp-opencode --environment "$BB_ENVIRONMENT_ID"
bb thread spawn --provider acp-opencode --model <provider/model>

OpenCode agents are session modes, not models selectable through BB's model field. OpenCode reports its primary agents as the mode session option. BB asks OpenCode for its models and modes in the directory the thread will run in: the project's checkout for a new thread, the environment's directory otherwise. Custom agents from the OpenCode config directory and from the project's .opencode/ directory therefore appear in the mode menu:

bb provider models acp-opencode --project "$BB_PROJECT_ID"
bb thread spawn --provider acp-opencode --option mode=<agent>

A new agent file shows up once the stored list is ten minutes old and is read again. The same holds for a custom agent with dialect: "opencode"; every other ACP agent is asked once per machine.

bb lists only the agents OpenCode itself loads, and OpenCode does not read agent files from other folders such as .agents/agents/. To use such a folder, set OPENCODE_CONFIG_DIR as a machine variable or in a custom agent's env; a relative value is resolved in each workspace, so .agents lists every project's own .agents/agents/*.md:

printf '.agents' | bb machine env set OPENCODE_CONFIG_DIR

Every file in that folder must be a valid OpenCode agent file; OpenCode refuses to start on one it cannot parse, such as tools written as a comma-separated list.

Grok Build advertises models and thought_level options over ACP, so the picker follows the connected agent (including xhigh on grok-4.6).

BB launches OpenCode sessions with OPENCODE_CLIENT=acp and OPENCODE_ENABLE_QUESTION_TOOL=false, overriding inherited and custom launch values. Native questions have no ACP interaction handler in BB; agents use the ask-user-question plugin’s AskUserQuestion tool instead. This also applies to custom agents with dialect: "opencode" and does not change OpenCode config files.

BB also sets OPENCODE_PERMISSION from the thread's permission mode, which OpenCode merges over the permission keys of its own config. In accept-edits OpenCode edits files without asking and asks before shell commands, web fetches and paths outside the workspace; BB shows those requests as approvals. In full all four are allowed. Changing a thread's permission mode restarts the OpenCode session with the new policy; the conversation is restored.

OpenCode and Grok ACP support the core bb thread compact command; Cursor ACP does not expose compatible compaction. Check the actual agent's capabilities before attempting provider-specific recovery.

OpenCode Go subscription usage is available in Provider usage when the selected machine has OpenCode installed and a Go subscription. Sign in to Go in OpenCode on that machine, then refresh its OpenCode tab. Verify with bb settings usage --machine <id-or-name> --json; the SDK equivalent is bb.sdk.system.usageLimits({ hostId, providerId: "acp-opencode" }). BB reports Go's five-hour, weekly, and monthly usage and reset times, not local session token totals or other OpenCode providers' subscriptions.

The collector checks OPENCODE_API_KEY first. For an OpenCode 2 database at $XDG_DATA_HOME/opencode/opencode.db, it then reads the credential table API key or official Console OAuth credential that OpenCode selects for each integration (opencode-go before opencode). Otherwise it reads the active official Console account and organization in that database, then OPENCODE_AUTH_CONTENT or $XDG_DATA_HOME/opencode/auth.json. OpenCode 2 imports auth.json once when it upgrades an OpenCode 1 database and never reads auth.json, OPENCODE_AUTH_CONTENT, or the OpenCode 1 Console account, so the collector reads them only when there is no OpenCode 2 database. The default data directory is ~/.local/share/opencode. Database storage is read only; expired Console sessions must be refreshed by OpenCode. V2 OAuth requires the device login method and account/organization metadata for the official Console server. API-key login prefers the opencode-go credential and accepts the shared opencode credential when Go is subscribed. Custom launch env values take precedence over the host environment. A custom OpenCode wrapper must declare dialect: "opencode" and providerUsage: true to expose its usage. Missing credentials, rejected keys, and collection errors remain unavailable states rather than zero usage. Never print API keys when diagnosing setup.

Custom ACP agents

Register another ACP agent in the ACP providers plugin's customAgents setting, a JSON array: bb plugin config provider-acp set customAgents '[...]'. Agents from the official ACP registry are added to the same setting by bb acp add <agent-id>. The plugin re-registers its providers as soon as the setting changes; no restart is needed.

• Required: id (lowercase letters, digits, and dashes; permanent),

displayName, and command. The provider id is acp-<id>. cursor is reserved; an entry with id opencode, omp, grok, or hermes-agent replaces the shipped agent.

• Launch: args, env, and cwd.
• modelCli for CLI model listing and selection, reasoningCli for

launch-time reasoning flags, nativeReasoning for ACP session/set_config_option reasoning, and permissionCli for permission-mode launch flags.

• dialect (cursor, opencode, omp, or grok) selects the vendor side

channels bb reads.

• nativeSkillRoots adds native skills to the composer: a user list resolved

from the target host's home directory and a project list resolved from the workspace, each a relative path without dot segments.

• supportsManualCompaction (default false) shows /compact only for agents

that accept an explicit compaction request.