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

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. 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.

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 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.

# Retrieve the interaction contract before any execution

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

Sample output structure:

{
  "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.

# 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 module handles evidence summarization and reward overlay attachment.

Dashboard as Read-Only Projection

The Dashboard reads from loopx/status_server.py and presents data defined in 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.

# 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.

# 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 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:

# Validate all contract invariants

python -m pytest tests/

Complete Workflow Example

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

# 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	Core architectural model with actor definitions and state ownership rules
loopx/quota.py	Interaction contract generation via quota should-run
loopx/status.py	Status export format consumed by dashboard
loopx/status_server.py	Optional HTTP server for live dashboard updates
loopx/project_prompt.py	Goal lifecycle management (create, list, close)
loopx/registry.py	Central goal state storage (todos, gates, quota, evidence)
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
• 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 and 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. 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 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. 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.

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