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

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
• 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, 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

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:

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

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

What This Creates

The 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

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

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

Or connect to an existing LoopX project:

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

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

loopx update --check

Preview Changes

loopx update --dry-run

Execute the Upgrade

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:

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) for stable releases, or the clone-based installer (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 that points to a release snapshot in ~/.local/share/loopx/releases/. loopx-canary is the development wrapper created by 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*.

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