Skip to content

ehz0ah/loopx

BranchesTags
 
 

Repository files navigation

LoopX loop engineering social preview banner

Loop engineering for long-running AI agents and agent teams.

A lightweight state kernel and agent-agnostic local control plane for Codex, Claude Code, Cursor, and other runtimes: objectives, gates, todos, quota, scheduler hints, evidence, and handoff state in one reviewable loop.

License Python Local first Loop Agents

把会干活的 Agent，接成可管理、可复盘、可持续改进的数字员工。

LoopX is a lightweight state kernel and local control plane for loop engineering: it keeps goals, todos, gates, quota, scheduler hints, evidence, and handoffs stable while Codex, Claude Code, Cursor, or another runtime executes each bounded turn. It does not replace your agent runtime; it makes long-running agent work reviewable, restartable, and easier to hand off.

Start with a useful loop instead of designing a whole agent platform. LoopX ships safe preset cards for daily triage, changelog drafts, PR watching, CI sweeping, and dependency sweeping. Beginner presets are report/draft/watch only; advanced fixers stay opt-in behind isolated worktrees, verifier checks, quota/cost limits, and human review.

Quick Start · User Manual · How It Works · See It In Action · Hosted Frontstage · Architecture · 简体中文

More docs and project links

Capability Surface · Getting Started · User Manual · Showcases · Release Readiness · Update Notes · Community · Product Vision · Dashboard

Keep the loop moving. Keep the judgment human.

How It Works

Under the hood, LoopX keeps objectives, gates, todos, claims, scopes, evidence, run history, quota, and human decisions in one compact layer. Product surfaces fold those mechanics into five questions a user can act on: what is the objective, what is next, what needs human judgment, what evidence changed, and whether the loop can be handed back to the agent.

Short answer: LoopX is not another executor. Codex /goal, Codex App automation, CLI scripts, cron jobs, or a human-visible TUI can trigger the next executor loop; LoopX keeps the objective, gate, evidence, quota, and handoff contract stable across those turns.

objective / issue / project
   │
   ▼
LoopX state: objective + gates + todos + scope + evidence + quota
   │
   ├─ human judgment needed? ── yes ─▶ ask / wait with a concrete user todo
   │
   ├─ safe fallback available? ──────▶ run a bounded agent slice
   │
   ▼
Codex / Claude Code / Cursor / shell agent executes one loop
   │
   ▼
write evidence + handoff + next todo ─▶ quota decides the next tick
Layer Role
Codex / Claude Code / Cursor Execute a bounded agent loop: read, write, run commands, and respond.
Task mode / automation / CLI scripts / TUI Trigger or schedule the next executor loop.
LoopX Preserve the dynamic loop state: gates, todos, run history, quota, evidence, boundaries, and handoff state.

The product promise is not "more todo lists." It is a practical foundation for loop engineering: keep human judgment at high-value decision points, keep safe fallback work moving when one lane is gated, and stop compute spend when a turn cannot produce a verified transition.

Put differently: LoopX lets a user's agent team keep working across tools, turns, and off-hours without turning the project into a pile of hidden scripts and stale prompts. The technical contract underneath that promise is explicit: agent identity, todo ownership, scope, capability gates, quota, evidence writeback, and public/private boundaries stay visible to the next turn.

LoopX 把一次静态目标变成能持续流转的动态 loop：该等人的地方明确等人， 不该空等的安全侧路继续推进，下一轮 agent 总能读到目标、边界、证据和交接。

LoopX control-plane board

Who Should Try It

LoopX is for people who already have an agent that can do useful work, and now need that work to continue without turning into stale chat memory.

Start here if you are running:

  • multi-day engineering, research, benchmark, or experiment objectives;
  • issue/PR fixing loops where the agent must preserve scope, evidence, and review state across turns;
  • recurring heartbeat or monitor-style agent work;
  • projects with owner/SOP gates, human reward judgments, or public/private boundary checks;
  • controller/side-agent workflows where todo ownership and handoff matter;
  • creator, research, or operations workflows where non-engineering users need agent progress translated into clear state, blockers, and feedback prompts.

LoopX is not an autonomous production controller. It is a local coordination substrate: dangerous permissions, publishing, production writes, and final ownership stay with the human/operator.

Quick Start

Requirements: Python 3.11+, curl, tar, macOS or Linux shell. Git is only needed for contributor clone/canary workflows. The Python package has no runtime dependencies outside the standard library.

