# How to Set Up Custom Agent Runner Integration with LoopX: A Complete Guide

> Learn to set up custom agent runner integration with LoopX. This guide covers installing the CLI, consuming packets, executing agent turns, and applying scheduler hints for seamless operation.

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

---

**To set up custom agent runner integration with LoopX, install the LoopX CLI on your host, consume the durable control-plane packets via the quota API, execute bounded agent turns, and apply the scheduler hints before the next wake.**

LoopX provides a **durable control-plane contract** that bridges your host-side runner and the agent performing bounded work. According to the `huangruiteng/loopx` source code, embedding LoopX into an existing custom runner requires only four integration steps, keeping your wake-up orchestration and workspace setup logic intact while delegating policy decisions to the LoopX control plane.

## Understanding the LoopX Integration Architecture

The architecture consists of three logical pieces that separate concerns between policy and execution.

### The Three Logical Components

1. **LoopX CLI** owns the durable goal, todo, claim, gate, quota, evidence, monitor, and scheduler hint. It does not own agent reasoning, tools, or external system interactions.
2. **Lightweight Skill / Re-entry Instruction** owns how the agent reads a fresh LoopX packet, obeys its boundary, validates work, and writes back. It does not own current task state or another scheduler.
3. **Your Runner** owns wake-ups, workspace/session set-up, agent invocation, and applying the timer/scheduler value. It does not own LoopX policy, hidden authority, or domain truth.

Your runner orchestrates the outer loop: `wake → bounded execution → apply scheduler hint → next wake`. Inside this loop, the **LoopX Turn** follows a deterministic sequence: decide, execute, validate, and commit.

### The Bounded Turn Model

Each turn is atomic. The runner requests a packet from LoopX, executes exactly the bounded work described, writes back the result, and receives a scheduler hint for the next wake. This model ensures that validation failures never spend quota and that state recovery happens without replay.

## Integration Paths: Direct CLI vs Turn Adapter

