How to Configure LoopX: CLI Commands, Environment Variables, and Goal-Level Settings

LoopX configuration is performed per-goal using the loopx configure-goal CLI command with --preview to inspect settings and --execute to persist changes, while environment variables like LOOPX_RUNTIME_ROOT control runtime behavior.

Configuring LoopX from the huangruiteng/loopx repository involves managing durable, observable settings for long-running AI work through a combination of CLI flags and environment variables. All configuration is stored in the project-local .loopx/registry.json file and is versioned with the goal ID to ensure repeatable runs and safe rollbacks.

Connecting and Initializing a Project

Before configuring LoopX, you must connect the project to create the hidden .loopx/ directory and initialize a goal. The loopx connect command sets up the necessary state storage, while loopx start-goal creates the top-level objective that owns all subsequent configuration.

# Connect a fresh repository

cd /path/to/your-project
loopx connect

# Create a new goal (interactive)

loopx start-goal --guided --project . --goal-text "Build a multilingual chatbot"

These commands establish the .loopx/ directory structure and the goal context required by the configuration system implemented in loopx/configure_goal.py.

Inspecting Current Configuration

Always preview changes before applying them. The --preview flag shows the full catalog of settings for a specific goal without mutating the state stored in .loopx/registry.json.

loopx configure-goal --goal-id my-goal --preview

This safe-read operation queries the configuration catalog defined in the Configure-Goal API contract (docs/status-data-contract.md) and displays the current values for quotas, capabilities, and agent profiles.

Applying Configuration Changes

To persist modifications, supply the same command with --execute or simply omit --preview. This updates the goal-level catalog and writes changes to loopx/registry.py’s managed persistence layer.

# Enable the Explore capability

loopx configure-goal --goal-id my-goal --enable-explore --execute

# Disable a capability you no longer need

loopx configure-goal --goal-id my-goal --disable-explore --execute

All changes are atomic and versioned with the goal ID, allowing you to track the evolution of your LoopX setup over time.

Common Configuration Options

Compute Quotas

Control resource consumption per turn using the --quota-compute flag. This limits how many slots a goal may spend during each execution cycle.

loopx configure-goal --goal-id my-goal --quota-compute 5 --execute

Spawn Policies and Capabilities

Enable optional capabilities such as Explore or Auto-Research using boolean flags. These policies determine which agents LoopX can spawn and what behaviors are permitted.

# Enable auto-research (adds scheduler hints and quota adjustments)

loopx configure-goal --goal-id my-goal --enable-auto-research --execute

Capability-specific options follow the pattern --<capability>-<option>, such as --issue-fix-policy for the loopx issue-fix command.

Agent Profiles

Map registered peers to role-specific parameters using the --profile flag. This creates a mapping between agent IDs and their configuration profiles within the goal context.

loopx configure-goal --goal-id my-goal --profile agent-123=researcher --execute

Environment Variable Overrides

For advanced scenarios, LoopX reads several environment variables at runtime:

• LOOPX_RUNTIME_ROOT – Directory where LoopX writes its state (defaults to .loopx/)
• LOOPX_REGISTRY – Path to a JSON file describing the project-wide registry of agents and capabilities
• LOOPX_PROMOTE_DEFAULT – Set to 1 to enable the installer to promote newly built releases

These variables are processed by the installer scripts (scripts/install-from-github.sh) and runtime bridges before the CLI commands execute.

Validating Your Configuration

After applying changes, verify the installation health and goal state using diagnostic commands:

# Verify the whole installation

loopx doctor

# Show active goal state and configuration

loopx status

Both commands are safe-read operations that surface misconfigurations without modifying state, as documented in the docs/guides/getting-started.md tutorial.

Using Presets for Quick Setup

LoopX ships with read-only presets that bundle sensible configuration defaults. These presets provide quick ways to enable complete capability suites without hand-editing the catalog.

# List available presets

loopx preset list

# View details of the daily-triage preset

loopx preset show daily-triage

# Apply the preset to your goal

loopx preset apply daily-triage --goal-id my-goal

Common presets include daily-triage and auto-research, defined in docs/presets/daily-triage.md and referenced in docs/guides/auto-research-command-path.md.

Summary

• Initialize with loopx connect and loopx start-goal before configuring any settings.
• Preview changes using --preview and persist them with --execute to update .loopx/registry.json.
• Manage resources via --quota-compute, capabilities via --enable-<feature>, and agents via --profile.
• Override runtime locations using LOOPX_RUNTIME_ROOT and LOOPX_REGISTRY environment variables.
• Validate configurations with loopx doctor and loopx status to ensure healthy operation.
• Accelerate setup using built-in presets like daily-triage via loopx preset apply.

Frequently Asked Questions

What is the difference between --preview and --execute in LoopX configuration?

The --preview flag performs a dry-run that displays the current configuration catalog from docs/status-data-contract.md without writing to .loopx/registry.json, while --execute (or omitting --preview) persists the modifications to the goal-level state.

Where does LoopX store configuration files?

LoopX stores all configuration in a project-local .loopx/ directory, specifically within .loopx/registry.json, which is managed by loopx/registry.py and versioned with the goal ID to support rollbacks and repeatable runs.

How do I enable the Explore capability in LoopX?

Enable the Explore capability by running loopx configure-goal --goal-id <your-goal> --enable-explore --execute, which updates the spawn policy in the configuration catalog to allow the Explore agent to run within that goal context.

Can I use environment variables instead of CLI flags for LoopX configuration?

Yes, you can set LOOPX_RUNTIME_ROOT to change the state directory, LOOPX_REGISTRY to specify a custom registry JSON file, and LOOPX_PROMOTE_DEFAULT to control release promotion, though goal-specific settings like quotas and capabilities still require the configure-goal CLI command.

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