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

> Run LoopX locally with this complete setup guide. Install easily and connect your project to drive long-running AI agent loops efficiently. Get started now.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: how-to-guide
- Published: 2026-08-08

---

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

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

```bash
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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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:

```bash
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`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py), [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py), and [`loopx/todo.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/todo.py). These constitute the "core tick" that drives agent loops:

### 1. Check if an Agent Turn May Run

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

```

The `should-run` command in [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) evaluates gate conditions and remaining quota slots. Returns exit code 0 if the turn is authorized.

### 2. Claim the Next Todo

```bash
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`](https://github.com/huangruiteng/loopx/blob/main/loopx/todo.py) prevents race conditions between multiple agents or hosts.

### 3. Update Todo After Bounded Turn Completion

```bash
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`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py) for validation and durability guarantees.

### 4. Add a Pure Run-Only Entry

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

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

```

The `spend-slot` command in [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/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:

```bash
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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) provides the first-screen view of any LoopX-enabled project:

```bash
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`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py), `loopx/state_*.py` | Durable todos, gates, evidence, quota persistence |
| **Quota System** | [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) | Allocation logic: `should-run`, `spend-slot` |
| **Todo Lifecycle** | [`loopx/todo.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/todo.py) | CRUD operations: `add`, `claim`, `complete`, `update` |
| **Status Display** | [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) | Human-readable project state summaries |
| **Host Bridges** | [`loopx/worker_bridge.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/worker_bridge.py) | Adapters for Codex, Claude, Pi, OpenCode |
| **Upgrade Path** | [`loopx/upgrade.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py)
- **Integrate** hosts using `loopx heartbeat-prompt` and [`loopx/worker_bridge.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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.