The Local Control Plane for Long-Running AI Agents: LoopX Design Philosophy and Practical Guide

An agent can complete a task in a single session – many developers do this daily. But long-running work is different: goals shift mid‑stream, human decisions interrupt, evidence goes stale, peer agents hand off to each other, and schedulers can keep burning resources long after the state has ceased to transition meaningfully. Chat memory and timers aren’t enough to govern these scenarios.

LoopX offers a different approach: keep the long-term control state in a compact, durable layer, so that the loop keeps moving forward while critical decisions stay with humans. It targets multi‑day or multi‑week engineering, research, and experimental goals. Codex, Claude Code, Cursor, or your own runtime execute bounded tasks one slice at a time, while objectives, gates, todos, evidence, quotas, and handoffs remain stable across rounds.

This article walks through LoopX’s design logic, installation paths, core operations, and advanced capabilities from a practitioner’s perspective. It helps technical teams decide whether this control plane fits their workflow.

Why a Single‑Round Agent Isn’t Enough – and Why We Need a Control Plane

Let’s start with the conclusion: single‑round agents are good at execution, not at governance. If you only need one‑off code generation, a quick Q&A, or a local refactor, existing tools are fine. But once a task stretches beyond a day, involves multiple people, uses multiple tools, needs human approval, or requires handoffs between agents, the cracks start to show.

Four Recurring Problems in Long‑Running Tasks

From hands‑on experience, these problems fall into four buckets:

Goal drift. What you set out to do on day one rarely matches day three – customer feedback, technical constraints, and new discoveries change direction. The agent’s chat history mixes old and new goals, making it hard to tell which version of the goal a given decision serves.

Non‑auditable decisions. The agent executes a series of actions, but reconstructing why it chose a particular path usually requires replaying the entire session. Without structured decision records, post‑mortems and debugging are expensive.

Broken handoffs. One agent works halfway, then needs another to take over, or waits for a human go‑ahead. State information gets lost in the transfer, and the new agent spends time re‑understanding context, hurting efficiency.

Unchecked resource consumption. Without a quota mechanism, an agent can spin its wheels on ineffective paths, burning tokens and time, while you have no clear signal on when to pull the plug.

How LoopX Addresses Them

LoopX overlays a compact control state on top of these four problem areas:

Goal / issue / project
   │
   ▼
LoopX state: objective + gate + todo + scope + evidence + quota
   │
   ├─ Needs human judgment? ── Yes ─▶ Ask a concrete question and wait
   │
   ├─ Safe side‑path available? ─▶ Execute a bounded agent slice
   │
   ▼
Codex / Claude Code / Cursor / shell agent runs one round
   │
   ▼
Write back evidence + handoff + next todo ─▶ quota decides next tick

This state model is the heart of LoopX. It is not an enhanced chat memory – it is an independent, persistent, and auditable control‑plane state. Each field targets a concrete problem:

• Objective: the current goal, with clear scope and authority.
• Gate: exactly where a human decision is needed, not a vague “wait for owner” but a specific question.
• Todo: what to do next, who owns this slice, and for how long.
• Scope: what is in bounds, what is out of bounds.
• Evidence: what happened, what was verified, which writebacks were accepted.
• Quota: whether the loop should continue, and the scheduler hint.

Key Concepts of the LoopX State Model – a Quick Tour

Before installing, it helps to understand how LoopX organises state. No deep theory here – just the concepts you will encounter immediately.

Goal and State

A Goal is the top‑level unit. It represents a long‑running objective – for instance, “fix a particular issue in OpenViking”, “run a series of ML experiments”, or “continuously monitor a benchmark”.

Each Goal has a clear state machine. States are not just “in progress / done”; they include:

• Active: the goal is live, agents may run subject to quota.
• Blocked: held by a gate – needs human judgment or an external event.
• Completed: the objective is met; no further execution.
• Archived: retained for evidence but not scheduled.

Gate – Concrete Anchors for Human Judgment

The Gate is one of LoopX’s most pragmatic features. It is not a vague “needs owner approval” flag – it pins the human decision to a specific question:

