How to Set Up a Development Environment for LoopX: A Step-by-Step Guide to Installing and Running the Autonomous Agent Framework

To set up a LoopX development environment, clone the repository, run scripts/install-local.sh to install dependencies and CLI tools, verify with loopx doctor, and confirm functionality with loopx demo.

LoopX is a complex autonomous-agent framework that separates control-plane logic, runtime adapters, and presentation layers. Setting up a proper development environment requires following the repository's canonical workflow to ensure all components are correctly wired. This guide walks through the exact steps documented in the official contribution guidelines, with copy-paste commands and verification steps.

Prerequisites and Quick Start

Before installing, ensure you have Python, Node.js, and Docker available on your system. The loopx doctor command will validate these dependencies after installation.

Run this complete workflow to get started:

# 1️⃣ Clone the repository

git clone https://github.com/huangruiteng/loopx ~/loopx
cd ~/loopx

# 2️⃣ Execute the official installer

./scripts/install-local.sh
export PATH="$HOME/.local/bin:$PATH"

# 3️⃣ Verify all dependencies are satisfied

loopx doctor

# 4️⃣ Launch the minimal end-to-end demo

loopx demo

The scripts/install-local.sh script automates environment creation, installs development extras, and adds the LoopX CLI to your $PATH【/cache/repos/github.com/huangruiteng/loopx/main/scripts/install-local.sh】.

Understanding the LoopX Development Environment Structure

LoopX organizes its codebase into distinct architectural layers. Knowing these boundaries helps you navigate the codebase effectively after installation.

Control-Plane, Runtime, and Presentation Layers

• Control-plane – Manages agent state machines and scheduling policies
• Runtime – Adapter layer connecting to external execution environments
• Presentation – UI and output formatting components

The Developer Guide at docs/development/README.md explains how to locate the relevant bounded context for your work【/cache/repos/github.com/huangruiteng/loopx/main/docs/development/README.md#L1-L25】.

Key Configuration Files

File	Purpose
CONTRIBUTING.md	Official clone-install-verify steps and quality-gate commands【/cache/repos/github.com/huangruiteng/loopx/main/CONTRIBUTING.md#L47-L66】
docs/development/README.md	Architecture overview and documentation navigation
scripts/install-local.sh	Automated environment bootstrap
examples/	Runnable smoke tests and demonstration scripts

Installing LoopX for Core Development

For users who plan to modify core components—such as the control-plane state machine, scheduler policies, or presentation UI—additional setup steps are required.

Install Development and Test Dependencies

python -m pip install -e ".[test]"

This installs the package in editable mode with test dependencies, as specified in the project's pyproject.toml or setup configuration.

Verify Code Quality

The repository enforces static analysis and type checking. Run these commands before committing changes:

# Linting with Ruff

python -m ruff check loopx/

# Static type checking with mypy

python -m mypy

Run Smoke Tests and Full Test Suite

Validate your environment with the repository's public smoke tests:

# Execute control-plane smoke test

python examples/control_plane/cli-output-budget-regression-smoke.py

# Run complete pytest suite

python -m pytest -q

These commands are documented in the Local Development section of CONTRIBUTING.md【/cache/repos/github.com/huangruiteng/loopx/main/CONTRIBUTING.md#L47-L66】.

Using the LoopX CLI for Environment Verification

The loopx command-line interface provides diagnostic and demonstration tools essential for development workflow.

loopx doctor – Dependency Validation

Checks that all required external tools (Python, Node, Docker, etc.) are available and that core commands are functional. Run this after any environment change.

loopx demo – End-to-End Verification

Launches a minimal run through the complete stack: control-plane → scheduler → turn → presentation. This confirms that the runtime is correctly wired and all layers communicate properly.

Troubleshooting Common Setup Issues

If loopx doctor reports missing dependencies, verify:

• Python version compatibility with the project's requirements
• Node.js installation for presentation-layer builds
• Docker daemon running for runtime container operations

The install-local.sh script attempts to configure $PATH automatically, but you may need to restart your shell or manually export PATH="$HOME/.local/bin:$PATH" to access the loopx command immediately after installation.

Summary

• Clone the repository to get the full source tree including scripts and examples
• Run scripts/install-local.sh to bootstrap the environment and install CLI tools
• Verify with loopx doctor to confirm external dependencies are satisfied
• Test with loopx demo to validate end-to-end functionality
• Install ".[test]" extras and run pytest when modifying core components

Following this workflow creates a LoopX development environment that respects the project's public/private boundary policies and is ready for contribution.

Frequently Asked Questions

What is the fastest way to install LoopX locally?

Run ./scripts/install-local.sh from the repository root. This single script creates a virtual environment, installs dependencies, and configures the loopx CLI tool in your $PATH【/cache/repos/github.com/huangruiteng/loopx/main/scripts/install-local.sh】.

How do I verify my LoopX installation is working correctly?

Execute loopx doctor to check external tool availability, then run loopx demo to see a complete control-plane → presentation flow. The demo launches a minimal end-to-end run that confirms the runtime is correctly wired.

Where are the official LoopX development instructions documented?

The CONTRIBUTING.md file contains the canonical clone-install-verify workflow, while docs/development/README.md provides broader architecture guidance【/cache/repos/github.com/huangruiteng/loopx/main/CONTRIBUTING.md#L47-L66】【/cache/repos/github.com/huangruiteng/loopx/main/docs/development/README.md#L1-L25】.

What tests should I run before submitting a LoopX contribution?

Run python -m ruff check loopx/ for linting, python -m mypy for type checking, and python -m pytest -q for the full test suite. Also execute python examples/control_plane/cli-output-budget-regression-smoke.py for the public smoke test as documented in the contribution guide【/cache/repos/github.com/huangruiteng/loopx/main/CONTRIBUTING.md#L47-L66】.

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