LoopX should feel like one product path before it feels like a CLI catalog. For a first-time user, the default surface is:
- Install or repair the CLI.
- Ask an agent to connect the current project.
- Use the host's LoopX command entry to start useful work.
The full command set remains available for operators and contributors, but it should not be the first thing a newcomer has to understand.
| Need | Use | Expected result |
|---|---|---|
| Check whether this project is connected and what is waiting. | LoopX status entry | The agent reads LoopX status, gates, todos, and next safe action without starting a new delivery path. |
| Start concrete long-running work. | LoopX task entry with <task text> |
The agent plans first, writes ordered todos, then advances one bounded, validated slice at a time. |
Examples:
$loopx fix the open PR review feedback and keep the patch reviewable
$loopx split this refactor into PR-sized slices and stop at unsafe gates
In current Codex surfaces, invoke the explicit loopx skill with $loopx or
choose it from /skills. On hosts that expose native custom slash commands,
the same task text may appear as /loopx <task text>.
LoopX preserves objective state, gates, todos, quota, and evidence. It does not replace the app or CLI that runs the next agent turn. Pick the driver that matches the surface you already use:
| Surface | Start with | What keeps it moving |
|---|---|---|
| Codex App | $loopx <task text> or /skills -> loopx in the project thread |
The app heartbeat automation. Let the agent install or refresh the generated LoopX heartbeat body; start at the bootstrap cadence, then follow quota should-run.scheduler_hint. |
| Codex CLI | codex from the project root, then paste loopx codex-cli-bootstrap-message --project . output |
Current verified Codex CLI builds do not load user-installed /loopx or /prompts:loopx commands. Keep the executor visible, then set the generated /goal <thin task_body>. |
| Claude Code | Install LoopX, then /loopx <task text> |
The installer registers lightweight slash-command skills. Enable the opt-in adapter only when Claude Code's native /loop should be gated by LoopX should_run. |
| Other agent or shell | loopx bootstrap-command-pack --project . |
A CLI, task, automation, heartbeat, or scheduler hook must run the next turn. If the surface has no such hook, LoopX can track state but the user drives it manually. |
Use this when an agent asks for the manual shell path, or when you are setting up a fresh terminal without an agent driving the first step:
curl -fsSL https://raw.githubusercontent.com/huangruiteng/loopx/main/scripts/install-from-github.sh | bash
export PATH="$HOME/.local/bin:$PATH"
loopx doctor
loopx slash-commands --install
loopx bootstrap-command-pack --project .The command pack is a bridge from manual shell setup back to the agent surface: paste the generated instruction into Codex, Claude Code, or another compatible agent that can run shell commands from the project root.
Keep these out of the first two commands, but do show them once a user has more than one LoopX project or agent lane:
| Need | Use |
|---|---|
| See the cross-project progress digest. | /loopx-global-summary |
| See only user or owner gates. | /loopx-global-gates |
| See runnable project-agent work. | /loopx-global-todos |
| See risks and blocked lanes. | /loopx-global-risks |
These are manager views. They should summarize and route work across projects; they should not replace the project-local LoopX task entry as the way to start useful work inside one repository.
| If you are trying to... | Use this surface first | Only then reach for... |
|---|---|---|
| Start project-local work | LoopX task entry with <task text> |
loopx bootstrap-command-pack --goal-text ... when manually bootstrapping an agent. |
| Understand several LoopX projects at once | /loopx-global-summary |
/loopx-global-gates, /loopx-global-todos, or /loopx-global-risks when you need a focused manager view. |
| Understand why work is paused | /loopx |
loopx diagnose --goal-id <goal-id> when the agent needs a deeper evidence packet. |
| Review a handoff or gate | The agent's LoopX status summary | loopx review-packet --goal-id <goal-id> for a copyable operator packet. |
| Operate recurring work | Codex App heartbeat or visible Codex CLI task body | loopx heartbeat-prompt --thin --goal-id <goal-id> when installing or repairing the loop. |
| Debug the control plane | The specific error or blocked todo | loopx status, loopx history, loopx quota should-run, or loopx check. |
The command catalog is reference material. Keep it useful, but keep it below the product path:
- New users should not need to scan every command before trying LoopX.
- Public examples should prefer the host's LoopX task entry unless they are teaching installation, debugging, or maintainer workflows.
- Contributors may still use the full command reference in Getting started.
- Installed users can run
man loopxorloopx commandswhen they need a grouped operator reference instead of the first-run path.