Start agent-first: paste one setup message for the surface you already use, then start real work through the LoopX command entry for that host. Agents and host integrations can make this deterministic with loopx agent-onboard --list-agent-types, then pass an exact runtime such as codex-app, codex-cli, or claude-code. Ambiguous values such as codex are intentionally rejected because Codex App automation and Codex CLI /goal use different host-loop activation paths.

Choose your surface:

  • Codex App: best for a long-running agent that can wake up, re-check gates, and keep moving. Paste the setup message below, then invoke $loopx <complex task> or choose loopx from /skills.
  • Codex CLI: best when the visible TUI should stay primary while LoopX keeps the state. Run codex, paste the setup message, then invoke $loopx <complex task> or choose loopx from /skills; after todos are written, LoopX must activate the visible /goal <task_body> loop or show the exact pasteable gate.
  • Claude Code: best when Claude Code's native /loop should drive each tick. Install the opt-in adapter, run /loopx <task>, then /loop.
  • Manual shell / other agents: best when you want LoopX state without a supported runtime bridge. Install from the no-clone installer, then run loopx doctor and loopx bootstrap.

Command registration is host-specific, but the state path is not. Codex surfaces may expose LoopX through $loopx or /skills command facades before native /loopx exists; Claude Code can expose /loopx <task> after its opt-in adapter is installed. If a host command is missing, run loopx slash-commands for the current catalog or start the same agent-safe path from a shell with loopx start-goal --guided --project . --goal-text "<task>". Host and plugin integrations that need the lower-level handoff packet can still use loopx bootstrap-command-pack --project . --goal-text "<task>". Full routing and recovery details live in Getting Started and the host command registry contract.

Codex App

Best when you want a long-running or decentralized multi-agent workflow without hand-writing scheduler prompts. Paste this in the current project thread:

Connect the current project to LoopX.
Do not clone the LoopX repository for ordinary use. If `loopx` is not on PATH,
install or repair it with the official no-clone installer:
curl -fsSL https://raw.githubusercontent.com/huangruiteng/loopx/main/scripts/install-from-github.sh | bash
export PATH="$HOME/.local/bin:$PATH"

Then run `loopx doctor`. Work only from the current project root: if LoopX state
already exists, reuse it and do not create or overwrite a goal or the active objective; if the project
is not connected, prefer `loopx connect`, and use `loopx bootstrap` only when
project state clearly needs initialization. Ensure `.loopx/`, `.codex/goals/`,
and `.local/` are ignored. If this is Codex App, set the heartbeat automation to start at 3 minutes.
Automatically refresh it from the LoopX generated task body; do not ask me to
manually run `heartbeat-prompt`. Then stop and report the project connection
status, current user gate, top agent todo, and next safe action.

Then start a real E2E exploration in normal language:

$loopx Explore an LLM semantic rerank slice for a recommendation or search
system: build an offline eval set, implement a minimal candidate -> semantic
feature -> rerank -> eval path, add trace/cache/fallback/cost guardrails,
compare baseline vs treatment, and stop for production traffic, private data,
credentials, or AB/canary gates.

LoopX will plan before writing state, then create ordered P0/P1/P2 todos that make the algorithm, infra, validation, and human gates visible.

This Explore-style harness works best when the task has a measurable offline eval, baseline, treatment, and guardrail metrics. It is not recommended for open-ended tasks or scenarios where the evaluation metric cannot be quantified reliably, because the loop depends on comparable metrics to decide whether an exploration branch actually improved the result.

Example visible todos 
[P0] Build the offline eval set: samples, labels, baseline, metrics, leakage check.
[P0] Implement the vertical slice: candidate input -> semantic feature -> rerank -> eval.
[P0] Add infra guardrails: trace schema, cache/fallback, rate limit, latency/cost budget.
[P0] Ask before production traffic, private data, credentials, or AB/canary decisions.
[P1] Compare baseline vs treatment with effect, cost, latency, and failure cases.
[P2] Write the promotion handoff: canary evidence, rollback plan, and next experiment.

After that, each tick reads quota should-run: if a user gate blocks the chosen path, the agent asks a concrete question; if a safe fallback exists, it keeps working; if nothing material changed, it backs off or quiet-stops instead of spending compute forever. The agent may use heartbeat-prompt --thin internally to wire Codex App, but users do not need to run that command in the recommended path. After the 3-minute bootstrap cadence, Codex App cadence should follow quota should-run.scheduler_hint for backoff and reset-to-initial updates.

