Promptlane

LoopRelay

[English](README.md) | [한국어](README.ko.md)

Local continuity and evidence for long-running Codex and Claude Code loops.

• 🔁 Restores the selected session, worktree, branch, and compact-boundary

state without scraping private agent transcripts.

• 📍 Produces an evidence-backed continuation brief for the next Codex or

Claude Code session.

• ✅ Links prompts to passed, failed, blocked, or unknown outcomes instead of

treating a higher prompt score as success.

• 🧠 Promotes only approved, evidence-bearing lessons into local memory or an

AGENTS.md/CLAUDE.md patch proposal.

• 🧭 Detects recurring failure patterns across loops and asks focused questions

instead of rewriting ambiguous requests by default.

• 🧩 Gives non-binding agent/model guidance and lets the operator record the

chosen profile and raw-free outcome against the selected loop snapshot.

The canonical [feature inventory](docs/FEATURE_INVENTORY.md) lists every active, opt-in, validation-only, dormant, and reserved product surface.

Measured Engineering Usefulness

Current results are maintainer-run observational evidence, not a causal claim. They include 30 matched pairs across 5 task types. Human usability has 0 observed flows and is not part of this agent-native gate. The operator cohort has 8 observed runs; 3/3 combine a checksum-pinned clean install with a successful fresh MCP session across 2/2 client families, including 1/1 continuation-brief runs.

| Task type | Pairs | Baseline success | LoopRelay success | Delta | Conservative 95% bound | Input-token delta | Decision | | ------------------------------- | ----: | ---------------: | ----------------: | ------: | ---------------------: | ----------------: | -------- | | Ambiguity clarification | 6 | 83.3% | 50% | -33.3pp | -100..77.6pp | -8535.5 | Narrow | | Failure prevention | 6 | 0% | 100% | +100pp | -10.9..100pp | +1777.7 | Narrow | | Implementation continuation | 6 | 100% | 83.3% | -16.7pp | -100..94.2pp | +34913.2 | Narrow | | Release verification continuity | 6 | 100% | 100% | 0pp | -100..100pp | +42178.2 | Narrow | | Session recovery | 6 | 16.7% | 83.3% | +66.7pp | -44.2..100pp | -25189 | Retain |

Aggregate success moved from 60% to 83.3%, while actionability moved from 74% to 89.7%. Mean input-token cost changed by 11.1%. Cached-token and TTFV condition coverage are 66.7% and 66.7% respectively; missing values are not interpreted as zero. Matched pairs observed 0 blocker-bearing cases: 0 documented as remediated and 0 unresolved cases that block public readiness. The agent-native gate requires 3 qualified runs across 2 client families and 1 continuation brief. All 5 target task types meet the per-type minimum of 5 pairs. Decisions remain directional because this is maintainer-run evidence and the agent-native gate does not establish human usability. Because ordinary implementation continuation regressed, LoopRelay should not intervene by default in every coding task. Human usability remains unmeasured and the causal claim remains false.

This chart is generated from the committed raw-free matched-pair ledger, not hand-edited marketing data. It shows outcome quality and operating cost together, retains null and negative results, and displays INSUFFICIENT DATA until at least 30 pairs across 5 task types and 5 pairs per type exist. The study is observational; causal_claim always remains false.

pnpm evidence:usefulness

See the [raw-free pair ledger](reports/usefulness-pairs.json), [generated summary](reports/usefulness-summary.json), and [evaluation protocol](docs/ENGINEERINGUSEFULNESSVALIDATION2026-07-11.md). The [agent-native protocol](evaluation/usefulness/AGENTOPERATORPROTOCOL.md) does not invent unavailable human participants: it combines a clean, checksum-pinned candidate install with fresh Codex/Claude Code MCP sessions. The current validation-only [participant handoff](evaluation/usefulness/PARTICIPANTHANDOFF_07a3ba86.md) pins candidate commit 07a3ba86; its isolated clean smoke reached first value in 7.098 seconds (installation: 6.396 seconds) with zero raw-path hits. Human usability remains unmeasured and does not become an implied claim.

Sol-planned, Terra-executed reproduction

A separate Codex 0.144.1 cohort used gpt-5.6-sol to preregister the rubric before any outputs were observed and gpt-5.6-terra for both conditions. In five counterbalanced pairs, baseline passed 4/5 and LoopRelay passed 5/5. Mean TTFV was 47.4s versus 30.4s, mean input tokens were 85,171 versus 42,415, and human review preferred LoopRelay in four pairs with one tie. Two initial Terra calls hit model capacity and succeeded on retry; their end-to-end delay and friction remain recorded. This small fixture-reuse cohort is a cross-model reproduction check, not an independent-user or causal result, and is not mixed into the 30-pair GPT-5.4 aggregate.

