Is There a Configuration File for LoopX? Understanding the .loopx Directory Structure

LoopX does not rely on a single monolithic configuration file; instead, it stores all project-specific settings in a hidden .loopx/ directory at the project root, using .loopx/registry.json as the primary registry and optional JSON files under .loopx/config/ for capability-specific settings.

Unlike traditional frameworks that use a centralized settings.yaml or config.json, the huangruiteng/loopx repository implements a distributed configuration model. All project metadata lives within a git-ignored .loopx/ folder, enabling safe local state management without risking secret leakage. This article explains the structure of the LoopX configuration file system and how the runtime loads these settings.

The .loopx Directory Structure

The LoopX configuration file approach centers on a hidden directory created at project initialization. According to the source code, this directory contains three primary categories of data.

Project Registry

The authoritative source of truth resides in .loopx/registry.json. This file maintains the complete list of goals, agents, and bindings registered within the project. The runtime reads this file on every startup to understand the project topology, as specified in docs/status-data-contract.md.

Capability-Specific Settings

Optional features store their configurations in isolated JSON files under .loopx/config/<capability>/. For example, the Lark inbox integration uses .loopx/config/lark/event-inbox.json, while reward-memory features use paths defined in docs/reference/protocols/reward-memory-architecture-v0.md. These files remain separate from the core registry to maintain clean separation between mandatory and optional functionality.

Runtime State

Transient data including domain state, quota information, and archived project states live in subdirectories like .loopx/domain-state/ and .loopx/runtime/. The control-plane uses these files for quota management, quota-spend tracking, and replay functionality, as illustrated in docs/product/domain-capability-packs.md.

Core Configuration System

LoopX generates its configuration catalog dynamically rather than using static files.

The Configuration Catalog

The loopx/configuration_catalog.py module builds an on-demand catalog that maps high-level feature requests to concrete CLI flags. This catalog validates mutation policies before any changes are written to disk, enforcing the preview-then-apply workflow that prevents accidental misconfigurations.

The Registry Schema

The .loopx/registry.json file follows a strict JSON schema. It records every goal ID and its associated feature bindings. All runtime commands, including loopx status and loopx quota should-run, read this file first to determine available capabilities before executing operations.

Managing Configuration Changes

All modifications to LoopX configuration files occur through the loopx configure-goal CLI command implemented in loopx/configure_goal.py.

Initializing a Project

Create the .loopx/ directory structure using the init command:

loopx init .

This creates an empty registry at .loopx/registry.json and configures git to ignore the entire .loopx/ directory, preventing accidental commits of local state or secrets.

Preview and Apply Workflow

Before committing changes, users can preview the exact modifications that would be written to the configuration files:

loopx configure-goal --goal-id my-goal \
    --multi-subagent-feature enabled \
    --max-children 4 \
    --allowed-domain sales \
    --preview

To apply the configuration, replace --preview with --execute:

loopx configure-goal --goal-id my-goal \
    --multi-subagent-feature enabled \
    --max-children 4 \
    --allowed-domain sales \
    --execute

This command updates .loopx/registry.json to mark the feature as enabled and writes the capability-specific settings to the appropriate files under .loopx/config/.

Enabling Optional Capabilities

For features like the Lark event inbox:

loopx configure-goal --goal-id my-goal \
    --lark-event-inbox-config .loopx/config/lark/event-inbox.json \
    --execute

The command creates the JSON configuration file following the schema in docs/capabilities/lark-event-inbox.md and records the binding in the registry.

Runtime Loading Process

During execution, loopx/runtime.py loads the configuration by first reading .loopx/registry.json, then validating any present capability configs against the mutation policy from the catalog. The runtime injects these feature flags into the control-plane, enabling quota enforcement and domain restrictions based on the active configuration.

Summary

• LoopX uses a .loopx/ directory rather than a single configuration file, with .loopx/registry.json serving as the primary project registry.
• Optional capabilities store settings in .loopx/config/<capability>/*.json files, keeping core and optional configurations separated and maintainable.
• The loopx/configuration_catalog.py module generates the configuration catalog dynamically, enabling safe preview-then-apply workflows for all changes.
• All modifications are managed via the loopx configure-goal CLI (implemented in loopx/configure_goal.py), which updates both the registry and capability-specific files atomically.
• The entire .loopx/ directory is git-ignored by default, preventing secrets and local runtime state from entering version control.

Frequently Asked Questions

Does LoopX use a single configuration file like config.yaml?

No. LoopX distributes configuration across multiple files within the .loopx/ directory. The primary file is .loopx/registry.json, while optional capabilities create their own JSON files under .loopx/config/, allowing modular feature management.

Where does LoopX store project metadata and goal definitions?

Project metadata, including all goals, agents, and bindings, is stored in .loopx/registry.json. The runtime reads this file on startup to build the project topology, as documented in the status data contract.

How do I safely enable optional features in LoopX?

Use the loopx configure-goal command with the --preview flag first to see the planned changes, then --execute to apply them. This CLI tool, implemented in loopx/configure_goal.py, safely updates both the registry and creates the necessary JSON configuration files under .loopx/config/.

Is the .loopx directory safe to commit to git?

No. The .loopx/ directory is git-ignored by default as specified in the getting started guide, and should never be committed. It contains local runtime state, temporary receipts, and potentially sensitive capability configurations that must remain local to the machine.

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