# How to Install LoopX: Complete Setup Guide for the Stateful Control-Plane

> Easily install LoopX with our complete setup guide. Follow simple commands to get the stateful control-plane running and verify your installation with loopx doctor.

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

---

**Run `curl -fsSL https://raw.githubusercontent.com/huangruiteng/loopx/main/scripts/install-from-github.sh | bash` to install the LoopX CLI, then verify with `loopx doctor`.**

LoopX is a **provider-neutral, stateful control-plane** that lets long-running AI agents keep their objectives, gates, todos, evidence, and quota durable across turns. To install LoopX, you can use either the no-clone installer for stable releases or the clone-based workflow for development. This guide covers both methods using the actual installation scripts from the `huangruiteng/loopx` repository.

## Prerequisites

Before you install LoopX, ensure your system meets the following requirements:

- **Python 3.11+** — The runtime requirement declared in [`pyproject.toml`](https://github.com/huangruiteng/loopx/blob/main/pyproject.toml)
- **Bash** — Required for the installer scripts
- **~/.local/bin on PATH** — The default location for the CLI wrapper

Both installation paths perform a health check at the end that validates Python availability, PATH configuration, and global skill installation.

## Method 1: No-Clone Installation (Recommended)

The **no-clone installer** is the fastest way to install LoopX for ordinary users who want the CLI and built-in skills without downloading the full repository.

### What the Installer Does

When you run [`scripts/install-from-github.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-from-github.sh), it performs the following actions:

1. Downloads a GitHub release archive (static tarball)
2. Extracts the snapshot under `~/.local/share/loopx/releases/`
3. Installs the `loopx` wrapper in `~/.local/bin`
4. Adds a man-page and global Codex skills under `~/.codex/skills/`
5. Runs `loopx doctor` to validate the installation

### Installation Command

```bash
curl -fsSL https://raw.githubusercontent.com/huangruiteng/loopx/main/scripts/install-from-github.sh | bash
export PATH="$HOME/.local/bin:$PATH"

```

### Verify the Installation

After installation, run the built-in health check:

```bash
loopx doctor

```

This command validates that:
- Python 3.11+ is available
- The CLI wrapper is on your PATH
- Global skills are installed under `~/.codex/skills`
- The LoopX state kernel responds correctly

## Method 2: Clone-Based Installation (For Contributors)

If you need to develop LoopX itself or test the live canary wrapper, use the **clone-based installer**.

### Setup Steps

```bash
git clone https://github.com/huangruiteng/loopx ~/loopx
~/loopx/scripts/install-local.sh

```

### What This Creates

The [`scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-local.sh) script:
- Creates a **canary wrapper** (`loopx-canary`) in `~/.local/bin` that points to your checkout
- Updates the man-page and global skills
- Allows you to test changes without disturbing the stable release

### Verify the Canary Installation

```bash
loopx-canary doctor

```

This runs the health check against your live checkout rather than the stable release.

## Connect Your First Project

Once LoopX is installed, you need to connect it to a project to activate the state kernel.

### Initialize a New Project

```bash
cd /path/to/your-project
loopx bootstrap          # Initialize LoopX state for this project

```

Or connect to an existing LoopX project:

```bash
loopx connect

```

### Understanding the State Directory

When you connect a project, LoopX creates a hidden `.loopx/` directory in your project root. This directory stores:
- Durable goal state
- Todos and evidence
- Quota metadata

**Important:** This state is never committed to your repository according to the public/private boundary rules documented in the source.

### Check Project Status

```bash
loopx status             # Shows the active goal and next todo

```

## Upgrading LoopX

LoopX includes a self-update mechanism to upgrade the CLI without re-running the installer.

### Check for Updates

```bash
loopx update --check

```

### Preview Changes

```bash
loopx update --dry-run

```

### Execute the Upgrade

```bash
loopx update --execute

```

This downloads the latest release snapshot and updates the wrapper in `~/.local/bin` while preserving your global skills configuration.

## Quick Demo

To test LoopX without connecting a real project:

```bash
export PATH="$HOME/.local/bin:$PATH"
loopx demo               # Creates /tmp/loopx-demo with sample goals

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

```

## Summary

- **Two installation paths**: Use the no-clone installer ([`scripts/install-from-github.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-from-github.sh)) for stable releases, or the clone-based installer ([`scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-local.sh)) for development with the `loopx-canary` wrapper.
- **Installation locations**: Binaries go to `~/.local/bin`, releases to `~/.local/share/loopx/releases/`, and global skills to `~/.codex/skills/`.
- **Health verification**: Always run `loopx doctor` after installation to validate Python 3.11+, PATH configuration, and state kernel connectivity.
- **Project setup**: Use `loopx connect` or `loopx bootstrap` to create the `.loopx/` state directory in your projects.
- **Self-updating**: Use `loopx update --execute` to upgrade without reinstalling from scratch.

## Frequently Asked Questions

### What is the difference between `loopx` and `loopx-canary`?

**`loopx`** is the stable CLI wrapper installed by [`scripts/install-from-github.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-from-github.sh) that points to a release snapshot in `~/.local/share/loopx/releases/`. **`loopx-canary`** is the development wrapper created by [`scripts/install-local.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-local.sh) that points directly to your Git checkout, allowing you to test changes to the Python modules (`loopx/*.py`) before submitting them.

### Where does LoopX store its state and configuration?

LoopX stores global CLI components in `~/.local/share/loopx/releases/` and `~/.local/bin/`, while global skills go under `~/.codex/skills/`. Per-project state lives in a hidden `.loopx/` directory created when you run `loopx connect` or `loopx bootstrap`. The state kernel keeps objectives, todos, and quota metadata in this directory, which remains uncommitted to your repository.

### Can I install LoopX without affecting my existing Codex or Claude Code setup?

Yes. The installer adds global skills under `~/.codex/skills/` but does not modify your existing agent configurations. The skills expose LoopX commands (`$loopx`, `/loopx`) to compatible hosts without disrupting other workflows. If you need to remove LoopX later, delete `~/.local/bin/loopx`, `~/.local/share/loopx/`, and the skill files in `~/.codex/skills/loopx*`.