How to Run LoopX Locally: Complete Local-First Setup Guide

Install LoopX with a one-line curl command, connect your project with loopx connect, then use loopx status and core primitives to drive long-running AI agent loops.

LoopX is a local-first, provider-neutral control-plane that lets long-running AI agents persist objectives, gates, todos, evidence, and quota in a durable state kernel. This guide walks through how to run LoopX locally according to the official huangruiteng/loopx source code.

Install LoopX Without Cloning the Repository

LoopX is designed to run without cloning the repository. The installation script downloads the CLI to ~/.local/bin/ and verifies the environment.

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

The doctor command checks for required dependencies and confirms the kernel can initialize. Most errors at this stage involve missing Python 3.10+ or permission issues with ~/.local/bin/.

Connect LoopX to Your Project

Once installed, navigate to any project directory and run:

cd /path/to/your-project
loopx connect          # alias for bootstrap; creates .loopx/registry.json

loopx status           # displays objective, user gate, and next agent todo

The connect command performs three actions:

• Creates a hidden .loopx/ directory containing registry.json for runtime state
• Generates a corresponding goal file under .codex/goals/
• Establishes the public/private boundary documented in docs/public-private-boundary.md — only public-safe artifacts are committed while all runtime state lives under ignored paths (.loopx/, .codex/goals/, .local/)

This local-first architecture ensures your data never leaves your machine unless explicitly configured.

Run LoopX in a Disposable Demo Environment

To experiment without modifying a real repository, use the built-in demo mode:

export PATH="$HOME/.local/bin:$PATH"
loopx demo                # creates a temporary goal under /tmp/loopx-demo

cd /tmp/loopx-demo
loopx status
loopx quota should-run --goal-id demo-goal
loopx history --goal-id demo-goal

The demo creates a fully functional LoopX environment in /tmp/loopx-demo with a synthetic goal ID. This is useful for testing primitives before integrating with production projects.

Core LoopX Primitives for Daily Operation

LoopX operates through a minimal set of kernel primitives implemented in loopx/runtime.py, loopx/quota.py, and loopx/todo.py. These constitute the "core tick" that drives agent loops:

1. Check if an Agent Turn May Run

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

The should-run command in loopx/quota.py evaluates gate conditions and remaining quota slots. Returns exit code 0 if the turn is authorized.

2. Claim the Next Todo

loopx todo claim --goal-id <goal-id> --todo-id <todo-id>

Ownership is recorded in the kernel state. The claim implementation in loopx/todo.py prevents race conditions between multiple agents or hosts.

3. Update Todo After Bounded Turn Completion

loopx todo update --goal-id <goal-id> --todo-id <todo-id> \
  --evidence "Agent produced X" --next-agent-todo "Next step"

This writes evidence and advances the objective state. All mutations pass through loopx/runtime.py for validation and durability guarantees.

4. Add a Pure Run-Only Entry

loopx refresh-state --goal-id <goal-id>

Creates a lightweight heartbeat without spending quota. Useful for health checks and state reconciliation.

5. Spend Quota for Completed Work

loopx quota spend-slot --goal-id <goal-id> --slots 1 \
  --source heartbeat --execute

The spend-slot command in loopx/quota.py decrements available capacity and records provenance for audit trails.

Generate Host-Specific Heartbeat Prompts

For integration with AI coding assistants like Codex, Claude, or OpenCode:

loopx heartbeat-prompt --thin --goal-id <goal-id>

The --thin flag produces a compact context suitable for model context windows. Host-specific adapters are implemented in loopx/worker_bridge.py, which normalizes provider output before the kernel validates and writes back state.

Inspect LoopX System Status

The loopx status command defined in loopx/status.py provides the first-screen view of any LoopX-enabled project:

loopx status

Output includes:

• Current objective from .codex/goals/
• Active user gate (blocking conditions)
• Next agent todo in the queue
• Remaining quota slots for the period

Run this frequently to orient before issuing primitives.

Key Architectural Components

Understanding these components helps debug local LoopX installations:

Component	Source File	Responsibility
Kernel	loopx/runtime.py, loopx/state_*.py	Durable todos, gates, evidence, quota persistence
Quota System	loopx/quota.py	Allocation logic: should-run, spend-slot
Todo Lifecycle	loopx/todo.py	CRUD operations: add, claim, complete, update
Status Display	loopx/status.py	Human-readable project state summaries
Host Bridges	loopx/worker_bridge.py	Adapters for Codex, Claude, Pi, OpenCode
Upgrade Path	loopx/upgrade.py	Self-update mechanisms

All state remains local under .loopx/ and .codex/goals/ — no external API calls required for core operation.

Summary

• Install LoopX with a curl one-liner and verify with loopx doctor
• Connect projects using loopx connect to create local .loopx/ registry and goal files
• Demo safely with loopx demo for temporary, throwaway environments
• Drive loops via five primitives: quota should-run, todo claim, todo update, refresh-state, quota spend-slot
• Inspect state anytime with loopx status defined in loopx/status.py
• Integrate hosts using loopx heartbeat-prompt and loopx/worker_bridge.py adapters

Frequently Asked Questions

Do I need to clone the LoopX repository to run it locally?

No. LoopX is designed for no-clone installation via the official install script. The curl-based installer in scripts/install-from-github.sh downloads only the necessary CLI components to ~/.local/bin/. Cloning is only required if you intend to modify LoopX source code or contribute to huangruiteng/loopx.

Where does LoopX store my data when running locally?

All runtime state lives in three ignored directories: .loopx/ for the registry and internal state, .codex/goals/ for objective definitions, and .local/ for host-specific caches. This architecture, documented in docs/public-private-boundary.md, ensures nothing sensitive is accidentally committed to version control while maintaining full local durability.

What is the minimum Python version required to run LoopX?

LoopX requires Python 3.10 or newer. The loopx doctor command validates your environment and reports specific dependency gaps. Runtime failures typically stem from outdated Python installations or missing write permissions to ~/.local/bin/ and the project-local .loopx/ directory.

How do I run LoopX for multiple projects on the same machine?

Run loopx connect in each project directory. LoopX creates isolated .loopx/ registries per project, with goal files namespaced under .codex/goals/. Use explicit --goal-id flags when issuing primitives to operate on non-default goals, or cd between projects and run commands without flags to use the local registry's active goal.

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