Codex CLI

Best when the visible TUI should stay primary. Open Codex CLI from your project repo:

cd /path/to/your-project
codex

Then paste one setup message:

Connect this repo to LoopX from this visible Codex CLI TUI. Do not clone the
LoopX repository for ordinary use. If `loopx` is not on PATH, install or repair
it with the official no-clone installer:
curl -fsSL https://raw.githubusercontent.com/huangruiteng/loopx/main/scripts/install-from-github.sh | bash
export PATH="$HOME/.local/bin:$PATH"

Then run `loopx doctor`. Work only from this project root: if LoopX state
already exists, reuse it and do not create or overwrite a goal or the active objective; if the project
is not connected, prefer `loopx connect`, and use `loopx bootstrap` only when
project state clearly needs initialization. Ensure `.loopx/`, `.codex/goals/`,
and `.local/` are ignored. Keep me in this TUI, do not use hidden headless
execution. Then stop and report the project connection status, current user
gate, top agent todo, and next safe action. After that I will start work with
`$loopx <complex task>` or the `loopx` skill from `/skills`. When that task
writes LoopX todos, generate the thin task body and set this visible TUI to
`/goal <task_body>`; if you cannot mutate `/goal`, show me the exact text to
paste instead of saying the loop is active.

That one message is the install, connect, and status check. The first useful TUI response should show the current objective, any concrete user gate, top todos, and next safe action. Hidden codex exec is not the default bootstrap path. Details for generated messages, later same-TUI automation, and proof capture live in Getting Started.

A successful connection looks like this:

  • loopx doctor passes;
  • the project has .loopx/registry.json;
  • the project has .codex/goals/<goal-id>/ACTIVE_GOAL_STATE.md;
  • loopx status shows who should act next;
  • Codex CLI has /goal <task_body> active, or the agent reported the exact pasteable gate for setting it;
  • local runtime state is ignored, not committed.

Claude Code

LoopX runs on Claude Code as native /loop + a LoopX control-plane MCP: the /loop runtime drives each tick and LoopX's should_run gates it. The adapter is opt-in and never writes ~/.claude unless you ask. Once enabled, drive it from Claude Code with /loopx <task> then /loop. Opt-in install, scope choice, the optional --harden gate, and uninstall are in loopx/claude_goal_mode/README.md.

Other Agents And Manual Shell

For Cursor, another terminal agent, or a manual shell, use the same no-clone installer. Be cautious with non-Codex agents: LoopX can only drive the agent path if that surface has at least one usable control hook, such as shell/CLI execution, a task command, an automation or heartbeat hook, or its own loop/scheduler. If the agent has none of those capabilities, LoopX can still track the project state, but the user must run the shell commands manually.

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

Then ask the agent to connect or run the command yourself:

cd /path/to/your-project
loopx bootstrap \
  --goal-id your-project-goal \
  --objective "Improve this project through bounded, verified segments." \
  --goal-doc GOAL.md

Advanced: Dynamic Workflow Scripts

For teams that already have their own agent runner, custom workflow runtime, tool harness, or multi-agent scheduler, LoopX can be used as the control-plane API inside that workflow. Your script or supervisor owns the executor loop; LoopX owns the state contract:

loopx quota should-run      # should any agent act now?
loopx todo claim/update     # who owns this slice, and what changed?
loopx refresh-state         # what evidence or blocker should the next turn see?
loopx quota spend-slot      # account for a completed automatic slice

This is the shape used by advanced showcases such as dynamic workflow orchestration: your agents can orchestrate external tools, devices, domain-specific runners, or side agents, while LoopX keeps goals, gates, todos, evidence, quota, and handoff state reviewable.

Clone-based install is only for contributors who want the live canary wrapper:

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

For the full install, diagnose, connect, heartbeat, dashboard, development, and command-reference workflow, read docs/guides/getting-started.md.

See It In Action

Want proof before reading the control-plane details? Start with the public manual, then use the short proof surfaces:

For more cases, open the showcase catalog. For a full presenter material, see the experimental features below.

Experimental Features

These paths are useful today, but they are intentionally kept below the core onboarding path while the first-run UX, safety defaults, and evidence contracts settle across more repositories.

Start With A Useful Loop

Use a preset to see LoopX's value before wiring up a full automation:

loopx doctor
loopx preset list
loopx preset show daily-triage
loopx start-goal --guided --project . --goal-text 'Run Daily Triage L1 for this repository: inspect LoopX status, active todos, open gates, stale signals, and next actions; write a compact report and ask before code edits or external writes.'

The preset output is read-only: it renders real /loopx, start-goal, quota should-run, and heartbeat-prompt command packets without writing project state, installing automation, editing docs, or opening PRs. When the project is connected, loopx ready-score --goal-id <goal-id> --agent-id <agent-id> gives a read-only readiness report for recurring loops.

Good first demos:

  • Daily Triage L1: a safe project digest from status, todos, gates, and the single next action.
  • Changelog Draft L1: a release-note draft grounded in merged work and PR links.
  • PR Watch L1: review/CI/merge-blocker monitoring without auto-merge.
  • CI Sweeper L2 and Dependency Sweeper L2: high-value opt-in fix lanes that start with dry-run or policy reports before any bounded patch attempt.

Auto Research One-Click Start

Auto research is the reference experimental preset for agent teams: the user provides one open question, the preset supplies research roles and seed todos, and the generic multi-agent kernel launches visible Codex CLI panes with frontier, quota, evidence, and takeover controls.

loopx auto-research "How should we evaluate whether multi-agent auto research creates value?"
loopx auto-research start "How should we evaluate whether multi-agent auto research creates value?" --execute

The first command renders the contract and next launch packet. The start command creates an isolated research frontier and launches the visible lanes; lane-authored evidence still has to be written back through LoopX state before the run can claim progress. See Auto-research command path for the full stop, attach, retry, and evidence boundary.

Explore Results And Harness Planning

For longer investigations, LoopX now has an experimental Explore Result Layer and Explore Harness path. The result layer records public-safe node/edge/finding events as an append-only exploration graph, then folds them into summaries, blocked-frontier views, Mermaid graphs, and optional operator sinks. The harness path reads that graph plus open todos and produces read-only branch or worker-lane plans.

loopx explore node --goal-id <goal-id> --title "Map the next frontier"
loopx explore finding --goal-id <goal-id> --title "Confirmed reusable contract" --node <node-id>
loopx explore summary --goal-id <goal-id>
loopx explore graph --goal-id <goal-id> --graph-format mermaid
loopx explore worker-branch-plan --goal-id <goal-id> --harness-profile generic

This is intentionally default-off. todo-branch-plan and worker-branch-plan only become active when the registered goal opts in through spawn_policy.explore_harness.enabled=true; even then they do not claim todos, acquire leases, start workers, mutate state, or spend quota. They emit request packets and suggested commands for a controller or human to execute through the normal LoopX lifecycle. See the Explore capability guide for the event model, per-goal gate, adaptive-resilient profile, and MoE router profile.

Review Agent Work

Use the management surface as a read-first experimental entry after a project is connected. It lets operators inspect connected projects, user gates, agent lanes, todos, and evidence before granting more control.

loopx serve-status --global-registry --port 8766 --limit 80
cd apps/presentation/dashboard && npm run dev

This path is intentionally conservative: CLI state remains the source of truth, browser writes require explicit local opt-in, and review signals stay separate from execution permission. See the intelligent management surface, project-level reward model, and 3-minute demo script.

Long-Running Agent App Paths

This is not replacing the first screen. It is an experimental entry point for users who already understand the control-plane idea and want to pick one useful LoopX capability today. Each path uses the same objective, todo, quota, evidence, and review contract, so users can feel the capability lift without learning a new control plane every time:

