# Where to Find Example Projects Using LoopX: Complete Guide to Samples and Starter Templates

> Discover LoopX example projects in the huangruiteng/loopx repository. Explore nine Python scripts demonstrating worker registration, agent coordination, benchmarks, and custom runtimes.

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

---

**All LoopX example projects reside in the `examples/` directory at the repository root, containing nine self-contained Python scripts that demonstrate worker-bridge registration, multi-agent coordination, benchmark workflows, and custom runtime integration.**

The **huangruiteng/loopx** repository ships with a comprehensive suite of ready-to-run examples that serve as miniature demo projects. Each script demonstrates specific integration patterns for the LoopX control-plane and can be executed directly with only Python's standard library—no additional dependencies required beyond the LoopX CLI itself.

## LoopX Example Directory Overview

The **`examples/`** folder contains nine "smoke" scripts, each targeting a distinct capability domain or runtime integration scenario:

| Integration scenario | Example script | Purpose |
|---|---|---|
| **Worker-bridge install contract** | [`worker-bridge-install-contract-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/worker-bridge-install-contract-smoke.py) | Registers a worker-bridge's install contract with LoopX |
| **Worker-bridge benchmark ingest** | [`worker-bridge-benchmark-run-ingest-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/worker-bridge-benchmark-run-ingest-smoke.py) | Ingests benchmark results via the worker-bridge |
| **Multi-agent launcher** | [`visible-multi-agent-launcher-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/visible-multi-agent-launcher-smoke.py) | Coordinates multiple agents sharing a common goal |
| **Codex CLI packaged install** | [`showcase-frontstage-prototype-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/showcase-frontstage-prototype-smoke.py) | Demonstrates Codex CLI packaged-install flow |
| **Minimal custom runtime** | [`minimal-custom-runtime-example.py`](https://github.com/huangruiteng/loopx/blob/main/minimal-custom-runtime-example.py) | Starter template for building custom agent runtimes |
| **Value-connector (GitHub probe)** | [`value-connectors-github-public-probe-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/value-connectors-github-public-probe-smoke.py) | Fetches public GitHub data via the value-connector capability |
| **SkillsBench end-to-end** | [`skillsbench-benchmark-run-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/skillsbench-benchmark-run-smoke.py) | Full benchmark workflow with LoopX gating |
| **Static-site generation** | [`static-site-presentation-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/static-site-presentation-smoke.py) | Generates dashboards from LoopX state |
| **Auto-research showcase** | [`showcase-animation-prototype-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/showcase-animation-prototype-smoke.py) | Wires together an Auto-Research loop |

All files are pure Python scripts executable with `python3 <script>` after installing LoopX (`loopx doctor`).

## Key Example Projects Using LoopX for Custom Runtimes

### Minimal Custom Runtime Example

The file **[`examples/minimal-custom-runtime-example.py`](https://github.com/huangruiteng/loopx/blob/main/examples/minimal-custom-runtime-example.py)** provides the simplest starting point for new LoopX projects. It demonstrates how to initialize a LoopX state directory, create a goal, register a custom agent, and execute a turn.

```python
import json, pathlib, subprocess, sys
from loopx import LoopX

# Initialise a temporary LoopX state directory

state_dir = pathlib.Path('.loopx')
state_dir.mkdir(exist_ok=True)

lx = LoopX(state_dir)

# Create a simple goal

goal_id = lx.create_goal(
    objective="Demo: fetch the latest LoopX release tag",
    description="Show how a custom runtime can drive a LoopX turn."
)

# Define a tiny agent that runs a shell command

def fetch_latest_tag():
    result = subprocess.check_output(
        ['git', 'ls-remote', '--tags', 'https://github.com/huangruiteng/loopx.git'],
        text=True
    )
    tags = [line.split('/')[-1] for line in result.splitlines()]
    latest = sorted(tags)[-1]
    return {"latest_tag": latest}

# Register the agent in the LoopX kernel and execute a turn

lx.register_agent('demo-fetcher', fetch_latest_tag)
turn = lx.run_turn(goal_id, agent_id='demo-fetcher')
print(json.dumps(turn, indent=2))

```

This script creates a local `.loopx/` directory, registers a goal for fetching the latest release tag, and executes a single turn—printing the resulting state as formatted JSON.

### Worker-Bridge Integration Example

The **[`examples/worker-bridge-install-contract-smoke.py`](https://github.com/huangruiteng/loopx/blob/main/examples/worker-bridge-install-contract-smoke.py)** file shows how external worker-bridges register their capabilities with LoopX:

```python
from loopx import LoopX

lx = LoopX('.loopx')
goal = lx.create_goal(
    objective="Demo: install a worker-bridge contract",
    description="Shows the contract registration flow."
)

# Simulate a worker-bridge providing its install contract

contract = {
    "name": "example-bridge",
    "version": "1.0",
    "install": {"cmd": "pip install example-bridge"},
    "capabilities": ["value-connectors"]
}
lx.register_worker_bridge(contract)
print("Registered contract:", contract)

```

This pattern is essential for integrating third-party tools that need to advertise their installation requirements and capability sets to the LoopX control-plane.

## Real-World Showcase Projects

Beyond the `examples/` directory, the repository contains documented **showcase projects** in **`docs/showcases/`** that trace real-world, long-running LoopX loops. These include:

- **OpenViking issue-fix loop** — A multi-day automated debugging workflow
- **Four-day unattended run** — Extended autonomous operation with LoopX gating

Each showcase page in [`docs/showcases/README.md`](https://github.com/huangruiteng/loopx/blob/main/docs/showcases/README.md) links to the exact repository state (commits and files) that produced the demo, allowing you to reconstruct the full execution context.

## Supporting Documentation for Example Projects

| File | Path | Purpose |
|---|---|---|
| Step-by-step minimal runtime tutorial | [`docs/guides/minimal-custom-runtime-example.md`](https://github.com/huangruiteng/loopx/blob/main/docs/guides/minimal-custom-runtime-example.md) | Expands the minimal example with detailed explanations |
| Custom agent integration guide | [`docs/guides/custom-agent-runner-integration.md`](https://github.com/huangruiteng/loopx/blob/main/docs/guides/custom-agent-runner-integration.md) | Converts existing agents into LoopX-aware runtimes |
| Showcase index | [`docs/showcases/README.md`](https://github.com/huangruiteng/loopx/blob/main/docs/showcases/README.md) | Curated list of production-like LoopX applications |

## How to Run LoopX Example Projects

1. **Install LoopX CLI**: Run `loopx doctor` to verify your environment
2. **Clone the repository**: `git clone https://github.com/huangruiteng/loopx.git`
3. **Navigate to examples**: `cd loopx/examples`
4. **Execute any script**: `python3 minimal-custom-runtime-example.py`

Each script is self-contained and creates its own `.loopx/` state directory, so you can run multiple examples without conflicts.

## Summary

- **All example projects using LoopX** live in the repository's `examples/` directory
- Nine smoke scripts cover worker-bridge registration, multi-agent coordination, benchmarking, and custom runtime development
- **[`minimal-custom-runtime-example.py`](https://github.com/huangruiteng/loopx/blob/main/minimal-custom-runtime-example.py)** provides the best scaffolding for new projects
- **`docs/showcases/`** contains documented real-world loops with traceable repository states
- Examples require only Python's standard library and the LoopX CLI—no additional dependencies

## Frequently Asked Questions

### Where are the LoopX example projects located?

All example projects reside in **`examples/`** at the repository root. This directory contains nine standalone Python scripts demonstrating specific LoopX integration patterns, plus additional showcase documentation in `docs/showcases/`.

### Can I run LoopX examples without installing dependencies?

Yes. The example scripts in `examples/` only depend on Python's standard library. You need the LoopX CLI installed (`loopx doctor` to verify), but no external packages are required to execute the smoke tests themselves.

### Which LoopX example should I start with for custom agent development?

Begin with **[`examples/minimal-custom-runtime-example.py`](https://github.com/huangruiteng/loopx/blob/main/examples/minimal-custom-runtime-example.py)**. It demonstrates the complete lifecycle—state directory initialization, goal creation, agent registration, and turn execution—in under 30 lines of code. Supplement with [`docs/guides/minimal-custom-runtime-example.md`](https://github.com/huangruiteng/loopx/blob/main/docs/guides/minimal-custom-runtime-example.md) for detailed walkthrough.