See the [cross-model ledger](reports/usefulness-sol-terra-pairs.json) and [generated cross-model summary](reports/usefulness-sol-terra-summary.json).

Unseen real-repository tasks

The preregistered 10-pair threshold is complete and one post-threshold unseen pair brings the cohort to 11 across five task types. Strict success is 0% for baseline and 27.3% for LoopRelay; actionability is 52.7% versus 83.6%. LoopRelay averages 6.2s less TTFV, 2.8 fewer tools, and 87,199 fewer input tokens. Three failures improved, eight pairs remained failed, and human review preferred LoopRelay 8 times and baseline 3 times. This is directional maintainer-run evidence, not a causal or public-readiness claim. Every task-type interval still spans the full plausible range, and several failures came from read-only test startup or strict plan/outcome mismatch. Human usability remains unmeasured.

Evidence-based scope at N=11:

• retain: exact session/checkpoint recovery and focused ambiguity questions

when material decisions are absent from Git.

• narrow: failure prevention until a different case produces strict success;

the third case also remained fail/fail and added treatment cost.

• narrow: implementation continuation to tasks with a genuinely hidden

selected contract; a fully specified task received only overhead.

• narrow: release continuity to fact handoff only; sequencing remained 0/2.
• Keep all paths opt-in: shell-first agent onboarding produced retained sandbox

and non-interactive execution failures even though clean package install and live MCP paths passed.

The eleventh pair found a real concurrent lost-update risk in the new human evidence intake. Baseline and LoopRelay both scored 6/10 and failed; treatment was slower and used more tools without quality lift. A focused deterministic regression then reproduced the risk, and the intake now serializes the complete read-validate-append-replace section. Historical data-loss evidence remains in the ledger while the current open critical-blocker count is zero.

The first separate real-repository session-recovery pair was strict fail/fail: baseline selected a different valid backlog item, while treatment recovered the selected task but omitted secondary brief constraints. That failure led to a focused checkpoint brief that removed inherited project prompt diagnostics. On the baseline-first follow-up, position-swapped Sol review consistently scored baseline fail and LoopRelay pass. Treatment used 38.28s, 3 tools, and 140,520 input tokens versus 64.13s, 20 tools, and 326,993 for baseline. These two observational pairs are retained in the [real-task ledger](reports/usefulness-real-task-pairs.json); they are not pooled with synthetic cohorts and are too small for a general productivity claim.

A third real-task pair tested recovery from unsupported validation commands and pre-existing repository formatting drift. Both conditions missed the strict all-criteria threshold, but position-swapped Sol review scored the failure-prevention concepts 0/5 for baseline and 4/5 for LoopRelay, preferring LoopRelay in both orders. The result remains a formal fail/fail and motivated removal of a stale generic Node gate from explicit checkpoint briefs.

The fourth pair tested the ambiguous request to update “the latest usefulness graph.” Baseline asked about the result set and graph but omitted several reporting decisions; LoopRelay asked all six preregistered questions and withheld edits. Position-swapped Sol review scored LoopRelay 8/8 and baseline 4/8 to 5/8. At that four-pair checkpoint, strict success was 0% versus 50% and the graph correctly remained INSUFFICIENT DATA. See the [generated real-task summary](reports/usefulness-real-task-summary.json) for the current eleven-pair result.

The fifth pair tested the live release boundary. Both conditions blocked release and both failed the exact-fact rubric; LoopRelay recovered more evidence blockers but cost slightly more and omitted public-artifact absence facts. This exposed that safe checkpoint evidence refs were stored but not rendered in the brief. They are now included under a privacy-filtered Checkpoint Evidence section. The follow-up recovered every release fact and reduced rediscovery, but still inserted a final gate before the required version decision, so it remains fail/fail. Selected contracts now explicitly forbid fallback steps between stated actions. That ten-pair threshold aggregate was 0% baseline and 30% LoopRelay strict success; the current eleven-pair aggregate is reported above. Neither is a release authorization.

The seventh pair covered ordinary implementation continuation for this evidence pipeline. Baseline chose plausible but different command and flag names and broadened verification; LoopRelay recovered the exact focused plan and passed, but took 7.52s longer and produced more output/reasoning tokens. This supports exact selected-contract recovery, not a general speed claim.

The eighth pair was a distinct failure-prevention retrospective. Both conditions found the existing secret-detector fix but could not run Vitest in the read-only sandbox, so both formally failed. LoopRelay cut TTFV from 74.99s to 47.57s and input tokens from 597,654 to 127,648, but baseline found an additional browser-sanitizer drift and was preferred 7/10 versus 6–6.5/10. This negative result shows that shorter rediscovery can miss useful adjacent risk. The browser sanitizer and report-ledger privacy regexes were aligned by focused regressions after the run.