App path Start with Expected output User-visible lift
Issue / PR fix loop LoopX slash entry: Fix <github-issue-or-pr-url>
loopx issue-fix workflow-plan		 Branch-ready fix packet with repro, smoke result, remaining review owner, and PR-review-ready evidence. Review comments and issues become a closed loop instead of reminders humans must shepherd by hand.
PR-sized refactor loop LoopX slash entry: <refactor task>
loopx canary plan		 Reviewable slice list, validation notes, successor todo, and merge boundary. More merged changes without turning the next morning into a giant diff audit.
Research or experiment loop loopx auto-research start "<open question>" --execute
loopx ml-experiment preview --format json		 Hypothesis, source/evidence packet, replay or experiment boundary, and next validated question. Research becomes a resumable long-horizon loop, not just a one-off report.
Explore result / harness loop loopx explore node|edge|finding
loopx explore worker-branch-plan --goal-id <id>		 Public-safe exploration graph, blocked frontier, Mermaid/exportable projection, and default-off worker branch plan. Long-running exploration becomes inspectable topology and opt-in worker planning instead of hidden notes.
Multi-agent work routing LoopX slash entry: <task text>
loopx quota should-run
loopx todo claim		 Claimed agent lanes with scope, lease, next action, quota decision, and handoff state. Multiple agents can work in parallel without hiding ownership or stepping on the same todo.
Knowledge / workflow connector loopx connect
loopx lark-kanban
loopx value-connectors		 LoopX state projected into docs, boards, GitHub, or domain workflows while LoopX remains the source of truth. Existing work surfaces become agent-aware without copying private state into public artifacts.
P0 blocked -> safe fallback loopx quota should-run
loopx todo claim		 Kernel projection of the exact user gate, safe fallback todo, quota decision, and evidence boundary inside an active project loop. Less idle agent time while preserving human judgment on the blocked path.
Candidate: Claude implements + Codex reviews LoopX slash entry: <implementation task>
loopx todo claim
loopx review-packet		 Role-scoped implementer todo, reviewer verdict, verifier command, evidence packet, and next handoff in one LoopX state thread. A two-agent demo can show collaboration without making either runtime the source of truth.
Candidate: PR conflict resolution LoopX slash entry: Resolve merge conflicts for <github-pr-url> Conflict patch, semantic risk note, focused validation, and review handoff before merge. Less mechanical conflict work after high-throughput agent branches, with humans still judging risky merges.

Start through the host's LoopX slash-command entry point: $loopx or /skills in current Codex surfaces, /loopx where a host exposes native slash commands. The commands above are short entry points, not separate state systems: each adapter still writes into the same LoopX control-plane contract.

User Mental Model

LoopX has more kernel concepts than a user should have to think about every day. The product surface should collapse them into five questions:

User question Kernel objects behind it What the user should see
Objective objective state, scope What are we trying to move, and what is out of bounds?
Next step todo, claim, quota What small action can the agent or human take now?
Judgment user gate, boundary authority What needs human approval, route choice, or reward feedback?
Evidence run history, artifacts, validation Why should we believe the state changed?
Handoff active state, handoff packet Can the next agent turn continue safely, and from where?

The CLI keeps the full contract available for debugging. The dashboard and frontstage should start from these five questions, not from raw logs.

Why Loop Engineering Needs A Control Plane

Short agent tasks usually fail because the model makes a bad local choice. Long-running loops fail differently: state drifts.

Loop engineering often begins with a timer, a long prompt, a shell script, or a visible TUI session. That can prove the idea, but it is not enough for real work. Once the objective changes, the user gives feedback, an owner gate appears, or multiple agents touch the same repo, the loop needs shared state instead of chat memory.

After several runs, several projects, or several handoffs, the hard questions become:

  • What is the current objective, and what is explicitly out of scope?
  • Which owner decision, source document, run artifact, or benchmark result is the current authority?
  • What did the last agent run actually do, and how was it validated?
  • Which next action belongs to the human, and which belongs to the agent?
  • Which actions are safe read-only work, and which cross write, production, private-data, or publication boundaries?
  • How does human feedback survive into the next run?

LoopX makes those questions machine-readable enough for agents and legible enough for operators, so a loop can run longer without becoming less accountable.

The value model is broader than a single task score: LoopX aims to make a Loop Agent reviewable by output quantity, output quality, token cost, and user attention cost. See the project-level reward model for the conservative schema and benchmark boundary.

For a short version of the operating model, read Loop Engineering principles and pitfalls or the Chinese version.

What You Get

  • Lifetime goals: durable project intentions that outlive one chat thread, run, todo, or implementation plan. A lifetime goal does not grant open-ended autonomy: only the next bounded transition is executable.
  • User gates: concrete human decisions that stay visible instead of disappearing into chat.
  • Safe fallback: audited side paths that can continue when one lane is gated, without bypassing the gate.
  • Todo ownership: user and agent todos with claimed_by for multi-agent coordination.
  • Quota and steering: a guard that says whether an automatic turn should run, wait, ask the user, self-repair, or stay quiet.
  • Run history and evidence: compact append-only events for progress, validation, blockers, reward, benchmark results, and quota spend.
  • Read-first management surface: a local dashboard for project selection, todo search, agent lanes, user gates, evidence, and review signals.
  • Performance review: project-level value signals across output quantity, output quality, token cost, and user attention cost.
  • Public/private boundary checks: local scans and docs rules to keep raw private state, credentials, logs, traces, and benchmark material out of public artifacts.

