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

> Discover LoopX configuration. Learn about the .loopx directory structure, registry.json, and optional config files for project settings. Understand LoopX setup.

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

---

**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`](https://github.com/huangruiteng/loopx/blob/main/.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`](https://github.com/huangruiteng/loopx/blob/main/settings.yaml) or [`config.json`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/.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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/.loopx/config/lark/event-inbox.json), while reward-memory features use paths defined in [`docs/reference/protocols/reward-memory-architecture-v0.md`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/.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`](https://github.com/huangruiteng/loopx/blob/main/loopx/configure_goal.py).

### Initializing a Project

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

```bash
loopx init .

```

This creates an empty registry at [`.loopx/registry.json`](https://github.com/huangruiteng/loopx/blob/main/.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:

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

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

```

This command updates [`.loopx/registry.json`](https://github.com/huangruiteng/loopx/blob/main/.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:

```bash
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`](https://github.com/huangruiteng/loopx/blob/main/docs/capabilities/lark-event-inbox.md) and records the binding in the registry.

## Runtime Loading Process

During execution, [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py) loads the configuration by first reading [`.loopx/registry.json`](https://github.com/huangruiteng/loopx/blob/main/.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`](https://github.com/huangruiteng/loopx/blob/main/.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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/.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`](https://github.com/huangruiteng/loopx/blob/main/.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`](https://github.com/huangruiteng/loopx/blob/main/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.