How to Test LoopX Locally: A Complete Guide to Installation and Validation

You can test LoopX locally by installing the lightweight Python-based control plane via a one-liner curl script, validating the installation with loopx doctor, connecting to a project directory, and running the built-in smoke tests from the examples/ folder.

LoopX is a lightweight, state-kernel control-plane for long-running AI agents. Because the core of LoopX lives in pure Python and only depends on the standard library, testing it locally is straightforward. This guide walks you through every step to verify your LoopX installation and validate its core capabilities.

---

Install LoopX Locally

The easiest way to test LoopX locally starts with the official one-liner installer. No repository clone is required.

curl -fsSL https://huangruiteng.github.io/loopx/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"

This script places the loopx CLI in ~/.local/bin/. The install snippet is documented in README.md at the root of the repository.

---

Validate the Installation with loopx doctor

Before testing any functionality, confirm that your environment meets LoopX's requirements.

loopx doctor

The doctor command validates:

• Python runtime availability
• Required OS utilities (curl, tar)
• A clean working directory for state operations

This health check is implemented in loopx/cli.py, which serves as the entry point for all CLI commands.

---

Connect LoopX to a Local Project

To test LoopX's state-kernel behavior, bind it to an existing project directory.

cd /path/to/your-project
loopx connect
loopx status

The connect flow initializes LoopX in your project. Running loopx status displays:

• Current goal
• Active gates
• Next todo item

This validates that the state kernel is properly tracking project context. The connection flow is documented in the "Getting Started" section of README.md.

---

Run Built-In Smoke Tests from the examples/ Directory

The LoopX repository ships with self-contained smoke tests under examples/. Each script exercises a specific capability and asserts expected output with no external dependencies.

python examples/worker-bridge-install-contract-smoke.py
python examples/visible-multi-agent-launcher-smoke.py
python examples/terminal-bench-loopx-cli-bridge-runner-smoke.py

These smokes deliberately avoid external dependencies, making them ideal for local CI pipelines. Key files include:

Smoke Test File	Capability Validated
examples/worker-bridge-install-contract-smoke.py	Worker-bridge contract installation
examples/visible-multi-agent-launcher-smoke.py	Visible multi-agent launcher flow
examples/terminal-bench-loopx-cli-bridge-runner-smoke.py	Terminal-bench CLI bridge integration

Each smoke test imports core modules like loopx.runtime and loopx.quota to verify control-plane primitives.

---

Run the Repository-Wide Quality Check

LoopX includes a check command that scans source, documentation, and examples for boundary violations and quality gate compliance.

loopx check \
  --scan-path README.md \
  --scan-path docs/ \
  --scan-path examples/

Passing this check confirms your local environment complies with the repository's public-safe policies. The check logic resides in loopx/cli.py alongside other CLI implementations.

---

Write Custom Tests with pytest (Optional)

For deeper validation, you can extend LoopX's testing with custom pytest suites. Because the core library is pure Python, any module is importable for unit testing.

First, install pytest:

pip install pytest

Then create a test file that exercises LoopX internals:

# tests/test_quota.py

import pytest
from loopx.quota import should_run

def test_quota_should_run():
    # Simulate a minimal goal-state fixture

    result = should_run(goal_id="demo", agent_id="test-agent")
    assert result is True

Run your custom suite:

pytest tests/

The official testing strategy is documented in docs/development/testing-and-quality.md. Core modules available for testing include:

• loopx.quota — quota enforcement logic
• loopx.status — status reporting for loopx status CLI output
• loopx.runtime — runtime management primitives

---

Summary

• Install LoopX locally with a one-liner curl script that requires no clone
• Verify installation using loopx doctor to check Python runtime and OS dependencies
• Connect to projects with loopx connect and inspect state with loopx status
• Run smoke tests from examples/ to validate worker bridge, multi-agent launcher, and CLI bridge capabilities
• Execute quality checks with loopx check to enforce repository policies
• Extend with pytest by importing pure-Python modules like loopx.quota and loopx.runtime

---

Frequently Asked Questions

Does LoopX require Docker or external services to test locally?

No. LoopX is implemented in pure Python with only standard library dependencies. All local testing—from installation verification to smoke tests—runs without Docker, databases, or external APIs. The examples/ smoke tests are self-contained and assert expected output directly.

Where are the official test files located in the LoopX repository?

The primary test files live in examples/ at the repository root. Files like worker-bridge-install-contract-smoke.py and visible-multi-agent-launcher-smoke.py serve as both documentation and executable validation. For pytest-style unit tests, see docs/development/testing-and-quality.md for templates using loopx.quota and other core modules.

What does loopx doctor actually check?

loopx doctor validates your local environment has: a compatible Python runtime, required OS utilities (curl, tar), and a clean working directory suitable for LoopX state operations. It is implemented in loopx/cli.py and runs before any project connection to prevent configuration errors.

Can I run LoopX tests in CI without installing the full repository?

Yes. The install script curl -fsSL https://huangruiteng.github.io/loopx/install.sh | bash works in CI environments. After installation, running the smoke tests from examples/ provides fast, dependency-free validation. The smoke tests require no repository clone and exit with clear pass/fail status codes suitable for CI pipelines.

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