The ninth pair tested the ambiguous request to move to “the next public version.” Both conditions formally failed. Baseline inferred patch/minor candidates and proposed release steps before clarification. LoopRelay asked more of the required decisions and cut TTFV by 11.4s, but omitted an explicit changelog-content question and mislabeled 8/10 real tasks as users. Sol preferred LoopRelay while retaining score ranges of 1–2/5 versus 3–4/5. Before the final pair, four of five task types met the two-pair minimum.

The tenth pair deliberately supplied a fully specified test-only task. Both conditions produced equivalent minimal plans and both formally failed an outcome-oriented rubric that required edits despite the evaluation's no-edit boundary. LoopRelay added 15.55s, one tool, and 90,616 input tokens with no quality gain. Human review preferred baseline; the Sol preference changed with position. This is direct evidence against injecting LoopRelay into ordinary, fully specified implementation work.

Regenerate only the separate real-task artifacts without rewriting the 30-pair README result blocks:

pnpm evidence:real-task

After the npm package is published:

npm install -g looprelay
looprelay setup --profile coach --register-mcp --open-web
# then collect and continue a real coding-agent loop:
looprelay loop collect
looprelay loop brief

Until then, run the same first coach loop from a local checkout:

git clone https://github.com/wlsdks/looprelay.git
cd looprelay
pnpm install
pnpm setup
pnpm looprelay loop collect
pnpm looprelay loop brief

LoopRelay is the local continuity and evidence layer for long-running coding-agent loops. It records safe loop state from Codex and Claude Code, ties work to outcome evidence, prepares the next-session handoff, and turns approved lessons into reviewable memory or instruction proposals. The npm package, CLI, MCP server, hook command, plugin, slash namespace, and data directory all use the looprelay identity.

Use looprelay in scripts, terminal commands, MCP registration, and plugin commands. Claude Code slash commands are exposed under the active /looprelay:* namespace.

looprelay is the only public CLI identity; no compatibility alias is shipped.

It stores redacted prompts and safe loop metadata locally, indexes them in SQLite, and exposes recovery, continuation, outcome, memory, instruction, and failure-pattern evidence through CLI, MCP, and a local review workspace.

LoopRelay does not execute the coding loop for you. It is the layer that keeps the loop coherent and reviewable across disposable sessions and different agents. It is not a transcript scraper, hidden provider proxy, or merge bot.

This project is not affiliated with, endorsed by, or sponsored by Anthropic, OpenAI, or any other AI tool provider. Product names such as Claude Code and Codex are used only to describe compatibility.

First 3-Minute Continuity Loop

The first success is resuming real work without rediscovering the repository or repeating a failed approach.

For most users, the happy path is:

looprelay start --open-web
looprelay setup --profile coach --register-mcp --open-web
# During the installation session, record a safe task checkpoint immediately.
looprelay loop checkpoint --summary "Verify the empty-result boundary before changing code." --branch "$(git branch --show-current)"
# Copy the returned continuation brief into the next agent session.

Skip --open-web if you do not want the web workspace to open automatically on new agent sessions.

Only troubleshoot after that path fails:

looprelay doctor claude-code
looprelay doctor codex

If MCP registration failed, rerun the one-command setup first:

looprelay setup --profile coach --register-mcp --open-web

Manual claude mcp add / codex mcp add commands are only for advanced troubleshooting. setup --register-mcp is preferred because it uses the current CLI entrypoint; from a cloned checkout that means absolute Node + dist/ paths, so Codex does not depend on looprelay being globally available in PATH.

Open the local archive only when you want dashboard, search, history review, or export.

Status

LoopRelay 1.0.1 is the first stable public release line for local-first Claude Code and Codex loop memory workflows.

• Claude Code support: MVP path
• Codex support: beta adapter
• Local rule-based analysis preview: implemented
• Prompt Quality Score: implemented as a local deterministic 0-100 rubric
• MCP prompt scoring tools: implemented as a local stdio server
• Copy-based LoopRelay improvement drafts: implemented, including raw-free next request briefs
• Prompt Practice workspace: implemented as a local draft-and-score UI with

score history and outcome feedback that do not store draft text

• Transcript import: CLI only
• Anonymized export: web UI and CLI preview/job flow
• Benchmark v1: implemented as a local regression baseline
• English/Korean web UI: implemented
• External LLM analysis: no hidden provider calls from looprelay;

optional MCP agent rewrite/judge packets can enter the active user-controlled Claude Code/Codex/Gemini CLI provider session when requeste

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wlsdks
• Source: wlsdks/looprelay
• License: MIT

Install and usage instructions live in the source repository linked above.