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

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.

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:

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

2. Onboard Your Custom Agent

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

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 (lines 60–68)

3. Execute Bounded Turns

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

# 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:

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

Source: 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. The function build_tui_multi_agent_runner_contract (starting at line 46) defines the schema, coordination model, TMUX lifecycle, lane environment, and pane behavior:

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 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:

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:

• 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, 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 and runtime_shell_command in 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.

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