Setting Up OpenCode Beast Mode for Complex Experiment Generation in AutoResearchClaw

To enable OpenCode Beast Mode in AutoResearchClaw, install the OpenCode CLI (npm i -g opencode-ai@latest), set opencode.enabled: true in your ARC configuration, and ensure complexity_threshold is configured (default 0.2); ARC will then automatically route complex experiments to the external OpenCode agent when score_complexity() returns a score above the threshold.

OpenCode Beast Mode is an optional code-generation pathway in AutoResearchClaw (ARC) designed for experiments that exceed the capabilities of the built-in CodeAgent. When activated, ARC spawns a temporary workspace, delegates the generation task to the external OpenCode CLI using a detailed mega-prompt, and returns a complete multi-file project. This mode is essential for multi-component neural architectures, custom loss functions, and sophisticated data pipelines that the standard agent cannot reliably produce.

How OpenCode Beast Mode Works

Beast Mode operates as an automated routing layer within ARC’s code generation pipeline. When an experiment plan is submitted, the system evaluates its structural complexity using a weighted scoring algorithm. If the complexity score meets or exceeds a configurable threshold, control passes to the OpenCodeBridge class, which manages the entire lifecycle from workspace preparation to file collection.

Complexity Scoring Algorithm

The decision to trigger Beast Mode begins with the score_complexity() function, located in researchclaw/pipeline/opencode_bridge.py (lines 31-86). This function analyzes the textual experiment plan and optional topic metadata, calculating a normalized score between 0.0 and 1.0 based on five weighted signals:

• Component count (weight 0.25): Detects keywords like encoder, decoder, or generator defined in _COMPONENT_KEYWORDS.
• File-hint count (weight 0.20): Identifies explicit module references such as model.py or trainer.py via _FILE_HINT_KEYWORDS.
• Domain complexity (weight 0.20): Recognizes advanced domains like GAN, diffusion, or meta-learning from _DOMAIN_COMPLEX_KEYWORDS.
• Condition count (weight 0.15): Parses regex patterns for numbered conditions or "baseline" mentions.
• Historical failures (weight 0.10): Incorporates past execution failures passed as the historical_failures argument.
• Dependency depth (weight 0.10): Flags custom optimizers or complex dependency chains via _DEPENDENCY_KEYWORDS.

If the final weighted sum is greater than or equal to complexity_threshold (default 0.2 as specified in OpenCodeConfig), the recommendation becomes "beast_mode", causing the pipeline to instantiate OpenCodeBridge instead of the standard agent.

The OpenCodeBridge Lifecycle

The OpenCodeBridge class (defined at lines 60-69 in researchclaw/pipeline/opencode_bridge.py) encapsulates the entire Beast Mode workflow through the following methods:

1. check_available(): Verifies that the opencode CLI exists on the system $PATH and is callable.

2. _prepare_workspace(): Creates a clean temporary directory, initializes a minimal Git repository (required by OpenCode), and writes three essential files: EXPERIMENT_PLAN.yaml, GUIDANCE.md, and opencode.json.

3. _build_opencode_config(): Generates the JSON configuration consumed by the OpenCode CLI, wiring the LLM provider (OpenAI-compatible, Azure, or Anthropic) and model parameters.

4. _invoke_opencode(): Executes the command opencode run -m <model> --format json "<prompt>" within the workspace, respecting the user-defined timeout_sec and environment-variable API key handling.

5. _collect_files(): Traverses the workspace, flattens Python files to their basenames, and extracts dependency manifests (requirements.txt or setup.py).

6. _ensure_main_entry_point(): Validates or injects a runnable main.py containing a proper if __name__ == "__main__": guard clause.

7. generate(): Orchestrates the complete process, handling retry logic (up to max_retries), logging, optional workspace cleanup, and returning an OpenCodeResult object.

The pipeline integration occurs in researchclaw/pipeline/_code_generation.py (lines 530-560), where the code checks _cplx.recommendation == "beast_mode" before invoking OpenCodeBridge(...).generate(...).

Configuration and Setup

Enabling Beast Mode requires both external CLI installation and internal ARC configuration.

Install the OpenCode CLI

The OpenCode CLI must be installed globally and accessible in the environment where ARC executes:

npm i -g opencode-ai@latest

Verify availability by running opencode --version in your terminal or Docker container.

Enable Beast Mode in ARC Configuration

