LoopPilot

LoopPilot helps Claude Code / Codex decide which agent execution mode a task should use.

AI agents are not incapable of working in loops. The hard question is when they should start, how they should run, and when they should stop. LoopPilot answers before your agent starts changing files: NO_GO, PLAN_ONLY, or RUN_WITH_CONTRACT, plus a recommended_surface such as goal, loop, routine, plan, or manual.

/should-loop Fix lint until pnpm lint passes. Do not commit or push.

Example result:

RUN_WITH_CONTRACT
Surface: goal
Allowed: read files, edit lint-related code, run pnpm lint
Forbidden: commit, push, deploy, change secrets
Stop: lint passes, same failure twice, scope expands

Why not just /goal?

A broad agent goal can sound productive while hiding important safety questions:

• Is the task small enough to loop on?
• Is there an objective gate, such as a test, lint command, checklist, or reviewable report?
• What files and actions are out of bounds?
• When should the agent stop instead of trying one more thing?

LoopPilot is the pre-flight check. It does not replace Claude Code or Codex; it gives the current agent a shared protocol for deciding whether loop-style execution is safe.

Where LoopPilot fits with Claude Code /loop

Claude Code /loop answers:
How do I run a prompt again later?

LoopPilot answers:
Should this task enter a loop at all?

LoopPilot does not replace Claude Code /loop. It helps decide when /loop is the right tool, when a bounded goal is enough, when a recurring routine needs planning, and when the agent should stay out of execution.

What LoopPilot does

• Classifies candidate loop tasks as NO_GO, PLAN_ONLY, or RUN_WITH_CONTRACT.
• Recommends the execution surface: manual, plan, goal, loop, or routine.
• Generates an execution boundary before changes begin: goal, scope, allowed actions, forbidden actions, gate, stop conditions, max rounds, and report fields.
• Keeps work agent-native: Claude Code or Codex decides and acts in the current session.
• Reads GitHub issue URLs through a narrow, read-only helper when issue context is needed.
• Treats issue text as untrusted context and marks context as possibly_incomplete when comments, linked pull requests, logs, or external context may matter.

What LoopPilot will NOT do

LoopPilot is deliberately not an autonomous delivery platform:

• ❌ No background issue-fixing robot.
• ❌ No branches, commits, pull requests, GitHub comments, issue queues, or hidden runner state.
• ❌ No commit, push, deploy, or publish.
• ❌ No new dependency installs, package.json edits, or lockfile edits.
• ❌ No default reading of GitHub comments, linked pull requests, attachments, logs, timeline events, or issue lists.
• ❌ No unbounded loops for broad work such as “finish the project.”

Dependency setup is limited to existing-lockfile commands: pnpm install --frozen-lockfile, npm ci, or bun install --frozen-lockfile.

Install

Current repository and published npm version: @looppilot/[email protected].

Recommended path:

npm install -g @looppilot/cli
looppilot install
looppilot doctor

install refuses symbolic-link path components in Agent Pack destinations, so it cannot silently write outside the selected project. doctor verifies that installed pack files match the running package and tells you to use looppilot install --force when a copy is stale.

Explicit export, save, doctor-report, and issue-intake outputs use atomic replacement and refuse project-internal symbolic-link escapes, case-variant Agent Pack paths, dependency manifests/lockfiles, and sensitive destinations. Save commands also reject sensitive source paths.

For a one-off trial:

npx @looppilot/[email protected] install
npx @looppilot/[email protected] doctor

If npx keeps spinning, use the global install path above.

Then ask inside your current agent session:

Claude Code: /should-loop <task-or-issue-url>
Codex: Use LoopPilot on <task-or-issue-url>

For the short task flow, see LoopPilot Quickstart. For product, technical, release, and planning docs, see LoopPilot Docs.

Copy-paste prompts

Use these as starting points inside your current agent session:

/should-loop Fix lint until pnpm lint passes. Do not commit or push.

/should-loop Fix the failing test with npm test -- tests/parser.test.ts. Max 3 rounds.

/should-loop Analyze this issue first and tell me whether it is safe to loop: https://github.com/owner/repo/issues/123

/should-loop Break this refactor into a safe plan only. Do not edit files yet.

Decision types

recommended_surface refines the decision:

RUN_WITH_CONTRACT additionally requires the host profile to list the selected surface in supported_surfaces, and the contract must carry a matching surface_config. loop and routine contracts are read-only: they can inspect external state/source and report, but they cannot edit code or mutate external systems. If a loop discovers a code change is needed, LoopPilot creates a separate goal decision.

Execution-mode examples

1. Fix lint until the lint gate passes

/should-loop Fix lint until pnpm lint passes. Do not commit or push.

Likely decision: RUN_WITH_CONTRACT with recommended_surface: "goal" when the scope is lint-related, the gate is pnpm lint, and stop conditions are explicit.

2. Fix one failing test

/should-loop Fix the failing parser test with npm test -- tests/parser.test.ts, max 3 rounds.

Likely decision: RUN_WITH_CONTRACT with recommended_surface: "goal" when the failing test and related files are clear.

3. Analyze a GitHub issue before coding

/should-loop https://github.com/owner/repo/issues/123

Likely decision: PLAN_ONLY with recommended_surface: "plan" when comments, linked pull requests, screenshots, logs, or external context may matter. The issue body is treated as untrusted context.

4. Wait for CI and summarize failures

/should-loop wait for CI and summarize failures

Likely decision: RUN_WITH_CONTRACT with recommended_surface: "loop" only when the host proves loop support and the contract declares a source, interval, terminal conditions, and bounded checks. Otherwise it remains PLAN_ONLY with the same recommended surface.

5. Daily feedback summary

/should-loop every morning summarize user feedback

