loopx-project/loopx

LoopX – a stateful control‑plane for long‑horizon AI agents

What it is – LoopX is an open‑source, provider‑neutral “control plane” that sits on top of existing LLM‑agent runtimes (Codex, Claude Code, Cursor, etc.). It stores the durable state of a multi‑turn, multi‑day workflow – objectives, gates, to‑dos, evidence, quotas and hand‑offs – and decides which agent should act next. In short, it turns a series of isolated agent calls into a reviewable, restartable, human‑in‑the‑loop loop.

Why it matters – Modern LLM agents are great at finishing a single task, but long‑running projects (research experiments, multi‑day engineering, continuous monitoring) need:

• Persistent context that survives restarts
• Explicit human‑approval points
• Safe fall‑backs and quota limits
• Clear audit trails (what was done, why, and with what evidence) LoopX provides that without replacing the underlying agent harness.

Key concepts

Concept	Role
Goal / Objective	The high‑level purpose of the loop (e.g., “train a model for 2 weeks”).
Gates	Human‑or policy‑driven checkpoints that must be approved before the next turn.
Todos	Bounded work items that an agent can claim and execute.
Evidence	Files, logs, or artifacts produced by a turn, stored immutably for later review.
Quota	Limits on how many turns may run, preventing runaway execution.
Handoff	Structured transfer of responsibility to another agent or to a human.

How it works – The loop looks like:

Goal → LoopX state (objective, gates, todos, evidence, quota)
   ├─ if human judgment needed → ask concrete question, wait
   ├─ else if safe fallback → run a bounded agent slice
   ▼
Agent runtime (Codex, Claude Code, etc.) executes one turn
   ▼
LoopX writes evidence, updates state, decides next turn

The state lives locally (a “local‑first” workspace) and is the single source of truth; the agent runtimes are merely workers.

Main features

• Personal Workspace – a local‑first UI (browser/PWA or native desktop) that shows goals, active tasks, schedules, and evidence across restarts.
• Provider‑neutral adapters – plug‑ins for Codex App, Claude Code, Cursor, KunlunCode, DeepSeek Harness, and generic shell runners.
• Human‑in‑the‑loop gating – explicit approval steps, typed previews, and receipts before state changes.
• Cross‑runtime continuity – you can switch from Codex to Claude Code mid‑project without losing state.
• Audit‑ready evidence graph – every turn’s outputs are versioned and visualised as a task‑graph.
• Extensible skill/command façade – expose LoopX as /loopx commands in various IDEs and chat platforms.
• Benchmarks & case studies – SWE‑Marathon, LHTB, auto‑ML, and open‑source issue‑fix demos showing 200 + hour loops.

Technology stack

• Core – TypeScript (Effect runtime) for the control‑plane server; Python 3.11+ client library and CLI.
• Storage – local file‑system based “local‑first” store (.loopx/ directory).
• UI – browser‑based dashboard (PWA) plus optional native macOS/Windows desktop builds.
• Packaging – distributed via PyPI (pip install loopx) and npm for the TypeScript core.

Typical use cases

• Multi‑day research or engineering experiments that need periodic human review.
• Issue‑fix or PR workflows that must retain context, evidence, and decision lineage.
• Continuous monitoring or heartbeat jobs that run for weeks.
• Teams of peer agents where ownership, leases, and hand‑offs are explicit.
• Any long‑running automation where a human operator must stay in control of critical actions.

Getting started

# Install the Python package (includes the CLI and the TypeScript runtime)
python3 -m pip install --upgrade loopx
# Install built‑in workflow skills (agents, adapters, etc.)
loopx workflow-skills --install
# Verify the installation
loopx doctor

# Connect a project to LoopX
cd /path/to/your/project
loopx connect   # creates .loopx/ state if missing
loopx status    # shows current goal, gate, todo

# Start a new long‑running goal (guided wizard)
loopx start-goal --guided --project . --goal-text "Train a sentiment model for 10 days"

After that you can launch the dashboard with loopx dashboard or run agents through the provided adapters (e.g., codex, claude, cursor).

Maturity – The repository ships a 1.0 release, a desktop preview, and a growing set of integrations. Documentation includes a bilingual developer book, detailed guides, and a showcase catalog. The project is actively maintained (Discord community, regular releases) and labelled “loop agents active”.

Where to learn more

• Website / Docs – https://loopx-project.github.io/loopx/
• Developer Book – https://loopx-project.github.io/loopx/docs/book/en/
• Discord – https://discord.gg/XmGgQyCFZd
• Benchmarks & case studies – see the “Evidence” section of the README.

---

All information above is taken directly from the repository’s README; no external speculation is added.