• Is this PR ready for review?
• Which arm of this A/B experiment should proceed?
• Is the safe side‑path authorised?
• Is this release cleared for deploy?

When an agent encounters a gate, it stops and asks the concrete question, then waits. Humans see actionable items instead of generic “please approve” requests.

Todo, Claim, and Lease

A Todo is the smallest unit of agent work. Any Todo can be claimed by at most one agent at a time, with a lease duration. This resolves conflicts in multi‑agent scenarios – no two agents work on the same Todo concurrently.

Claim and Lease turn Todos from passive “to‑do lists” into schedulable units with explicit ownership and timeout‑based reclamation.

Evidence and Writeback

After finishing a slice, the agent must write back Evidence – what it did, what the result was, and its verification status. Writeback is an accepted, validated result; not every output is automatically accepted.

This mechanism may sound simple, but it has a strong practical effect: it makes cross‑round decisions traceable, and lets humans inspect “what does the current evidence say?” without replaying the entire execution history.

Quota and Scheduler Hint

Quota controls the execution cadence. It is not a fixed “N times per day” cap; instead it includes:

• Should‑run: whether the registered agent should execute now.
• Scheduler hint: a suggested timing for the next tick.
• Spend‑slot: only slices that complete verification and writeback consume quota.

Silent skips, preflight failures, and dry‑run previews do not consume quota. This allows agents to perform health checks and rehearsals without burning budget.

Installation and First Connection – Two Paths, Pick the Right One

LoopX’s installation follows a simple rule: most users do not need to clone the repository.

Path 1: Direct Install (Recommended)

Requirements: Python 3.11+, curl, tar, and a macOS or Linux shell. The Python package has no runtime dependencies beyond the standard library.

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

Then connect inside your project root:

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

If the project is not yet initialised and connect explicitly tells you that state is missing, use the guided path:

loopx start-goal --guided --project . --goal-text "your long‑term goal"

Important: reuse existing LoopX state when present – do not overwrite it. Ensure that .loopx/, .codex/goals/, and .local/ are ignored in version control.

Path 2: Clone Install (for Contributors Only)

Only contributors who need the live canary wrapper should use this:

git clone https://github.com/huangruiteng/loopx ~/loopx
~/loopx/scripts/install-local.sh
loopx doctor

Post‑Installation Checks

After a successful connection, you should see:

• loopx doctor passes.
• The project has .loopx/registry.json and an active goal projection.
• loopx status shows the current goal, concrete user gates, and the next agent todo.
• A visible loop driver exists, or the agent gives explicit activation instructions.
• Local runtime state is ignored, not committed.

Connecting to Your Existing Agent – Codex, Claude Code, Cursor, and More

LoopX does not replace your agent runtime – it acts as a control plane that integrates with various hosts. Each host has a different integration entry point, but all obey the same gate and quota constraints.

Codex App

Have the agent connect to LoopX inside the current project, run loopx doctor, preserve existing state, and report the current gate and next todo. Then use $loopx <complex‑task> or the loopx skill to trigger execution.

Codex App heartbeat cadence follows quota should-run.scheduler_hint.

Codex App over SSH

loopx agent-onboard --agent-type codex-app-ssh --project .

The returned visible /goal <task_body> serves as the entry point.

Codex CLI

Launch Codex in the project, let it connect and diagnose LoopX, then use $loopx <complex‑task> or /skills. Headless execution is not the default.

Claude Code

Install the opt‑in adapter, then run /loopx <task> followed by /loop. The native Claude Code /loop is driven by LoopX gates.

OpenCode

Install the static command facade; for recurring goals, explicitly opt in with --with-goal-bridge.

Cursor, Shell, and Custom Runners

Use the same installer and loopx doctor, then connect manually or invoke via your runner. See the Custom Agent Runner Integration guide for details.

Core Tick Operations

Regardless of the host, the core tick operations are minimal:

loopx quota should-run      # should the registered agent execute now?
loopx todo claim            # who owns this slice?
loopx todo update           # what happened?
loopx refresh-state         # what should the next round see?
loopx quota spend-slot      # account for a completed and verified slice

Day‑to‑Day Operations and Recovery – Status Checks, Quota, and Gates

