How to Configure HITL Intervention Modes in AutoResearchClaw for Different Research Stages

Configure HITL intervention modes in AutoResearchClaw by setting the mode parameter in HITLConfig and optionally overriding specific stages with stage_policies to control exactly when the pipeline pauses for human feedback.

AutoResearchClaw (aiming-lab/AutoResearchClaw) provides a flexible Human‑In‑The‑Loop (HITL) subsystem that lets you insert human feedback at any point of the research pipeline. You configure this behavior using the HITLConfig class from researchclaw/hitl/config.py, which defines intervention strategies through built‑in modes and granular stage‑specific policies.

Understanding the HITLConfig Structure

The HITL subsystem centers on the HITLConfig dataclass defined in researchclaw/hitl/config.py. This configuration object controls how and when the pipeline pauses for human intervention.

Core Configuration Parameters

According to the source code in researchclaw/hitl/config.py, a HITLConfig instance contains these key fields:

• enabled – Boolean toggle to activate or deactivate HITL for the entire run.
• mode – The global intervention strategy, specified as an InterventionMode enum value.
• stage_policies – Optional dictionary mapping stage indices to StagePolicy objects for per‑stage overrides.
• notifications – Controls UI prompts for pausing, resuming, or escalation alerts.

The mode parameter determines the default StagePolicy applied to every pipeline stage, while stage_policies allows you to override specific stages with custom pause and checkpoint behaviors.

The Six Built-In Intervention Modes

AutoResearchClaw ships with six predefined intervention modes in the InterventionMode enum. Each mode applies a different default policy through the internal _default_policy_for_mode helper function.

Mode	Behavior	Best For
FULL_AUTO	No pauses; pipeline runs completely unattended.	Batch processing and exploratory runs.
GATE_ONLY	Pauses only at gate stages (major decision points like hypothesis validation).	Reviewing critical junctions without micromanaging.
CHECKPOINT	Creates resumable checkpoints after stages requiring review, but does not pause automatically. Use with --resume for later inspection.	Long experiments running on remote servers.
STEP_BY_STEP	Pauses before and after every stage, forcing manual confirmation.	Debugging sessions or teaching demonstrations.
CO_PILOT	Pauses at critical stages (literature synthesis, hypothesis generation) while keeping routine stages automatic.	Collaborative research requiring human‑LLM dialog.
CUSTOM	All defaults disabled; you must manually configure each stage via stage_policies.	Specialized workflows outside standard presets.

Configuring HITL Intervention Modes

You can configure HITL through declarative YAML files, programmatic Python code, or command‑line flags.

YAML Configuration Setup

Add a hitl section to your run configuration file to define the global mode and stage‑specific overrides:

hitl:
  enabled: true
  mode: co-pilot
  stage_policies:
    3:                    # Stage index from researchclaw/pipeline/stages.py

      pause_before: true
      checkpoint_required: true
    5:
      pause_after: false

Numeric keys in stage_policies correspond to stage indices defined in researchclaw/pipeline/stages.py, allowing you to target specific research phases like literature collection or experiment execution.

Loading Configuration Programmatically

Load your YAML configuration into a HITLConfig object using the from_dict class method:

from pathlib import Path
import yaml
from researchclaw.hitl.config import HITLConfig

# Load from YAML file

config_path = Path("config.yaml")
with open(config_path) as f:
    user_config = yaml.safe_load(f)

# Parse hitl section with validation

cfg = HITLConfig.from_dict(user_config.get("hitl", {}))

The from_dict constructor validates the mode value against the InterventionMode enum and populates missing fields with sensible defaults from the selected preset.

CLI Configuration Options

The CLI entry point in researchclaw/cli.py exposes convenient flags forquick configuration:

# Enable HITL with default FULL_AUTO mode

rc run --hitl

# Specify a particular intervention mode

rc run --hitl-mode co-pilot

# Load full configuration from file

rc run --hitl-config hitl.yaml

These flags are injected into HITLConfig before the pipeline runner initializes the session.

Customizing Stage-Specific Policies

When the built‑in modes lack the granularity you need, override individual stages using StagePolicy objects. Each policy supports:

• pause_before – Pause execution immediately before the stage starts.
• pause_after – Pause after the stage completes to review outputs.
• checkpoint_required – Persist state to disk for later resumption.
• Notification flags – Control UI prompts and escalation alerts.

The pipeline executor in researchclaw/pipeline/runner.py consults the active HITLSession (initialized with your HITLConfig) to determine whether to halt execution or create a checkpoint based on the current stage's policy.

Practical Configuration Examples

Example 1: Fully Automated Execution

Disable HITL entirely for unattended batch processing:

hitl:
  enabled: false

Or simply omit the hitl section from your configuration.

Example 2: Co-Pilot Mode for Critical Stages

Enable collaborative intervention during hypothesis generation and experiment design while letting data collection run automatically:

hitl:
  enabled: true
  mode: co-pilot

Run with:

rc run --hitl-mode co-pilot

The UI will pause during critical stages defined in the CO_PILOT preset, allowing you to edit LLM outputs before proceeding.

Example 3: Custom Per-Stage Overrides

Combine global checkpointing with selective pausing and disabled checkpoints for specific long‑running stages:

hitl:
  enabled: true
  mode: checkpoint
  stage_policies:
    2:                         # PROBLEM_DECOMPOSE stage

      pause_before: true
    5:                         # EXPERIMENT_RUN stage

      checkpoint_required: false

This configuration forces a manual review before problem decomposition while skipping disk‑heavy checkpoints during actual experiment execution.

Example 4: Scripted HITL for Testing

Automate "human" decisions using the ScriptedHITLAdapter for CI/CD or regression testing:

from researchclaw.hitl.session import HITLSession
from researchclaw.hitl.adapters.scripted_adapter import ScriptedHITLAdapter

# Load pre-written responses from JSON

adapter = ScriptedHITLAdapter.from_file("interventions.json")
session = HITLSession(config=cfg, hitl_adapter=adapter, run_dir=Path("./test-run"))

The adapter reads predetermined responses from a JSON map, enabling fully automated testing of HITL workflows without manual intervention.

Summary

• Select a global strategy using the mode parameter in HITLConfig (defined in researchclaw/hitl/config.py) to apply preset behaviors like FULL_AUTO or CO_PILOT.
• Fine‑tune individual stages by adding entries to the stage_policies dictionary, referencing stage indices from researchclaw/pipeline/stages.py.
• Load configurations via YAML files, Python's HITLConfig.from_dict(), or CLI flags --hitl-mode and --hitl-config.
• Automate testing using ScriptedHITLAdapter from researchclaw/hitl/adapters/scripted_adapter.py to simulate human responses programmatically.
• Persist and resume long runs by using CHECKPOINT mode and the --resume CLI flag.

Frequently Asked Questions

What is the default HITL mode if I only pass the --hitl flag without specifying a mode?

When you run rc run --hitl without an explicit mode, AutoResearchClaw defaults to FULL_AUTO mode. This activates the HITL subsystem but keeps the pipeline running without pauses, effectively enabling the infrastructure for potential manual checkpoints while maintaining unattended operation.

How do I find the correct stage index numbers for stage_policies?

Stage indices correspond to the enumeration order defined in researchclaw/pipeline/stages.py. Each research phase (such as LITERATURE_COLLECT or EXPERIMENT_RUN) has an integer index that you use as the key in your stage_policies dictionary. Consult the source file to map specific pipeline phases to their numeric identifiers.

Can I switch intervention modes mid-run or do I need to restart the pipeline?

AutoResearchClaw requires you to define the intervention mode at initialization through HITLSession. To change modes dynamically, you must restart the pipeline with a new configuration. However, if you use CHECKPOINT mode, you can resume a previous run with different HITL settings by specifying a new configuration file when invoking rc run --resume.

What is the difference between pause_before and checkpoint_required in a StagePolicy?

pause_before triggers an interactive pause that blocks execution until human approval is received, making it suitable for review points. checkpoint_required writes the current state to disk without blocking, allowing the pipeline to continue while preserving the ability to resume later. You can combine both to create inspection points that save progress and wait for manual confirmation.

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