Capability Surface

LoopX has grown beyond a single heartbeat helper. The useful mental model is a small control-plane kernel plus adapters that project the same state into agent, operator, and domain-specific surfaces.

Surface What it does Start with
Goal state and status Tracks active state, todos, claims, gates, evidence, run history, and first-screen attention. loopx status, loopx diagnose, loopx review-packet
Quota and interaction contract Decides whether a turn should deliver, ask the user, wait for evidence, self-repair, or stay quiet. loopx quota should-run, quota allocation
Agent runtime bridges Keeps Codex App heartbeats, Codex CLI TUI loops, Claude Code /loop, and generic worker bridges aligned with the same guard. loopx heartbeat-prompt, loopx codex-cli-bootstrap-message, loopx worker-bridge
Operator surfaces Renders compact project status for humans without making the browser the source of truth. loopx serve-status, dashboard, frontstage
External projections Projects LoopX todos and gates into collaboration surfaces while LoopX remains the state authority. loopx lark-kanban, Lark Kanban adapter
Domain adapters Packages repeatable work lanes such as issue fixing, content operations, value connector planning, ML experiment advice, and benchmark evidence. loopx issue-fix, loopx content-ops, loopx value-connectors, loopx ml-experiment, loopx benchmark
Governance patterns Captures recurring good/bad interaction shapes so new capabilities do not become one-off prompt branches. pattern catalog, state model

Every surface should answer the same core questions: what is current, who owns the next action, which decision is gated, what evidence changed, and whether the next agent turn is allowed to spend compute.

Community & Feedback

LoopX is still early. The most useful feedback comes from real long-running agent projects: where the control plane helped, where it felt heavy, and which user gates or handoffs still disappeared from view.

  • Use GitHub Issues for reproducible bugs, install problems, and feature requests.
  • Open PRs for docs fixes, showcase writeups, and small public-safe examples.
  • For Chinese-speaking early users, scan the Lark user group first for fast onboarding help, feedback loops, and showcase co-creation. Use the Lark developer group for implementation questions and contributor coordination. A WeChat group QR is available as a backup, but QR codes may expire; if one is stale, use Lark or open an issue to ask for a refresh.
LoopX Lark user group QR code
Lark user group 		LoopX Lark developer group QR code
Lark developer group 		LoopX WeChat user group QR code
WeChat group, may expire

Core Workflows

After a project is connected, LoopX should feel like a small operator checklist, not a second job. Start by asking your agent to diagnose the loop instead of debugging the control plane by hand:

Diagnose LoopX for this project end to end. Do not ask me to run shell
commands. Run loopx diagnose, tell me whether the project can
self-drive, what blocks it, the exact user/controller question if one exists,
and what you will do next.

For manual inspection, start with:

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

Common operator actions:

loopx todo add --goal-id your-project-goal --role agent --text "Run the next bounded validation slice."
loopx review-packet --goal-id your-project-goal
loopx refresh-state --goal-id your-project-goal

Domain-specific helpers such as issue-fix, content-ops, value-connectors, ml-experiment, benchmark, and lark-kanban are dry-run, projection, or advisory lanes by default unless an explicit execute flag or external permission is present.

Automatic turns should use the thin heartbeat prompt and treat quota as the source of truth:

loopx quota should-run --goal-id your-project-goal
loopx heartbeat-prompt --thin --goal-id your-project-goal
loopx quota spend-slot --goal-id your-project-goal --slots 1 --source heartbeat --execute

For shared-control-plane or agent-team goals, generate the automation with a registered identity, for example loopx heartbeat-prompt --thin --goal-id your-project-goal --agent-id codex-main-control --agent-scope "primary coordination". After configure-goal or the control-plane UI changes registered_agents or primary_agent, use the returned heartbeat_prompt_migration commands to refresh any installed Codex App automation body. Scheduler cadence updates should run scheduler_hint.codex_app.ack_hint.cli_args; current payloads use quota scheduler-ack-current, which re-reads the latest hint instead of making agents copy short-lived reset tokens.

The next_automatic_turn reported by quota plan is only an advisory scheduling hint: it chooses the highest-compute eligible goal, while operator-gated, focus-waiting, waiting, throttled, paused, and health-blocked goals stay out of the eligible lane.

