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

> Learn LoopX basic usage examples and master AI agent control planes. This quick start guide covers connect, start-goal, claim/update, and review-packet workflows for durable AI objectives.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: getting-started
- Published: 2026-08-14

---

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

```bash

# 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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/.loopx/registry.json) if missing.

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

```bash
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`](https://github.com/huangruiteng/loopx/blob/main/loopx/todo.py) and [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py).

```bash

# 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`](https://github.com/huangruiteng/loopx/blob/main/loopx/todos.py) implement claim/update/list operations with atomic ownership checks. The `quota` module in [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/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.

```bash

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

```bash
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`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli.py) | Core command-line entry point parsing all `loopx …` commands |
| [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) | Implements `loopx status` and `loopx doctor` diagnostics |
| [`loopx/todos.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/todos.py) | Logic for `todo claim`, `todo update`, and listing operations |
| [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) | Quota allocation and `should-run` decision contract |
| [`docs/architecture.md`](https://github.com/huangruiteng/loopx/blob/main/docs/architecture.md) | Explains the kernel's lifetime-goal invariant |
| [`docs/state-interaction-model.md`](https://github.com/huangruiteng/loopx/blob/main/docs/state-interaction-model.md) | Details interaction contracts between agents, capabilities, and kernel |
| [`examples/worker-bridge-install-contract-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/examples/worker-bridge-install-contract-smoke.py) | Minimal runnable worker bridge integration example |

The **State Interaction Model** documented in [`docs/state-interaction-model.md`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/.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`](https://github.com/huangruiteng/loopx/blob/main/loopx/todos.py) and [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py).
- **Review state** with `loopx review-packet` and `loopx history` for human oversight.
- **Reference source** in [`loopx/cli.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/.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`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) and [`loopx/todos.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/todos.py). Presets, gate logic, and evidence storage require no network access.