Merge pull request subsy#123 from manascb1344/feature/issue-122-opencode-variant-support

feat(opencode): add support for --variant flag

Author: subsy

src/commands/run.tsx

@@ -115,6 +115,13 @@ export function parseRunArgs(args: string[]): ExtendedRuntimeOptions {
         }
         break;
 
+      case '--variant':
+        if (nextArg && !nextArg.startsWith('-')) {
+          options.variant = nextArg;
+          i++;
+        }
+        break;
+
       case '--tracker':
         if (nextArg && !nextArg.startsWith('-')) {
           options.tracker = nextArg;
@@ -239,6 +246,7 @@ Options:
   --prd <path>        PRD file path (auto-switches to json tracker)
   --agent <name>      Override agent plugin (e.g., claude, opencode)
   --model <name>      Override model (e.g., opus, sonnet)
+  --variant <level>   Model variant/reasoning effort (minimal, high, max)
   --tracker <name>    Override tracker plugin (e.g., beads, beads-bv, json)
   --prompt <path>     Custom prompt file (default: based on tracker mode)
   --output-dir <path> Directory for iteration logs (default: .ralph-tui/iterations)

src/config/index.ts

@@ -299,6 +299,14 @@ function getDefaultAgentConfig(
       };
     }
 
+    // Apply CLI --variant to agent options (for agents like OpenCode that support it)
+    if (options.variant) {
+      result = {
+        ...result,
+        options: { ...result.options, variant: options.variant },
+      };
+    }
+
     // Apply fallbackAgents shorthand (only if not already set on agent config)
     if (storedConfig.fallbackAgents && !result.fallbackAgents) {
       result = {

src/config/types.ts

@@ -90,6 +90,9 @@ export interface RuntimeOptions {
   /** Override model for the agent */
   model?: string;
 
+  /** Override model variant for the agent (e.g., minimal, high, max for Gemini) */
+  variant?: string;
+
   /** Override tracker plugin */
   tracker?: string;
 

src/plugins/agents/builtin/opencode.ts

@@ -135,6 +135,9 @@ export class OpenCodeAgentPlugin extends BaseAgentPlugin {
   /** Model name (without provider prefix) */
   private model?: string;
 
+  /** Model variant (provider-specific reasoning effort: high, max, minimal) */
+  private variant?: string;
+
   /** Agent type to use (general, build, plan) */
   private agent: string = 'general';
 
@@ -153,6 +156,12 @@ export class OpenCodeAgentPlugin extends BaseAgentPlugin {
       this.model = config.model;
     }
 
+    // Accept any variant string - validation is delegated to OpenCode CLI
+    // Different models support different variant values (e.g., Gemini: minimal/high/max)
+    if (typeof config.variant === 'string' && config.variant.length > 0) {
+      this.variant = config.variant;
+    }
+
     if (
       typeof config.agent === 'string' &&
       ['general', 'build', 'plan'].includes(config.agent)
@@ -328,6 +337,11 @@ export class OpenCodeAgentPlugin extends BaseAgentPlugin {
       args.push('--model', modelToUse);
     }
 
+    // Add model variant if specified
+    if (this.variant) {
+      args.push('--variant', this.variant);
+    }
+
     // Always use JSON format for streaming output parsing
     // This gives us structured events (text, tool_use, etc.) that we can format nicely
     args.push('--format', 'json');
@@ -423,6 +437,8 @@ export class OpenCodeAgentPlugin extends BaseAgentPlugin {
       return 'Invalid agent type. Must be one of: general, build, plan';
     }
 
+    // Variant validation is delegated to OpenCode CLI - different models support different values
+
     return null;
   }
 

tests/commands/run.test.ts

@@ -72,6 +72,28 @@ describe('run command', () => {
       });
     });
 
+    describe('variant option', () => {
+      test('parses --variant with value', () => {
+        const result = parseRunArgs(['--variant', 'high']);
+        expect(result.variant).toBe('high');
+      });
+
+      test('parses --variant max', () => {
+        const result = parseRunArgs(['--variant', 'max']);
+        expect(result.variant).toBe('max');
+      });
+
+      test('parses --variant minimal', () => {
+        const result = parseRunArgs(['--variant', 'minimal']);
+        expect(result.variant).toBe('minimal');
+      });
+
+      test('ignores --variant without value', () => {
+        const result = parseRunArgs(['--variant']);
+        expect(result.variant).toBeUndefined();
+      });
+    });
+
     describe('tracker option', () => {
       test('parses --tracker with name', () => {
         const result = parseRunArgs(['--tracker', 'beads']);
@@ -262,6 +284,7 @@ describe('run command', () => {
           '--epic', 'my-epic',
           '--agent', 'claude',
           '--model', 'opus',
+          '--variant', 'high',
           '--tracker', 'beads-bv',
           '--iterations', '15',
           '--delay', '1000',
@@ -272,6 +295,7 @@ describe('run command', () => {
         expect(result.epicId).toBe('my-epic');
         expect(result.agent).toBe('claude');
         expect(result.model).toBe('opus');
+        expect(result.variant).toBe('high');
         expect(result.tracker).toBe('beads-bv');
         expect(result.iterations).toBe(15);
         expect(result.iterationDelay).toBe(1000);
@@ -322,6 +346,7 @@ describe('run command', () => {
       const output = consoleOutput.join('\n');
       expect(output).toContain('--prd');
       expect(output).toContain('--model');
+      expect(output).toContain('--variant');
       expect(output).toContain('--delay');
       expect(output).toContain('--cwd');
       expect(output).toContain('--resume');

tests/plugins/opencode-agent.test.ts

@@ -59,6 +59,18 @@ describe('OpenCodeAgentPlugin', () => {
       expect(await plugin.isReady()).toBe(true);
     });
 
+    test('accepts variant config', async () => {
+      // Variant validation is delegated to OpenCode CLI - any string is accepted
+      await plugin.initialize({ variant: 'high' });
+      expect(await plugin.isReady()).toBe(true);
+    });
+
+    test('accepts any variant string', async () => {
+      // Different models support different variants, so we accept any value
+      await plugin.initialize({ variant: 'custom-variant' });
+      expect(await plugin.isReady()).toBe(true);
+    });
+
     test('accepts agent type config', async () => {
       await plugin.initialize({ agent: 'build' });
       expect(await plugin.isReady()).toBe(true);
@@ -140,6 +152,15 @@ describe('OpenCodeAgentPlugin', () => {
       expect(await plugin.validateSetup({ provider: 'google' })).toBeNull();
       expect(await plugin.validateSetup({ provider: 'custom-provider' })).toBeNull();
     });
+
+    test('accepts any variant string', async () => {
+      // Variant validation is delegated to OpenCode CLI - different models have different values
+      expect(await plugin.validateSetup({ variant: 'minimal' })).toBeNull();
+      expect(await plugin.validateSetup({ variant: 'high' })).toBeNull();
+      expect(await plugin.validateSetup({ variant: 'max' })).toBeNull();
+      expect(await plugin.validateSetup({ variant: 'custom' })).toBeNull();
+      expect(await plugin.validateSetup({ variant: '' })).toBeNull();
+    });
   });
 
   describe('getSetupQuestions', () => {

website/content/docs/plugins/agents/opencode.mdx

@@ -43,6 +43,14 @@ opencode --version
     ralph-tui run --prd ./prd.json --agent opencode --model anthropic/claude-3-5-sonnet
     ```
   </Step>
+
+  <Step title="Select a Variant">
+    Control reasoning effort with `--variant`:
+
+    ```bash
+    ralph-tui run --prd ./prd.json --agent opencode --model google/gemini-2.5-pro --variant high
+    ```
+  </Step>
 </Steps>
 
 ## Configuration
@@ -58,6 +66,7 @@ agent = "opencode"
 [agentOptions]
 provider = "anthropic"
 model = "claude-3-5-sonnet"
+variant = "high"
 ```
 
 ### Full Config
@@ -74,6 +83,7 @@ timeout = 300000
 [agents.options]
 provider = "anthropic"
 model = "claude-3-5-sonnet"
+variant = "high"
 agent = "general"
 format = "default"
 ```
@@ -84,6 +94,7 @@ format = "default"
 |--------|------|---------|-------------|
 | `provider` | string | - | AI provider: `anthropic`, `openai`, `google`, `xai`, `ollama` |
 | `model` | string | - | Model name within the provider |
+| `variant` | string | - | Model reasoning effort (model-specific, e.g., `minimal`, `high`, `max` for Gemini) |
 | `agent` | string | `"general"` | Agent type: `general`, `build`, or `plan` |
 | `format` | string | `"default"` | Output format: `default` or `json` |
 | `timeout` | number | `0` | Execution timeout in ms (0 = no timeout) |
@@ -140,6 +151,18 @@ OpenCode supports multiple AI providers. Models are specified in `provider/model
 Model names are validated by the provider's API. Invalid model names result in errors from OpenCode, not Ralph TUI.
 </Callout>
 
+## Model Variants
+
+You can control the reasoning effort for supported models using the `variant` option:
+
+```bash
+ralph-tui run --agent opencode --model google/gemini-2.5-pro --variant max
+```
+
+<Callout type="info">
+Variant values are model-specific and validated by the provider's API. Check your model's documentation for supported variants.
+</Callout>
+
 ## Agent Types
 
 OpenCode offers specialized agent personalities:

website/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
+import "./.next/dev/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.