For stalled control-plane repair, control_plane.self_repair.enabled=true lets quota should-run return a bounded decision=self_repair contract; missing policy defaults off. When the payload includes a gate_prompt or operator_question, the target heartbeat should proactively ask that concrete user/controller gate and do not call the turn "no new user action" while they remain open. Even after a bounded safe-bypass step, its report still has to list existing open user todos. When notify_user_on_open_todo=true, skip delivery work and quota spend for that blocker-push turn.

When should_run=false but safe_bypass_allowed=true, the heartbeat may still do one bounded read-only steering or analysis step. See docs/quota-allocation.md for the full allocation contract. After an automatic turn actually spends delivery compute, append one spend event. Do not append spend for quiet should_run=false skips, preflight failures, or pure dry-run previews.

Three rules matter in daily use:

  • surface concrete user gates instead of summarizing them as "waiting for owner";
  • safe fallback work may continue, but it must not bypass the gate;
  • append spend only after a validated writeback, not for quiet skips, preflights, or dry-run previews.

Optional surfaces such as the local dashboard, Lark Kanban, and domain helpers should make the loop easier to inspect, but LoopX remains the source of truth:

loopx serve-status --global-registry --port 8766 --limit 80
cd ~/loopx/apps/presentation/dashboard && npm install && npm run dev

Before publishing public docs or examples, keep the public/private boundary explicit:

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

More detail lives in Getting Started; contracts live in Status Data, Quota Allocation, and Public/Private Boundary. For the local UI, see the dashboard guide.

Product Vision

LoopX starts with AI coding, research, and benchmark loops because those workflows make state drift easy to see. The broader product direction is a dynamic goal control plane for any long-running agent work where humans need clear progress, gates, feedback, and recovery without reading raw logs.

The near-term open-source path is maintainer-first: help people manage agents that read issues, propose fixes, open PRs, resolve review feedback, run benchmarks, and keep evidence attached to the work. That path is valuable even before LoopX controls execution, because it gives maintainers a readable queue of goals, gates, todos, evidence, cost, and feedback.

The broader product shape is a Loop Agent: an agent with a relatively stable responsibility, a continuing stream of external signals, and a recurring need to prove that its output quality, cost, and human-attention footprint are improving. A Loop Agent could be a coding maintainer, an experiment optimizer, a research assistant, or a creator/operator assistant. LoopX is the control plane that keeps those loops reviewable before they become more autonomous. LoopX makes the "digital worker" idea operational: goals, gates, evidence, cost, and feedback stay reviewable over time.

A medium-term productization case is a creator-operator workflow: a non-engineering user asks an agent to track social-platform trends, map them to personal creative preferences, extract insights, draft content, and maintain a material library. The same control-plane shape applies: what happened, what is happening, where it is blocked, what comes next, and how user feedback changes the plan.

See Product Vision for the planned creator-operator case, non-technical status model, fake-data demo path, and feedback/boundary contract.

Documentation Map

Contributing

External contributors should start with CONTRIBUTOR_TASKS.md for public, claimable work and CONTRIBUTING.md for setup, validation, and boundary rules.

LoopX keeps local active goal state separate from the public repository: do not commit .loopx/, .codex/goals/, live ACTIVE_GOAL_STATE.md, raw benchmark traces, or private operator artifacts.

Before publishing docs or examples, run:

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

Current Status

LoopX is early. It is not a full agent platform and not an autonomous production controller.

The current milestone is a useful local substrate for goal state, run history, operator gates, human reward, structured todos, scoped claims, quota-aware heartbeats, read-only project maps, benchmark control-plane evidence, runtime bridges, collaboration projections, and a small multi-project dashboard.

The next milestones are a clearer maintainer workflow for issue/PR loops, stronger project and domain adapters, safer controller/sub-agent coordination, better benchmark-runner ergonomics, and a more polished management surface that maps kernel state into the five user questions above.

License

MIT. See LICENSE.

About

Lightweight loop engineering state kernel for long-running AI agent teams. Agent-loop agnostic across Codex, Claude Code, and other coding agents, with durable goals, quota-aware auto-wake, executable todos, evidence logs, and verifiable handoffs.

my.feishu.cn/wiki/CaL5wMk9ui17ngkWzeUcMlAYnZg

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • Python 92.7%
  • TypeScript 6.6%
  • Other 0.7%