Start each session with these three commands:

loopx status
loopx history --goal-id your-project-goal
loopx quota should-run --goal-id your-project-goal

Automated rounds must always check quota first; only completed and verified slices count toward spent slots. Silent skips, preflight failures, and dry‑run previews do not consume quota.

When a lane is blocked by a user gate, independently audited safe side‑paths may continue, but they cannot bypass the gate.

Peer agents use loopx todo claim before execution and loopx todo update after validation, keeping ownership and evidence visible.

Scheduler cadence follows quota should-run.scheduler_hint. For Codex App automation, the ack_hint.cli_args in the payload confirms the current hint.

Before public release, run:

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

Capabilities at a Glance – What LoopX Can Do, and Its Boundaries

LoopX condenses the control plane into five questions that users can act on directly:

Question	State kept visible by LoopX
What is the current goal?	Active goal, clear scope, and current authority.
What comes next?	Ordered user/agent todos, ownership, claim, and lease.
Which step needs human judgment?	A concrete user gate, not a vague “wait for owner”.
What has happened to the evidence?	Compact run history, verification, blockers, and accepted writebacks.
Can the loop continue?	Quota, capability, safe side‑paths, scheduler hints, and stop conditions.

Control‑Plane Surfaces

Surface	Purpose	Entry command
Goal state & status	Track active state, todos, claims, gates, evidence, and run history.	loopx status, loopx diagnose, loopx review-packet
Quota & interaction contract	Decide whether to execute, ask, wait, self‑heal, or stay silent.	loopx quota should-run
Agent runtime bridge	Make different hosts obey the same guard.	loopx heartbeat-prompt, loopx codex-cli-bootstrap-message, loopx worker-bridge
Operator surface	Present compact state without making the browser the source of truth.	loopx serve-status
External projection	Project todos/gates onto collaboration surfaces while keeping LoopX authoritative.	loopx lark-kanban
Domain capabilities	Reusable lanes for issue fixing, content ops, ML experiments, benchmarks, etc.	loopx issue-fix, loopx content-ops, loopx ml-experiment, loopx benchmark
Governance patterns	Reusable routing, gates, evidence, projection, and planning shapes.	See the Interaction Pattern Catalog

Four Runtime Responsibilities

Role	Responsibility
Agent	Completes the plan, analysis, tool use, and one bounded execution via the host/runtime.
Provider	Calls external systems, returns observations, effect results, and readbacks.
Capability	Defines caller results, normalises and validates provider outputs, and proposes typed transitions.
Kernel	Persists todos, gates, monitors, accepted writebacks, quotas, recovery, and scheduling.

The execution path is Agent -> Capability -> Provider, and control flows back via Provider readback -> Capability transition -> Kernel.

Advanced Paths – Presets, Auto Research, and Governed Turns

A first useful loop does not require every optional capability. Enable these advanced paths only when the work actually needs them.

Presets and Auto Research

Safe presets cover daily triage, changelog drafts, and PR watch. More advanced CI/dependency sweeper presets require explicit authorisation, isolated worktrees, verifiers, quota/cost gates, and human review.

loopx preset list
loopx preset show daily-triage

Viewing a preset is read‑only. For an already‑connected recurring goal, you can check its readiness:

loopx ready-score --goal-id <goal-id> --agent-id <agent-id>

Auto Research orchestrates proposer, executor, and evaluator/promoter roles while keeping quota and evidence visible. It suits scenarios that need parallel iteration with multiple roles.

Governed Turn

LoopX can produce a pure‑function, bounded turn decision based on validated receipts, fresh quota state, and provider‑neutral budget.

Explore Graph / Harness

Explore is formally supported, optional, and off by default. It fits tasks with quantifiable offline eval, baselines, treatments, and guardrails – it does not replace production approval.

Reviewing Agent Work

loopx review-packet gives an owner‑facing compact view: decisions, evidence, verification, and unresolved gates.

Apps and Projections

• Local read‑first UI: see apps/presentation/dashboard/README.md
• Public‑safe product view: https://huangruiteng.github.io/loopx/frontstage/
• Lark Kanban adapter: documented in the integrations folder
• Custom multi‑agent runners: see the Custom Runner integration guide

