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

> Learn to configure HITL intervention modes in AutoResearchClaw. Master pipeline pauses for human feedback during research stages using HITLConfig and stage_policies.

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

---

**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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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:

```yaml
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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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:

```python
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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/researchclaw/cli.py) exposes convenient flags forquick configuration:

```bash

# 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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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:

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

```yaml
hitl:
  enabled: true
  mode: co-pilot

```

Run with:

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

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

```python
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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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`](https://github.com/aiming-lab/AutoResearchClaw/blob/main/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.