LoopX supports two integration depths defined in [`docs/guides/custom-agent-runner-integration.md`](https://github.com/huangruiteng/loopx/blob/main/docs/guides/custom-agent-runner-integration.md).

### Direct CLI Orchestration

**Direct CLI orchestration** is the stable baseline. Use this when your runner already invokes agents and validates their work. Your runner consumes the `quota should-run` command, manages the todo lifecycle, handles `refresh` and `spend` contracts, and acknowledges scheduler hints via the CLI.

### LoopX Turn Adapter (Experimental)

**The LoopX Turn adapter** adds a typed transaction layer inside the runner. Use `turn run-once` with the built-in `codex-cli` adapter or a thin `generic-cli` adapter when you want a typed command that plans, invokes a bounded host segment, validates, and commits. This path is experimental and wraps the direct CLI calls in a higher-level abstraction.

## Step-by-Step Implementation

Follow these steps to integrate the LoopX control plane into your custom runner.

### 1. Bootstrap the Host Environment

Install the LoopX CLI on the machine that owns the project workspace:

```bash
curl -fsSL https://raw.githubusercontent.com/huangruiteng/loopx/main/scripts/install-from-github.sh | bash
export PATH="$HOME/.local/bin:$PATH"
loopx doctor --agent-type other-agent

```

*Source:* [`scripts/install-from-github.sh`](https://github.com/huangruiteng/loopx/blob/main/scripts/install-from-github.sh)

### 2. Onboard Your Custom Agent

Retrieve the current packet, including the `quota should-run` command and available capabilities:

```bash
loopx agent-onboard \
  --agent-type other-agent \
  --project . \
  --goal-id $GOAL_ID \
  --agent-id $AGENT_ID \
  --task-text "Initial task description" \
  --available-capability shell

```

*Source:* [`docs/guides/custom-agent-runner-integration.md`](https://github.com/huangruiteng/loopx/blob/main/docs/guides/custom-agent-runner-integration.md) (lines 60–68)

### 3. Execute Bounded Turns

For **direct CLI orchestration**, request the quota command as JSON, extract the command, and run it:

```bash

# Get the quota command (JSON output)

JSON=$(loopx --format json \
  --registry "$HOME/.codex/loopx/registry.global.json" \
  quota should-run \
  --goal-id $GOAL_ID \
  --agent-id $AGENT_ID \
  --available-capability shell)

# Extract the command to run

CMD=$(echo "$JSON" | jq -r '.command')

# Execute the agent turn (your custom runner just runs the command)

$CMD

```

For the **experimental Turn adapter**, use:

```bash
loopx turn run-once --adapter codex-cli --goal-id $GOAL_ID --agent-id $AGENT_ID

```

*Source:* [`docs/guides/custom-agent-runner-integration.md`](https://github.com/huangruiteng/loopx/blob/main/docs/guides/custom-agent-runner-integration.md) (lines 101–108)

### 4. Handle State Write-Back and Scheduling

After the agent finishes, LoopX automatically writes back state via `loopx refresh-state`. Spend quota only after validation. Extract the `scheduler hint` field from the CLI output, apply it to determine the next wake time, and acknowledge it with the returned CLI command before the next iteration.

## Core Contracts and Code References

To implement a visible-TUI runner, reference these specific contracts in the LoopX codebase.

### Multi-Agent Runner Contract

The reusable visible-TUI runner contract is defined in [`loopx/control_plane/agents/multi_agent/contract.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/agents/multi_agent/contract.py). The function `build_tui_multi_agent_runner_contract` (starting at line 46) defines the schema, coordination model, TMUX lifecycle, lane environment, and pane behavior:

```python
from loopx.control_plane.agents.multi_agent.contract import build_tui_multi_agent_runner_contract

contract = build_tui_multi_agent_runner_contract(
    session_name="my-session",
    lane_count=2,
    attach_command="tmux attach -t my-session",
    stop_command="tmux kill-session -t my-session",
    retry_command="tmux new-session -s my-session",
    all_lane_workspace_isolation=False,
)

print(contract)

```

### Runtime Launcher Integration

The visible-multi-agent launcher in [`loopx/visible_multi_agent_launcher.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/visible_multi_agent_launcher.py) builds the shell command that injects LoopX environment variables and launches the runner. Use the `runtime_shell_command` function (around line 34) to generate the invocation:

```python
from loopx.visible_multi_agent_launcher import runtime_shell_command
from pathlib import Path
import subprocess

cmd = runtime_shell_command(
    "tmux new-session -s my-session",
    project=Path('.'),
    registry=Path('.loopx/registry.json'),
    runtime_root=Path('.loopx/runtime'),
    visible_session="my-session",
)

subprocess.run(cmd, shell=True, check=True)

```

## Acceptance Checklist for Production

Before automating the integration, verify that your runner satisfies the checklist from [`docs/guides/custom-agent-runner-integration.md`](https://github.com/huangruiteng/loopx/blob/main/docs/guides/custom-agent-runner-integration.md):

- **Restart Recovery**: Restart recovers from LoopX state without replay.
- **User Action Surface**: A concrete user action is surfaced; unrelated safe todos may still run.
- **Claim Safety**: Two agents cannot silently claim the same work.
- **Validation Guarantees**: Validation failure never spends quota.
- **Idempotency**: Scheduler ACK is idempotent.
- **Privacy**: No private paths or raw transcripts leak into LoopX state.
- **Handoff**: Agents hand off via successor todos without a permanent leader.

## Summary

- LoopX provides a **durable control-plane** that separates policy from execution via three logical components: the CLI, the re-entry skill, and your runner.
- Choose **direct CLI orchestration** for stable integration or the **Turn adapter** for experimental typed transactions.
- Implement the core loop: bootstrap with [`install-from-github.sh`](https://github.com/huangruiteng/loopx/blob/main/install-from-github.sh), onboard with `loopx agent-onboard`, execute with `loopx quota should-run`, and apply scheduler hints.
- Reference `build_tui_multi_agent_runner_contract` in [`contract.py`](https://github.com/huangruiteng/loopx/blob/main/contract.py) and `runtime_shell_command` in [`visible_multi_agent_launcher.py`](https://github.com/huangruiteng/loopx/blob/main/visible_multi_agent_launcher.py) for TUI runner contracts.
- Validate against the eight-item acceptance checklist before production deployment.

## Frequently Asked Questions

### Can I use LoopX with my existing agent framework?

Yes. The direct CLI orchestration path is designed for existing runners. You keep your wake-up logic, workspace setup, and agent invocation; you simply replace hard-coded commands with calls to `loopx quota should-run` and consume the JSON packet to drive each turn.

### What happens if the runner crashes mid-turn?

The LoopX control plane maintains durable state. After a restart, your runner recovers from LoopX state without replaying previous work because the control plane tracks which todos are claimed and which quota has been spent. You must ensure your runner re-fetches the current packet via the onboarding or refresh contract rather than replaying local state.

### How does the Turn adapter differ from Direct CLI orchestration?

The **Turn adapter** provides a typed transaction layer (`turn run-once`) that wraps the decide-execute-validate-commit sequence in a single command, whereas **Direct CLI orchestration** requires your runner to explicitly call `quota should-run`, execute the returned command, and manage the write-back. The adapter is experimental and adds convenience; direct CLI offers finer-grained control.

### Where is the authoritative state stored?

The **LoopX CLI** owns the durable goal, todo, claim, gate, quota, and evidence. Your runner does not own the policy or domain truth; it only owns wake-ups, workspace setup, and applying the scheduler values returned by the LoopX control plane. This ensures that state remains consistent across runner restarts and concurrent agent invocations.