# Setting Up OpenCode Beast Mode for Complex Experiment Generation in AutoResearchClaw

> Unlock OpenCode Beast Mode in AutoResearchClaw for advanced experiment generation. Easily configure the CLI and ARC to automate complex research tasks and boost your workflow.

- Repository: [AIMING Lab/AutoResearchClaw](https://github.com/aiming-lab/AutoResearchClaw)
- Tags: how-to-guide
- Published: 2026-05-28

---

**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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/EXPERIMENT_PLAN.yaml), [`GUIDANCE.md`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/GUIDANCE.md), and [`opencode.json`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/requirements.txt) or [`setup.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/setup.py)).

6. **`_ensure_main_entry_point()`**: Validates or injects a runnable [`main.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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:

```bash
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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/config.researchclaw.yaml)). The `OpenCodeConfig` section in **[`researchclaw/config.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/config.py)** (lines 41-55) defines the following adjustable fields:

```yaml
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:

```python
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:

```bash
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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/main.py) entry points.
- Configuration is controlled via **`OpenCodeConfig`** in [`researchclaw/config.py`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/EXPERIMENT_PLAN.yaml), [`GUIDANCE.md`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/opencode_log.txt) inside the specified `stage_dir` (e.g., [`stage-10/opencode_log.txt`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/stage-10/opencode_log.txt)), allowing post-hoc analysis of the OpenCode CLI output.