Optional projections make state easier to inspect, but they never become the new source of truth.

Two Real‑World Trajectories – 200+ Hours of Public Evidence

LoopX’s README shows two real trajectories, each spanning 200+ wall‑clock hours. Wall‑clock time here means the elapsed time from project start to the latest evidence – not 200 hours of continuous model execution, nor unattended production autonomy.

Open Source Issue Fix

A 200+ hour public contribution trajectory: focused PR delivery and reusable fix knowledge feed back into each other.

The creator of LoopX uses this path, as an OpenViking contributor, for ongoing issue‑to‑PR fixes. The public contribution sequence, from the first PR creation to the latest review or update, spans more than 200 hours. The issue‑fix capability keeps rolling repository context, revision‑aware fix knowledge, and reviewer‑facing preferences separate; the linked PRs, source code, and tests at the current checkout always remain the ultimate authority.

Auto ML Experiment

A 200+ hour owner‑run experiment trajectory: hypotheses, matched evidence, invalid lineages, live reproduction, and promote/stop gates all stay on the same graph.

This public‑safe graph preserves the decision lineage within that 200+ hour natural time window. It is trajectory evidence – not a claim of continuous compute execution, independent reproduction, or production outcomes.

Community and Feedback Channels

LoopX is still early. The most valuable input comes from real long‑running agent projects – where the control plane helps, where it feels too heavy, and which gates, handoffs, or scope definitions remain unclear.

• For reproducible bugs, installation issues, or feature requests: open a GitHub issue.
• For documentation fixes, showcase additions, or small public‑safe examples: submit a PR.
• Chinese‑speaking users and contributors can join the Feishu developer group, or add WeChat huangrt00 (note: LoopX).

Practical Summary / Action Checklist

1. Install directly with curl | bash – no clone needed.
2. Connect inside your project root: loopx connect, then verify with loopx status.
3. First goal: if the project is uninitialised, use loopx start-goal --guided.
4. Daily checks: loopx status, loopx history, loopx quota should-run.
5. Agent integration: pick the correct host entry point; core tick operations are uniform.
6. Quota discipline: only completed and verified slices consume quota.
7. Gate handling: stop at user gates and wait for human judgment – do not bypass.
8. Before public release: run loopx check to verify public/private boundaries.

One‑Page Quick Reference

Question	Answer
What is LoopX?	A local control plane for long‑running AI agents – not an agent runtime.
What problem does it solve?	Goal drift, non‑auditable decisions, broken handoffs, and uncontrolled resource use.
Which agents does it support?	Codex, Claude Code, Cursor, shell, and custom runners.
What is the core state?	Objective, gate, todo, scope, evidence, quota.
What is a gate?	A concrete anchor for human judgment – not a vague “approval needed”.
How does quota work?	Only verified slices consume quota; silent skips are free.
How is evidence stored?	Through writeback – only validated results are accepted.
How do multiple agents coordinate?	Via todo claim + lease – one owner at a time.

Frequently Asked Questions

Does LoopX execute dangerous operations for me?
No. Dangerous permissions, production writes, public releases, and final ownership stay with humans. LoopX is a control plane, not an automation controller.

Do I need to clone the repository to use it?
No. Most users install directly with curl | bash. Cloning is only for contributors who need the live canary wrapper.

How does LoopX relate to Codex or Claude Code?
LoopX does not replace them. The agent runtime handles bounded execution; LoopX keeps goals, gates, todos, evidence, quotas, and handoffs stable across rounds.

Does LoopX support multiple agents running in parallel?
Yes. The todo claim + lease mechanism ensures that only one agent owns a given todo at any time.

If a gate blocks, does the whole loop stop?
When a lane is blocked by a user gate, independently audited safe side‑paths may proceed, but they cannot bypass the gate.

What happens when quota runs out?
quota should-run returns false, so no new slices are executed until quota is reset or manually overridden.

Where does LoopX store its state?
In .loopx/ at the project root. Do not commit it to version control.

Is LoopX ready for production?
LoopX is an early but usable local control plane – it is not a production automation controller. Production writes and public releases still require human approval.