# LoopX Best Practices: A Complete Guide to Local-First AI Agent Control Planes

> Master LoopX best practices for local-first AI agent control. Learn to manage goals as state, use explicit contracts, and structure feedback for efficient AI execution.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: best-practices
- Published: 2026-08-08

---

**LoopX best practices center on treating goals as durable state objects, driving every execution turn through explicit interaction contracts, and capturing all human feedback as structured overlays rather than chat history.**

LoopX is a local-first, provider-neutral control plane that separates durable state from runtime execution for long-running AI agents. Understanding how to use LoopX effectively requires adopting its state interaction model, which makes agent loops robust to interruptions, auditable, and safe for production use.

## Core Architecture: The State Interaction Model

LoopX organizes all actors around a strict state ownership model documented in [`docs/state-interaction-model.md`](https://github.com/huangruiteng/loopx/blob/main/docs/state-interaction-model.md). The four primary actors—**Goal**, **Codex App Executor**, **User**, and **Dashboard**—each have defined read, write, and own permissions.

Every new capability must explicitly name the state it touches. This prevents accidental cross-contamination and makes dependencies visible in code review.

### Goal-Owned Durable State

A **Goal** is the central durable work object in LoopX. Unlike transient chat threads, goals persist across restarts, thread boundaries, and agent hand-offs. According to the interaction model, a goal owns:

- Objective and success criteria
- Gates (approval checkpoints)
- Todos (execution plan)
- Evidence (observable outcomes)
- Quota (resource budgets)
- Hand-off conditions

Keeping long-term information in the goal rather than in LLM context windows eliminates context loss and makes every state change observable in [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py).

## Driving Execution Through Interaction Contracts

The `loopx quota should-run` command produces a machine-readable **interaction contract** that the executor must obey. This contract is retrieved from [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) and contains the precise CLI actions permitted for the next turn.

**Never execute actions without first retrieving the quota contract.** This invariant guarantees that agents act only under explicit, signed-off plans.

```bash

# Retrieve the interaction contract before any execution

loopx --format json quota should-run --goal-id <goal-id>

```

Sample output structure:

```json
{
  "interaction_contract": {
    "cli_channel": {
      "next_cli_actions": [
        "loopx run-model --model revenue-forecast",
        "loopx generate-report --format pdf"
      ]
    }
  }
}

```

## Human-in-the-Loop Gates and Structured Feedback

The user actor holds authority over actions affecting production resources, privacy, or safety. LoopX best practices require recording human feedback as a **`human_reward` overlay** rather than buried in free-form chat.

This structured approach makes reward signals visible to downstream controllers and enables systematic reward model training.

```bash

# Add structured human reward after reviewing executor output

loopx reward add \
    --goal-id $GOAL_ID \
    --run-id $RUN_ID \
    --score 1.0 \
    --comment "Forecast looks accurate, keep this approach."

```

The [`loopx/summary_all.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/summary_all.py) module handles evidence summarization and reward overlay attachment.

## Dashboard as Read-Only Projection

The **Dashboard** reads from [`loopx/status_server.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status_server.py) and presents data defined in [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py). It never writes directly to goal state unless an explicit capability grants that permission.

This read-only design ensures the dashboard cannot accidentally corrupt durable state. Operators use the dashboard to inspect todos, quota consumption, and evidence without risk.

```bash

# Inspect goal state via CLI (dashboard consumes same data)

loopx status --goal-id $(loopx project_prompt list --json | jq -r '.[0].id')

```

## Local-First Installation with Zero Dependencies

LoopX installs via a single script with **no external Python dependencies** beyond the standard library. This reproducibility makes LoopX suitable for locked-down environments.

```bash

# Install LoopX (no clone or virtualenv required)

curl -fsSL https://raw.githubusercontent.com/huangruiteng/loopx/main/scripts/install-from-github.sh | bash
export PATH="$HOME/.local/bin:$PATH"

```

The installation process is documented in [`README.md`](https://github.com/huangruiteng/loopx/blob/main/README.md) at the repository root.

## Extensible Capability System

New functionality must be expressed as **capabilities** that register contracts in `docs/capabilities/` rather than ad-hoc commands. This keeps the core control plane stable while allowing optional providers to plug in.

The *Issue-Fix* capability in `docs/capabilities/` demonstrates the required structure: a capability contract declaring state ownership, interaction protocol, and quota requirements.

## Self-Repair and Regression Safety

LoopX includes a self-repair skill in `skills/loopx-self-repair/` that detects and fixes known failure modes. The `tests/` directory contains regression suites validating contract invariants.

Run the full test suite after any modification to ensure interaction contract integrity:

```bash

# Validate all contract invariants

python -m pytest tests/

```

## Complete Workflow Example

This end-to-end example demonstrates LoopX best practices in sequence:

```bash

# 1. Install and configure

curl -fsSL https://raw.githubusercontent.com/huangruiteng/loopx/main/scripts/install-from-github.sh | bash
export PATH="$HOME/.local/bin:$PATH"

# 2. Create a durable goal

loopx project_prompt create \
    --title "Investigate Quarterly Revenue Spike" \
    --description "Analyze data, run models, and produce a report."

# 3. Capture goal ID

GOAL_ID=$(loopx project_prompt list --json | jq -r '.[0].id')

# 4. Inspect initial state

loopx status --goal-id $GOAL_ID

# 5. Retrieve interaction contract and execute allowed actions

for cmd in $(loopx --format json quota should-run --goal-id $GOAL_ID | \
             jq -r '.interaction_contract.cli_channel.next_cli_actions[]'); do
    echo "Executing: $cmd"
    eval $cmd
done

# 6. Record execution evidence and human feedback

RUN_ID=$(loopx run-model --model revenue-forecast --json | jq -r '.run_id')
loopx summary_all --goal-id $GOAL_ID
loopx reward add --goal-id $GOAL_ID --run-id $RUN_ID --score 1.0 \
    --comment "Forecast accuracy validated against actuals."

# 7. Iterate through additional turns as needed...

# 8. Close the goal when complete

loopx project_prompt close --goal-id $GOAL_ID

```

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`docs/state-interaction-model.md`](https://github.com/huangruiteng/loopx/blob/main/docs/state-interaction-model.md) | Core architectural model with actor definitions and state ownership rules |
| [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) | Interaction contract generation via `quota should-run` |
| [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) | Status export format consumed by dashboard |
| [`loopx/status_server.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status_server.py) | Optional HTTP server for live dashboard updates |
| [`loopx/project_prompt.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/project_prompt.py) | Goal lifecycle management (create, list, close) |
| [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py) | Central goal state storage (todos, gates, quota, evidence) |
| [`loopx/summary_all.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/summary_all.py) | Evidence summarization and reward overlay attachment |
| `skills/loopx-self-repair/` | Automated detection and repair of contract violations |
| `tests/` | Regression suite for contract invariant validation |

## Summary

- **Treat goals as durable state objects** that persist across all interruptions and hand-offs, with all long-term information stored in [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py)
- **Drive every execution turn through explicit quota contracts** retrieved via `loopx quota should-run`, never executing actions without prior authorization
- **Capture human feedback as structured `human_reward` overlays** rather than unstructured chat, making signals consumable by downstream systems
- **Maintain dashboard as read-only projection** via [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) and [`loopx/status_server.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status_server.py), preventing accidental state corruption
- **Install locally with zero dependencies** using the official install script for reproducible, locked-down deployments
- **Extend via registered capabilities** in `docs/capabilities/` rather than ad-hoc commands, preserving core control plane stability
- **Validate with self-repair and regression tests** from `skills/loopx-self-repair/` and `tests/` to maintain contract invariants

## Frequently Asked Questions

### How does LoopX prevent context loss across agent restarts?

LoopX persists all durable state in the **Goal** object managed by [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py). Unlike chat-based systems that lose context when threads expire or services restart, goals retain objective, todos, evidence, and quota across any interruption. The executor retrieves the current goal state via `loopx status` and receives a fresh interaction contract via `loopx quota should-run` on every turn.

### What is the interaction contract and why is it required?

The **interaction contract** is a machine-readable document produced by [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) that specifies exactly which CLI actions the executor may perform in the next turn. It is required to ensure agents never act without explicit, auditable authorization. The contract includes resource quotas, action whitelists, and gating conditions that enforce human oversight where configured.

### How should human feedback be recorded in LoopX?

Human feedback must be recorded as a **structured `human_reward` overlay** using `loopx reward add` with explicit `--score` and `--comment` parameters. This attaches the feedback to a specific run within the goal's evidence trail. Free-form chat messages are discouraged because they are invisible to downstream controllers and reward model training pipelines.

### Can the LoopX dashboard modify goal state?

No. The dashboard is explicitly designed as a **read-only projection** that consumes data from [`loopx/status_server.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status_server.py). It renders todos, quota status, and evidence for operator visibility but cannot write to goal state unless a dedicated capability grants that permission. This separation prevents accidental state corruption through UI interactions.