LoopX Basic Usage Examples: A Quick Start Guide for AI Agent Control-Planes

LoopX is a provider-neutral, stateful control-plane that helps long-running AI agents keep objectives, gates, todos, evidence, and quota durable across turns, exposing a CLI workflow of connect → start-goal → claim/update → review-packet.

This guide walks through the essential LoopX basic usage examples, from installation to running your first multi-turn agent loop. LoopX operates as a tiny kernel that stores a goal (your objective) together with typed todos, gates, quota, and evidence. Agent runtimes like Codex App, Claude Code, or custom runners execute bounded turns, write back evidence, and LoopX decides whether to continue, wait for human judgment, or invoke a safe fallback—without taking over the runtime itself.

Installation and First Steps

LoopX installs without external Python dependencies. Run the official install script and verify with loopx doctor.

# Install LoopX (no clone needed)

curl -fsSL https://huangruiteng.github.io/loopx/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"

# Sanity-check the installation

loopx doctor

The loopx doctor command validates your environment and reports any missing configuration. This command is implemented in loopx/status.py, which also powers the loopx status diagnostic tool.

Connecting a Project and Checking State

Before running goals, connect LoopX to a project directory. This creates .loopx/registry.json if missing.

cd /path/to/your/project
loopx connect          # initializes the project registry

loopx status           # shows current objective, gates, and next todo

The loopx status command reads the active goal, displays pending gates requiring human approval, and lists the next available todo. For deeper diagnostics, loopx doctor validates filesystem state, registry integrity, and CLI compatibility.

Starting a Long-Running Goal

Use loopx start-goal to create a new objective. The --guided flag launches an interactive wizard.

loopx start-goal --guided --project . \
    --goal-text "Improve model accuracy on dataset X"

This initializes the kernel's lifetime-goal invariant: a compact, inspectable run-history that persists across process restarts. The goal text becomes the durable objective that all subsequent turns reference.

Running a Turn: The Core LoopX Workflow

A single turn follows a strict contract: claim → work → update → spend. This pattern appears in loopx/todo.py and loopx/quota.py.

# 1. Claim ownership of the next slice

loopx todo claim

# 2. Agent performs work (via $loopx <task> or /skills in your runtime)

# 3. Report completion or partial progress

loopx todo update

# 4. Record consumed resources

loopx quota spend-slot

The todo subcommands in loopx/todos.py implement claim/update/list operations with atomic ownership checks. The quota module in loopx/quota.py enforces the should-run decision contract—if quota is exhausted or gates are blocked, the turn halts before work begins.

Inspecting Loop State and History

After each turn, inspect decisions and evidence with review commands.

# Compact view of decisions, evidence, and gates

loopx review-packet

# Full run-history for a specific goal

loopx history --goal-id <id>

The review-packet output summarizes: gate evaluations (pass/block), evidence written, quota consumed, and the next recommended action. This compact format is designed for human-in-the-loop oversight without overwhelming detail.

Using Preset Shortcuts

LoopX includes optional presets for common workflows. List and inspect them:

loopx preset list
loopx preset show daily-triage

Presets bundle preconfigured gates, todo templates, and quota allocations. They live in the registry and can be referenced by name when starting goals.

Architecture and Source Code Reference

Understanding LoopX basic usage examples requires knowing where implementation lives. Key files in huangruiteng/loopx:

File	Purpose
loopx/cli.py	Core command-line entry point parsing all loopx … commands
loopx/status.py	Implements loopx status and loopx doctor diagnostics
loopx/todos.py	Logic for todo claim, todo update, and listing operations
loopx/quota.py	Quota allocation and should-run decision contract
docs/architecture.md	Explains the kernel's lifetime-goal invariant
docs/state-interaction-model.md	Details interaction contracts between agents, capabilities, and kernel
examples/worker-bridge-install-contract-smoke.py	Minimal runnable worker bridge integration example

The State Interaction Model documented in docs/state-interaction-model.md formalizes the write-back flow: agents produce evidence, capabilities validate constraints, and the kernel updates todos and quota atomically.

Summary

• Install LoopX via curl with zero Python dependencies, verify with loopx doctor.
• Connect projects with loopx connect to initialize .loopx/registry.json.
• Start goals using loopx start-goal --guided to establish durable objectives.
• Run turns through the claim → update → spend-slot cycle enforced by loopx/todos.py and loopx/quota.py.
• Review state with loopx review-packet and loopx history for human oversight.
• Reference source in loopx/cli.py and supporting modules for implementation details.

Frequently Asked Questions

What makes LoopX "provider-neutral"?

LoopX does not embed any specific LLM client or agent runtime. It exposes a control-plane contract that Codex App, Claude Code, or custom runners can all implement. The kernel stores state; your runner chooses how to execute.

How does LoopX protect human-in-the-loop gates?

Gates are typed checkpoints defined in the goal. Before each turn, loopx/quota.py evaluates gate conditions. If a gate requires human approval and none is recorded, should-run returns false and the loop pauses. Agents cannot override gates—only write evidence that might satisfy them.

Where is LoopX state stored?

Project-local state lives in .loopx/registry.json and companion files. This keeps goals, todos, and run-history visible on disk without requiring a remote service. The architecture supports future pluggable backends while defaulting to filesystem durability.

Can I run LoopX entirely offline?

Yes. After installation, all core commands operate locally. The control-plane validates contracts using local state in loopx/quota.py and loopx/todos.py. Presets, gate logic, and evidence storage require no network access.

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