# How to Enable LoopX Explore Capability for Experiment Tracking

> Unlock LoopX Explore capability for powerful experiment tracking. Learn how to enable this feature to record exploration history blockers and findings for better project insights.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: how-to-guide
- Published: 2026-08-07

---

**LoopX Explore capability provides a structured, public‑safe evidence graph that records exploration history, blockers, and confirmed findings under `loopx/capabilities/explore/`, enabling systematic experiment tracking through two toggleable sub‑features: Explore Graph and Explore Harness.**

In the `huangruiteng/loopx` repository, the LoopX Explore capability serves as the canonical append‑only log for experimental evidence. It maintains a machine‑readable topology of what the system has explored, why specific paths are blocked, and what hypotheses have been validated, making it essential for audit trails and reproducible research workflows.

## What Is the LoopX Explore Capability?

The **Explore evidence layer** is a structured graph stored under `loopx/capabilities/explore/` that acts as a single source of truth for experiment state. Unlike transient logs, this layer maintains a **canonical append‑only log** of nodes, edges, and findings that survives material refreshes and can be safely exposed to public‑facing dashboards.

According to the source code in [`docs/capabilities/explore/README.md`](https://github.com/huangruiteng/loopx/blob/main/docs/capabilities/explore/README.md), the capability is designed to answer three operational questions:
- What has the system already explored?
- Why is a specific branch blocked?
- Which findings have been confirmed with high confidence?

## Explore Architecture and Sub‑Features

The capability splits into two **independent optional sub‑features** defined in [`loopx/capabilities/explore/activation.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/explore/activation.py):

**Explore Graph** (`explore_graph.enabled`)  
Persists the evidence graph after every material refresh and optionally pushes projections to presentation sinks (e.g., Lark Base). This is the data persistence layer that ensures your experiment history is never lost.

**Explore Harness** (`spawn_policy.explore_harness.enabled`)  
Provides a read‑only planner that builds "todo‑branch‑plans" or "worker‑branch‑plans" for subsequent experiments. It analyzes the current graph topology to suggest the next logical experiments without automatically executing them.

Both gates default to **off**. You can enable only the Graph for passive tracking, or activate both for active experiment planning.

## Architecture Flow for Experiment Tracking

When enabled, the Explore capability follows a five‑stage pipeline as implemented in the activation layer:

1. **Goal registration** – LoopX stores a goal entry in the registry under `goals/<goal-id>/`.

2. **Material refresh** – Running `loopx refresh-state` folds the canonical Explore log into a projection named `loopx_explore_result_projection_v0`.

3. **Graph activation** – If `explore_graph.enabled` is true, the function `sync_explore_graph_after_material_refresh` writes the projection to configured sinks and records a delivery post‑condition.

4. **Harness planning** – If `spawn_policy.explore_harness.enabled` is true, the planner reads the projection and emits read‑only plans containing node references, confidence scores, and resource‑capacity hints. **Note:** This step does not launch workers.

5. **Presentation** – The `loopx.extensions.lark.presentation` package renders the graph into Lark boards or Mermaid diagrams, with board styles controlled by [`explore_visual_styles.py`](https://github.com/huangruiteng/loopx/blob/main/explore_visual_styles.py).

## How to Enable LoopX Explore Capability

Enable the capability using the `loopx configure-goal` CLI or programmatically via the registry API.

### Method 1: CLI Configuration

Enable the Explore Graph (and optionally the Harness) for a specific goal:

```bash
loopx configure-goal --goal-id my-goal \
  --explore-graph-enabled \
  --no-explore-harness-enabled \
  --execute

```

This writes the following structure to your registry:

```yaml
explore_graph:
  enabled: true
spawn_policy:
  explore_harness:
    enabled: false

```

### Method 2: Programmatic Configuration

For automation pipelines, modify the goal registry directly:

```python
from pathlib import Path
from loopx.agent_registry import load_goal_from_registry, save_goal_to_registry

registry = Path("/path/to/registry")
goal_id = "my-goal"

goal = load_goal_from_registry(registry, goal_id) or {}
goal.setdefault("explore_graph", {})["enabled"] = True
goal.setdefault("spawn_policy", {}).setdefault("explore_harness", {})["enabled"] = False

save_goal_to_registry(registry, goal_id, goal)

```

### Trigger the First Graph Generation

After configuration, generate your initial evidence graph:

```bash
loopx refresh-state --goal-id my-goal --execute

```

This triggers `sync_explore_graph_after_material_refresh`, which appends new events to `goals/my-goal/explore-result-log.jsonl`.

## Configuring Presentation Sinks

To visualize the graph in Lark (Feishu), configure a presentation sink after enabling the Graph:

```bash
loopx explore feishu-visual-configure \
  --view-role canonical \
  --projection-mode canonical_full \
  --board-style auto_flow \
  --execute

```

The `board-style` parameter accepts values defined in [`loopx/extensions/lark/presentation/explore_visual_styles.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/extensions/lark/presentation/explore_visual_styles.py), including `auto_flow` for automatic layout or `semantic_lane_columns` for lane‑based grouping. This creates a local config at [`.loopx/lark-explore.json`](https://github.com/huangruiteng/loopx/blob/main/.loopx/lark-explore.json) and registers the board with Lark.

## Using the Explore Harness for Planning

Once your graph is populated, query the Harness for experiment suggestions:

```bash
loopx explore todo-branch-plan \
  --goal-id my-goal \
  --width 3

```

The output lists candidate todo IDs, confidence scores, and resource‑lane hints. The Harness operates as a **read‑only planner**; it suggests experiments but does not claim or launch workers. You must manually claim suggested todos through your standard execution pipeline.

Alternatively, request a worker‑branch plan for resource‑specific allocations:

```bash
loopx explore worker-branch-plan --goal-id my-goal --width 5

```

## Summary

- **LoopX Explore capability** maintains a canonical evidence graph at `loopx/capabilities/explore/` for audit‑safe experiment tracking.
- **Explore Graph** (`explore_graph.enabled`) handles persistence and optional sink integration via `sync_explore_graph_after_material_refresh`.
- **Explore Harness** (`spawn_policy.explore_harness.enabled`) provides read‑only planning without automatic execution.
- Enable the capability via `loopx configure-goal` or the registry API, then trigger updates with `loopx refresh-state`.
- Visualize results using Lark integration configured through `loopx explore feishu-visual-configure`.

## Frequently Asked Questions

### What is the difference between Explore Graph and Explore Harness?

**Explore Graph** is the data persistence layer that records the evidence topology after each material refresh, while **Explore Harness** is a planning layer that reads that topology to suggest next experiments. You can enable the Graph alone for passive tracking, or combine both for active experiment recommendation.

### Where is the Explore evidence data physically stored?

The canonical log is stored in your registry under `goals/<goal-id>/explore-result-log.jsonl`. This append‑only JSONL file is the source of truth, with projections generated dynamically during `loopx refresh-state` operations.

### Does enabling Explore Harness automatically execute experiments?

No. The Harness operates as a read‑only planner. When you run `loopx explore todo-branch-plan`, it emits candidate branches with confidence scores and resource hints, but **does not** claim todos or launch workers. Execution remains a manual or separately automated step.

### How do I customize the visual layout of the Explore graph in Lark?

Board styling is controlled through the `--board-style` parameter in `loopx explore feishu-visual-configure`. Valid options include `auto_flow` for automatic node positioning and `semantic_lane_columns` for column‑based grouping, defined in [`loopx/extensions/lark/presentation/explore_visual_styles.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/extensions/lark/presentation/explore_visual_styles.py).