Skip to content

opencode-profiles.md

Latest commit

 

History

History
174 lines (112 loc) · 8.45 KB

opencode-profiles.md

File metadata and controls

174 lines (112 loc) · 8.45 KB

OpenCode SDD Profiles

← Back to README

You configured your SDD models once, and now every task -- cheap or expensive, experimental or battle-tested -- runs through the same orchestrator. Profiles fix that: create named model configurations and switch between them with Tab inside OpenCode.

Gentle AI supports two ways of working with OpenCode profiles:

  1. Generated multi-profile mode -- the classic Gentle AI flow. The base SDD conductor is gentle-orchestrator. Each named profile generates its own sdd-orchestrator-{name} plus 10 suffixed sub-agents in opencode.json, and you switch between them with Tab.
  2. External single-active mode -- for community tools that keep profile files outside opencode.json and activate one runtime profile at a time.

That means you can stay with the built-in multi-profile overlay, or plug Gentle AI into an external profile manager without the two systems fighting each other.

Quick Start (TUI)

  1. Launch the installer: gentle-ai (or go run ./cmd/gentle-ai).
  2. Select "OpenCode SDD Profiles" from the welcome screen.
  3. Select "Create new profile" (or press n).
  4. Enter a profile name in slug format (lowercase, hyphens ok). Example: cheap.
  5. Pick the orchestrator model (provider, then model -- reuses the existing model picker).
  6. Assign sub-agent models (use "Set all phases" for a uniform config, or set each phase individually).
  7. Confirm -- the installer writes the profile to opencode.json and runs sync.

Open OpenCode and press Tab -- your new orchestrator appears alongside gentle-orchestrator, the default OpenCode SDD conductor.

Reasoning effort levels (per-model variants)

For models that expose reasoning effort variants (e.g. OpenAI gpt-5 with low/medium/high/xhigh), the picker shows an extra Select reasoning effort level step right after you choose the model. Pick default to use the provider's default, or pick a specific level to lock the assignment to that effort.

The effort options are populated from a cache file written by the bundled model-variants OpenCode plugin at ~/.gentle-ai/cache/model-variants.json. The plugin runs the first time OpenCode starts after gentle-ai sync and refreshes the cache on every subsequent start.

First-run order matters:

  1. Run gentle-ai (installs the plugin into ~/.config/opencode/plugins/).
  2. Run opencode once -- on startup the plugin queries the provider list and writes ~/.gentle-ai/cache/model-variants.json.
  3. Re-run gentle-ai and open the model picker. Reasoning models now show the effort selector.

If the JSON does not exist yet (plugin has not run, no providers expose variants, or the request failed silently), reasoning models still work -- the picker simply skips the effort step and saves the assignment with the provider default. You will not see the [effort] annotation next to those rows in the phase list.

Key Names To Remember

Use this table when reviewing configs or debugging profile sync:

Agent key Meaning Safe to rename manually?
gentle-orchestrator Canonical base OpenCode SDD conductor. All /sdd-* commands point here by default. No
sdd-orchestrator Legacy base conductor key. Sync migrates it to gentle-orchestrator. No; let sync migrate it
sdd-orchestrator-{name} Generated named profile conductor, such as sdd-orchestrator-cheap. No; use TUI or CLI
sdd-{phase} Default sub-agent for a phase, such as sdd-apply. No
sdd-{phase}-{name} Named profile sub-agent, such as sdd-apply-cheap. No

Quick Start (CLI)

Create a profile during sync with --profile name:provider/model:

gentle-ai sync --profile cheap:anthropic/claude-haiku-3.5-20241022

Multiple profiles in one command:

gentle-ai sync \
  --profile cheap:anthropic/claude-haiku-3.5-20241022 \
  --profile premium:anthropic/claude-opus-4-20250514

Override a specific phase with --profile-phase name:phase:provider/model:

gentle-ai sync \
  --profile cheap:anthropic/claude-haiku-3.5-20241022 \
  --profile-phase cheap:sdd-apply:anthropic/claude-sonnet-4-20250514

This creates a "cheap" profile where everything runs on Haiku except sdd-apply, which uses Sonnet.

External Profile Managers

If you're using a community tool that stores profiles under ~/.config/opencode/profiles/*.json and activates them at runtime, Gentle AI can now sync OpenCode in a compatibility mode.

Auto-detection

On gentle-ai sync, if OpenCode profile files exist under:

~/.config/opencode/profiles/*.json

Gentle AI automatically switches to external-single-active strategy for OpenCode sync.

Manual override

You can also force the strategy explicitly:

gentle-ai sync --agent opencode --sdd-profile-strategy external-single-active

Or force the classic generated overlay behavior:

gentle-ai sync --agent opencode --sdd-profile-strategy generated-multi

What compatibility mode does

In external-single-active mode, Gentle AI:

  • keeps writing the base OpenCode SDD assets and shared prompt files
  • does not auto-regenerate suffixed named profiles from opencode.json
  • preserves the current gentle-orchestrator prompt during sync so external tools can keep their runtime policy / fallback blocks intact

This is the important bit: Gentle AI still maintains the SDD foundation, but it stops acting like opencode.json is the source of truth for every profile.

Using Profiles in OpenCode

After creating profiles in generated multi-profile mode, each one appears as a selectable orchestrator in OpenCode:

What you see in Tab What it runs
gentle-orchestrator Default profile (your original config)
sdd-orchestrator-cheap "cheap" profile -- Haiku everywhere
sdd-orchestrator-premium "premium" profile -- Opus everywhere

Press Tab to cycle between orchestrators. All SDD slash commands (/sdd-new, /sdd-ff, /sdd-explore, etc.) run against whichever orchestrator is currently selected. The orchestrator delegates to its own suffixed sub-agents (e.g., sdd-apply-cheap), so profiles never interfere with each other.

If you're using an external single-active manager instead, you typically keep working with the base gentle-orchestrator while the external tool swaps its active model assignments at runtime.

Managing Profiles

From the TUI profile list screen:

Action Key Notes
Edit a profile Enter on the profile Change models, then sync
Delete a profile d on the profile Removes orchestrator + all sub-agents from JSON
Create a new profile n (or select "Create new profile") Full creation flow

The default profile (gentle-orchestrator) can be edited but not deleted -- it always exists when SDD is configured.

Profile name rules

Input Valid? Reason
cheap Yes Simple slug
premium-v2 Yes Hyphens allowed
my profile No Spaces not allowed
default No Reserved for the base orchestrator
LOUD Becomes loud Auto-lowercased
How It Works

In generated multi-profile mode, each named profile generates 11 agent entries in opencode.json: one orchestrator (sdd-orchestrator-{name}, mode primary) and 10 sub-agents (sdd-{phase}-{name}, mode subagent, hidden). The base/default conductor remains gentle-orchestrator. Each named profile orchestrator's permissions are scoped so it can only delegate to its own suffixed sub-agents.

Sub-agent prompts are shared across all profiles as files under ~/.config/opencode/prompts/sdd/ (e.g., sdd-apply.md). Each agent entry references the shared file via {file:~/.config/opencode/prompts/sdd/sdd-apply.md} -- only the model field differs between profiles. Orchestrator prompts are inlined per-profile because they contain profile-specific model assignment tables and sub-agent references.

During sync or update, Gentle AI now uses one of two strategies:

  • generated-multi -- scan opencode.json for sdd-orchestrator-*, update shared prompts, regenerate profile orchestrators, preserve model assignments, and keep gentle-orchestrator as the canonical base conductor
  • external-single-active -- detect external profile files, keep the shared SDD assets current, and preserve the existing gentle-orchestrator prompt instead of overwriting external runtime extensions

← Back to README