# How to Build LoopX from Source: Complete Python 3.11+ Installation Guide

> Build LoopX from source with this complete Python 3.11+ installation guide. Learn to clone the repo and install using pip for standard or editable modes.

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

---

**To build LoopX from source, clone the repository, ensure Python 3.11 or newer is installed, upgrade pip/setuptools/wheel, then run `pip install .` for a standard install or `pip install -e .` for editable development mode.**

LoopX is a pure-Python package with optional JavaScript/TypeScript assets that powers a local-first control plane for long-running AI agents. Building it from source gives you the latest features, lets you contribute patches, or customize the behavior for specialized deployments. This guide walks through the complete build process using the actual source structure from the `huangruiteng/loopx` repository.

## Prerequisites: Python 3.11+ and Git

LoopX deliberately targets modern Python. The `requires-python` field in [`pyproject.toml`](https://github.com/huangruiteng/loopx/blob/main/pyproject.toml) enforces **Python 3.11 or newer** — older versions will be rejected during installation.

Verify your environment before proceeding:

```bash
python3 -V   # Must output 3.11.x or higher

git --version

```

If your system Python is older, use **pyenv**, **conda**, or **uv** to install a compatible version.

## Step 1: Clone the LoopX Repository

Retrieve the source tree from GitHub. The repository root contains the package definition, all capability modules, and bundled frontend assets.

```bash
git clone https://github.com/huangruiteng/loopx.git
cd loopx

```

The `loopx/` directory contains the main package code, including [`loopx/entrypoint.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/entrypoint.py) where the CLI is defined.

## Step 2: Upgrade Build Dependencies

The project uses **setuptools** as its sole build backend. Upgrade your packaging tools to avoid compatibility issues with the `setuptools==83.0.0` requirement specified in [`pyproject.toml`](https://github.com/huangruiteng/loopx/blob/main/pyproject.toml).

```bash
python3 -m pip install --upgrade pip setuptools wheel

```

## Step 3: Build and Install LoopX

You have three installation modes depending on your use case:

### Standard Production Install

Compiles a wheel into `dist/` and installs LoopX into your active environment:

```bash
python3 -m pip install .

```

After installation, verify the CLI works:

```bash
loopx doctor   # Runs the built-in health-check command

```

### Editable Development Install

Use **`-e .`** when you plan to modify source code. Changes reflect immediately without re-installation:

```bash
python3 -m pip install -e .

```

This creates a link to your source directory, ideal for debugging or contributing to `huangruiteng/loopx`.

### Install with Optional Dependencies

LoopX declares optional extras under `[project.optional-dependencies]` in [`pyproject.toml`](https://github.com/huangruiteng/loopx/blob/main/pyproject.toml). For example, to include the DeepSeek harness:

```bash
python3 -m pip install .[deepseek-harness]

```

## Building a Wheel Without Installation

To generate a distributable `.whl` for sharing or private index upload:

```bash
python3 -m pip install build   # One-time install

python3 -m build               # Creates dist/loopx-*.whl

```

The wheel appears in `dist/` and can be installed later with `pip install dist/loopx-*.whl`.

## Understanding the Build Configuration

The **build backend** is declared in [`pyproject.toml`](https://github.com/huangruiteng/loopx/blob/main/pyproject.toml) using standard PEP 517 format:

```toml
[build-system]
requires = ["setuptools==83.0.0"]
build-backend = "setuptools.build_meta"

```

Key sections in this file control:

- **Package metadata** — name, version, description
- **Entry points** — `[project.scripts]` maps `loopx` to `loopx.entrypoint:main`
- **Package data** — `tool.setuptools.package-data` bundles JavaScript/TypeScript assets (no separate Node build required)
- **Optional dependencies** — extras like `deepseek-harness`

## Verifying Your Build

After installation, confirm LoopX is accessible:

```bash
which loopx           # Shows installation path

loopx --help          # Lists available commands

loopx doctor          # Validates environment health

```

The `loopx doctor` command exercises the core initialization path through [`loopx/__init__.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/__init__.py) and the CLI entry point in [`loopx/entrypoint.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/entrypoint.py).

## Troubleshooting Common Issues

- **Python version errors**: Double-check `python3 -V` matches 3.11+; the installer strictly enforces this via `requires-python = ">=3.11"`
- **Setuptools version mismatches**: Upgrade with `pip install --upgrade setuptools` if you see backend errors
- **Missing CLI command**: Ensure your PATH includes the pip scripts directory, or use `python3 -m loopx` as fallback

## Summary

- **Clone** `https://github.com/huangruiteng/loopx.git` to obtain source
- **Require Python 3.11+** — enforced by [`pyproject.toml`](https://github.com/huangruiteng/loopx/blob/main/pyproject.toml)
- **Upgrade** `pip setuptools wheel` before building
- **Install** with `pip install .` (production) or `pip install -e .` (development)
- **Optional extras** available via `pip install .[extra-name]`
- **No Node build needed** — JavaScript assets are pre-bundled as package data

## Frequently Asked Questions

### Do I need Node.js or npm to build LoopX from source?

No. While LoopX includes TypeScript/JavaScript assets for features like the `opencode` goal-mode plugins, these are shipped as pre-built package data per `tool.setuptools.package-data` in [`pyproject.toml`](https://github.com/huangruiteng/loopx/blob/main/pyproject.toml). The standard `pip install .` process handles them automatically without any Node toolchain.

### Why does LoopX require Python 3.11 specifically?

The `requires-python = ">=3.11"` constraint in [`pyproject.toml`](https://github.com/huangruiteng/loopx/blob/main/pyproject.toml) reflects deliberate use of modern language features and standard library improvements. The `setuptools` backend enforces this at installation time; attempting to install on Python 3.10 or earlier will fail with an explicit version conflict error.

### How do I uninstall or upgrade a source-built LoopX?

Use standard pip commands: `pip uninstall loopx` removes it completely. For upgrades, pull latest source with `git pull`, then re-run `pip install .` (or `pip install -e .` for editable installs). The build process automatically increments to the new version declared in [`pyproject.toml`](https://github.com/huangruiteng/loopx/blob/main/pyproject.toml).

### Where does the `loopx` command come from after installation?

The CLI entry point is declared in [`pyproject.toml`](https://github.com/huangruiteng/loopx/blob/main/pyproject.toml) under `[project.scripts]` as `loopx = "loopx.entrypoint:main"`. When you run `loopx`, pip creates a wrapper that executes the `main()` function in [`loopx/entrypoint.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/entrypoint.py), which then dispatches to subcommands like `doctor` and `run`.