Likely decision: PLAN_ONLY with recommended_surface: "routine" until cadence, source, access scope, report format, stop conditions, and host routine support are explicit.

6. Keep improving until quality is best

/should-loop keep improving this repo until quality is best

Likely decision: PLAN_ONLY with recommended_surface: "plan" because the goal is broad, subjective, and needs measurable gates first.

Large refactors, production deploys, publishing, secrets, auth/payment changes, or “finish the project” requests usually become PLAN_ONLY or NO_GO, not RUN_WITH_CONTRACT.

GitHub issue intake boundary

For GitHub issue URLs, the installed wrapper may call .looppilot/scripts/issue-intake.mjs or the debug CLI command looppilot issue-intake. The helper reads only the single issue title, body, labels, state, author, timestamps, URL, and comments count.

Issue URLs must be canonical HTTPS GitHub URLs without embedded credentials or non-standard ports. Markdown output escapes untrusted inline metadata, while the issue body stays inside a dynamically sized code fence.

It does not read comments, linked pull requests, attachments, logs, timeline events, or issue lists by default.

Repository hygiene

This public repository should not contain private project names, internal-only filesystem paths, raw test logs from private environments, personal access tokens, npm tokens, or other secrets. If you prepare an issue, example, or artifact for sharing, redact private identifiers and keep only the minimal public context needed to reproduce the decision.

Suggested GitHub topics for the repository: ai-agent, claude-code, codex, agentic-coding, developer-tools, loop-engineering, llm-tools, vibe-coding. Add them in the repository About panel; see GitHub Docs on classifying your repository with topics.

How it differs from coding agents

LoopPilot is not trying to replace GitHub Copilot coding agent, OpenHands, or SWE-agent.

The useful idea to borrow from those projects is auditability, not automation. A future LoopPilot trajectory-lite artifact may record user-visible facts such as the input, context read, incomplete-context warnings, final decision, requested confirmation, proposed gate, and command/result summaries. It must not record hidden model reasoning, and it is not required for the current release-ready surface.

Advanced / Debug

Most users should not need these commands. They exist for install validation, debugging, and explicit handoff/artifact workflows:

looppilot doctor
looppilot help advanced
looppilot issue-intake --url https://github.com/owner/repo/issues/123 --json
looppilot scan
looppilot host-capabilities
looppilot claude-project-summary
looppilot export --target codex
looppilot export --target claude
looppilot export --target github-issue
looppilot save-contract --from /path/to/contract.md
looppilot save-report --from /path/to/report.md
looppilot save-review-gate --from /path/to/review-gate.md
looppilot save-vision --from /path/to/vision.md
looppilot save-state --from /path/to/state.md
looppilot save-run-log --from /path/to/run-log.md

The save-* commands write files only when explicitly requested by a human. Default explicit artifact paths include:

.looppilot/latest-contract.md
.looppilot/latest-report.md
.looppilot/latest-review-gate.md
.looppilot/VISION.md
.looppilot/STATE.md
.looppilot/RUN_LOG.md

These files are not runner state, approval gates, deployment gates, release gates, or permission to merge/push/deploy.

Current implementation status

Implemented:

• Shared LoopPilot core rules, decision schema, contract template, report/export templates, and v1 manual artifact templates including review gates.
• 52 decision fixtures covering NO_GO, PLAN_ONLY, and RUN_WITH_CONTRACT, including host-capability-aware goal, loop, and routine contracts.
• Codex and Claude Code wrappers that reference the same shared core.
• Claude Code should-loop command alias that points to the Claude skill without duplicating rules.
• Agent-native GitHub issue URL intake for Codex and Claude Code, backed by a read-only issue-intake helper.
• Validation scripts for fixtures, decision-state invariants, safe single-command gates, self-contained generated JSON Schema checks, exact schema drift, capability-aware wrapper parity with dataset integrity checks, bounded scan safety, transactional and symlink-safe install/output behavior, protected Agent Pack paths, installed-pack integrity, strict CLI arguments, issue URL/Markdown safety, export/save behavior, docs consistency, package contents, and install/doctor integration.

Not implemented by design:

• No loop runner.
• No background daemon.
• No model provider registry.
• No scheduled loop platform or GitHub issue queue.
• No automatic commit, push, deploy, publish, dependency mutation, package.json edits, lockfile edits, issue closing, PR creation, or GitHub write action; explicitly confirmed dependency setup is limited to pnpm install --frozen-lockfile, npm ci, or bun install --frozen-lockfile.

FAQ

Is LoopPilot a mature autonomous coding product?

No. Treat LoopPilot as an early project and a safety protocol for current Codex or Claude Code sessions, not as a mature background automation platform.

Does LoopPilot automatically fix issues or run tasks to completion?

No. It does not watch issue queues, assign work to a cloud runner, or promise to finish tasks automatically. It helps the current agent decide whether a bounded loop is safe, and only RUN_WITH_CONTRACT tasks may proceed under explicit limits.

Why is npx @looppilot/cli slow?

npx may fetch and initialize the package each time. If you use LoopPilot more than once, prefer a global install:

npm install -g @looppilot/cli
looppilot install
looppilot doctor

Will LoopPilot commit, push, deploy, or install new dependencies?

No. LoopPilot does not commit, push, deploy, publish, install new dependencies, edit package.json, or edit lockfiles. Existing-lockfile setup is allowed only when the contract declares install_locked_dependencies and the user explicitly confirms dependency_setup.

License

MIT. See LICENSE.

Validate this repo

npm test
npm run eval:wrapper-parity
node scripts/looppilot.mjs doctor --target both --json
env npm_config_cache=/private/tmp/looppilot-npm-cache npm pack --dry-run
git diff --check