Configure Beast Mode parameters in your ARC configuration file (e.g., config.researchclaw.yaml). The OpenCodeConfig section in researchclaw/config.py (lines 41-55) defines the following adjustable fields:

opencode:
  enabled: true
  auto: true                # Auto-trigger without manual prompting

  complexity_threshold: 0.2
  model: ""                 # Optional: Leave empty to use primary LLM

  timeout_sec: 600
  max_retries: 1
  workspace_cleanup: true   # Deletes temp files after generation

Load the configuration via the --config CLI flag or set the RESEARCHCLAW_CONFIG environment variable to point to your YAML file.

Manual Invocation from Python

For direct programmatic access without the full pipeline, instantiate OpenCodeBridge manually:

from pathlib import Path
from researchclaw.pipeline.opencode_bridge import OpenCodeBridge

bridge = OpenCodeBridge(
    model="anthropic/claude-sonnet-4-6",
    timeout_sec=900,
    max_retries=2,
    workspace_cleanup=True,
)

result = bridge.generate(
    stage_dir=Path("./stage-10"),
    topic="Multi-modal diffusion for medical imaging",
    exp_plan="We need an encoder-decoder diffusion model with a custom loss, separate trainer, and data augmentation pipeline.",
    metric="FID",
    pkg_hint="torch, torchvision, einops",
    extra_guidance="Use mixed-precision training.",
    time_budget_sec=300,
)

if result.success:
    print("Generated files:", list(result.files.keys()))
else:
    print("Beast Mode failed:", result.error)

Monitoring and Debugging

ARC captures the raw stdout and stderr from the OpenCode CLI in a log file within the stage directory. Inspect this file to debug generation failures or timeouts:

cat stage-10/opencode_log.txt

This log contains the complete OpenCode execution trace, including any API errors or generation timeouts that occurred during the _invoke_opencode() phase.

Summary

• OpenCode Beast Mode is triggered automatically when score_complexity() in researchclaw/pipeline/opencode_bridge.py returns a score ≥ complexity_threshold (default 0.2).
• The OpenCodeBridge class manages the entire lifecycle: verifying CLI availability, preparing Git-enabled workspaces, invoking OpenCode with structured prompts, and ensuring valid main.py entry points.
• Configuration is controlled via OpenCodeConfig in researchclaw/config.py, allowing customization of timeouts, retries, LLM models, and auto-trigger behavior.
• Installation requires the external OpenCode CLI (opencode-ai npm package) alongside ARC’s Python environment.
• Generated code is captured in a temporary workspace and returned as an OpenCodeResult, with execution logs preserved in opencode_log.txt for debugging.

Frequently Asked Questions

How does AutoResearchClaw decide when to use Beast Mode instead of the standard CodeAgent?

ARC calls score_complexity() in researchclaw/pipeline/opencode_bridge.py to analyze the experiment plan for signals like component keywords (encoder, decoder), file hints (model.py), domain complexity (GAN, diffusion), and historical failure rates. If the weighted score exceeds the complexity_threshold defined in OpenCodeConfig (default 0.2), the pipeline routes the request to OpenCodeBridge.generate() rather than the built-in agent.

What prerequisites must be satisfied before enabling OpenCode Beast Mode?

You must install the OpenCode CLI globally using npm i -g opencode-ai@latest and ensure it is available on the system $PATH where ARC runs. Additionally, the opencode.enabled field must be set to true in your ARC configuration file, and valid API keys for your chosen LLM provider must be configured via environment variables.

Can I manually trigger Beast Mode for an experiment that ARC does not flag as complex?

Yes. You can instantiate OpenCodeBridge directly in Python, bypassing the automatic complexity scoring. Import the class from researchclaw.pipeline.opencode_bridge, configure the model and timeout parameters, and call the generate() method with your experiment plan. This approach is useful when you know a project requires multi-file generation regardless of the heuristic score.

Where are the generated files and logs stored during Beast Mode execution?

The OpenCodeBridge creates a temporary workspace directory (locations vary by OS) where it writes EXPERIMENT_PLAN.yaml, GUIDANCE.md, and the OpenCode configuration. Generated Python files are collected from this workspace into an OpenCodeResult object. Execution logs are preserved in opencode_log.txt inside the specified stage_dir (e.g., stage-10/opencode_log.txt), allowing post-hoc analysis of the OpenCode CLI output.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}