Troubleshooting
Run codeloop doctor first. It validates the entire activation chain — global MCP config, agent rules, project config, runtime tooling (ffmpeg, adb, xcrun, simctl, screencapture, xdotool, xwininfo, PowerShell, Playwright) and backend reachability — and prints a one-line remedy for every failure. Almost every issue below is covered by the doctor output; this page is the symptom-first index.
Pre-flight self-test (0.1.49+)
Whenever CodeLoop “isn’t working” on a specific project, ask your agent to call codeloop_self_test as the FIRST step of the chat. It runs a fast, synthetic check of every critical pre-condition:
- Workspace exists on disk and is a directory.
codeloop_init_projecthas been run (.codeloop/config.jsonpresent).- Platform detection produced a known platform.
- Desktop-app honesty mode is correctly toggled. CodeLoop now treats WPF, WinForms, MAUI, Avalonia, WinUI, UWP, Electron, Tauri, React Native, and Flutter desktop projects as desktop-apps — capturing a screenshot without resolving the app’s window is refused rather than silently grabbing the IDE.
evidence.target_appis set when desktop-app mode is ON, socodeloop_launch_app/codeloop_capture_screenshotcan resolve a window.- The PNG decoder skip path is wired (corrupt PNGs become skip warnings instead of dragging design-compare scores to 0%).
- Coordinate translation round-trips on a synthetic high-DPI fixture — clicks land where the agent expects on Retina / 200%-DPI Windows / Linux GDK_SCALE displays.
The tool returns a structured pass/fail report plus a single next_step directive. Use it before reaching for codeloop doctor when the issue is project-shaped rather than environment-shaped.
Stale CODELOOP_PROJECT_DIR (0.1.49+)
When you rename or move a workspace folder, the absolute path baked into .cursor/mcp.json / .claude/settings.local.json at init time stops matching the new location. CodeLoop now logs a single one-line warning at MCP server boot:
[CodeLoop] ⚠ CODELOOP_PROJECT_DIR=/old/path is stale (path does not exist) — falling back to discovery. Re-run `npx codeloop init` from the workspace's current location to rewrite the pin.Re-running npx codeloop init from the new location rewrites the pin in place. No data loss; the existing .codeloop/config.json is preserved.
WPF / desktop hardening (0.1.50+)
codeloop-mcp-server@0.1.50 / codeloop@0.1.41 closes eight real CodeLoop-shaped gaps surfaced by a multi-day Photometry-DB E2E (Windows / WPF .NET 8) that 0.1.49 did not address. Every entry below has a regression test pinning the new behaviour.
| Symptom | Fix |
|---|---|
codeloop_interact with text: "Save Configuration" on a WPF window logs click at (undefined, undefined) and the click never lands. Same with role: "Button" / automation_id: "BtnSave". | H1 — UIA selector resolution. A new runners/uia_resolver.tswalks the UIAutomationClient tree from the app's main window and resolves automation_id > text (Name exact, then substring) > role (ControlType) to a screen-absolute (x, y) via GetClickablePoint() with BoundingRectangle centre as the fallback. The codeloop_interact click / double_click / right_click / hover handlers now call the resolver before executing, so passing a selector without explicit x / y works on Windows desktop. |
On a dotnet / WPF / WinForms / MAUI / Avalonia / Xcode desktop project, codeloop_gate_checkfails the depth gate’s upload_when_drop_zone minimum even though the project has no upload runner and the agent has no way to satisfy it. | H2 — conditional upload gate. gate_check.ts’s evaluateDepth now drops upload_when_drop_zone from the minimums when discoverySnapshot.upload_runner_available === false and emits a one-line note ("Skipped upload_when_drop_zone: no upload runner for <platform>") so the gate is never the reason a desktop project can't reach 94%. |
codeloop_design_compare reports a 0% match for a screen because it cross-run-matched the latest capture against a weak token-overlap reference from a different run instead of marking the screen as missing / skipped. | H3 — strict design-compare matching. design_compare.ts now hard-disables weak cross-run hits: when no strong reference exists for a screen and only a weak token-overlap match exists in another run, the matcher returns path: null and the screen is surfaced as skipped: true, severity: "low", skip_reason: "no strong reference for <screen> in run <id>" instead of poisoning the gate with a 0% score on the wrong reference. |
codeloop_capture_screenshot writes artifacts to C:\Users\<user>\artifacts\ when the agent omitted project_dir, so subsequent runs can’t find them. | H4 — default project_dir resolution. A new runners/resolve_project_dir.ts centralises the precedence ladder used by every capture / interact / record / replay handler: explicit param > active recording session’s project_dir > CODELOOP_PROJECT_DIRenv var > nearest walked-up .codeloop/config.json> the MCP server cwd. Artifacts now always land under the correct project root. |
codeloop_discover_screens returns an empty list on a WPF / WinForms / MAUI / Xcode / Electron / Tauri / Flutter-desktop project even when designs/ contains the reference PNGs. | H5 — desktop discover_screens. discover_screens.ts now scans designs/desktop/*.png and designs/*.png (including jpg / jpeg / webp, skipping viewport sub-folders) and emits one screen per file with source: "designs" and confidence: 0.9 for desktop platforms detected via .sln / .csproj / .xcodeproj / tauri.conf.json / Electron main field / Flutter desktop targets. |
codeloop_diagnose classifies error MSB3027: Could not copy "..." and MSB3021: Unable to copy file ... in use by another process as issue_unclassifiedwith a generic MSBuild fix-hint, so the agent doesn’t know to stop the running app and rebuild. | H6 — MSB3027 / MSB3021 patterns. diagnose.ts now ships dedicated patterns for both file-locked build errors. Category environment_failure, severity high, and the fix-hint is the deterministic Stop-Process -Name <app>; then re-run codeloop_verify shape so the agent's next step is unambiguous. The generic error MSB<n>: pattern explicitly excludes 3027 / 3021 so the specific fix-hint always wins. |
artifacts/runs/run_* from old sessions accumulates indefinitely. Worse, a corrupt PNG from a legacy run keeps poisoning design_compare even after H3. | H7 — codeloop doctor --prune-artifacts. The CLI doctor command accepts a new --prune-artifacts flag (with optional --older-than-days N, default 30, and --dry-run) that walks artifacts/runs/, identifies runs older than N days OR containing any unreadable PNG (validated via the same PNG-dim sniffing used by the design-compare skip path), prints a per-run reason, and rm -rf's them. Default behaviour is unchanged; you opt into the prune. |
On Windows / macOS / Linux, when codeloop_capture_screenshot / codeloop_start_recordingcan’t find the app window the error is just “App window not found” with no clue about what was open or what to try next. | H8 — structured WindowNotFoundError. window_manager.ts now exposes a findWindowIdDetailed path that returns { found: false, target_app, candidates: string[], next_step } when the four-step priority ladder exhausts. The capture handlers surface the candidates and next_step directly in the tool response, so the agent sees something like “App window not found for ‘Photometry DB’. Saw: ‘Photometry DB - dev’ (proc Photometry), ‘Cursor - PhotometryDB’ (proc Cursor). Set evidence.target_app to one of these literals, or run codeloop_self_test for guidance.” |
Full auto-loop & modal handling (0.1.51+)
codeloop-mcp-server@0.1.51 / codeloop@0.1.42closes eleven gaps that kept the loop from being “100% system-automatic” — see the plan summary below. Each entry has a regression test pinning the new behaviour.
| Symptom | Fix |
|---|---|
The agent forgets to call codeloop_verify after editing a file. The next tool call surfaces a green gate against stale code. | H1 — post-edit hooks. codeloop init now installs an afterFileEdit hook in ~/.cursor/hooks.json and a PostToolUse(Edit|Write) hook in .claude/settings.local.json. Both run a cross-platform script (sh on POSIX, ps1 on Windows) that prints a HARD directive into the agent context after every save. Debounced 5s; skips noise dirs (node_modules, artifacts, .git, …). Bypass via codeloop init --no-hooks or CODELOOP_SKIP_HOOKS=1. Two unavoidable manual Cursor steps remain: (1) flipping the MCP toggle on first install (Cursor consent prompt has no JSON / API form), and (2) clicking Approve on the very first tool invocation per workspace. Everything else is automatic. |
The agent skips codeloop_verify between edits. codeloop_gate_check later passes against an old run. | H2 — verify-staleness reminder. Every CodeLoop tool response (other than codeloop_verify itself, which has a 30s cooldown) now scans the project for source files newer than the last finished_at in artifacts/runs/run_index.json. When stale, the response prepends a HARD DIRECTIVE banning every other tool until codeloop_verify has re-run. |
On a multi-stack monorepo (.NET backend + React frontend, Django + Next.js, Tauri, Flutter + native plugins) codeloop_verify only runs the first stack detectPlatform picked up. | H3 — auto-promote scope:'full'. When the project carries signals from more than onestack and the caller didn't pass an explicit scope, runVerify auto-promotes to scope: "full" and surfaces the promotion in the run summary ([H3 auto-promoted scope:'full' — …]) so it's auditable. Explicit scopes are always honoured. |
An Electron / Tauri / React Native project shows screenshot_evidence: n/a in codeloop_check_workflow while codeloop_gate_check blocks on the same gate. | H4 — single source of truth for isUIProject. The check_workflow inline classifier and the gate_check helper now share the same module (tools/is_ui_project.ts), which understands flutter / web / xcode / android / dotnet desktop / Electron / Tauri / RN / Expo. |
| A Python (pytest / Django) or Rust (cargo) project reports "No verification checks could run for platform <…>". | H5 — Python + Rust runners. runPythonTests auto-detects pytest / Django manage.py / unittest, picks the right interpreter (python3 → python → py), and parses both pytest and unittest summary formats. runRustTests wraps cargo test --no-fail-fast and sums per- crate summaries across workspaces. Both are wired into the scope: "full" cascade for hybrid projects. |
codeloop_visual_review / codeloop_design_compare / codeloop_interaction_replay / codeloop_generate_dev_reportdon't show the init-hint or critical-floor nag on a fresh workspace. | H6 — withInitHint coverage. All four tools now wrap their responses in withInitHint so the version banner / update notice / critical-floor enforcement / staleness directive (H2) all fire consistently. |
| The auto-fix loop spins forever on a pathological failure, burning tokens. | H7 — server-side iteration counter. codeloop_gate_check increments gate_attempts (cap 15); codeloop_diagnose increments diagnose_attempts (cap 8). Source of truth: ~/.codeloop/loop-state.json (per- project map). Audit trail: per-run snapshot at artifacts/runs/<id>/loop_state.json. When the cap is reached gate_check forces recommendation: "escalate" and the response carries an escalated_reason that tells the agent to stop. Reset via codeloop doctor --reset-loop-state. |
You want to capture screenshots for every screen but looping codeloop_capture_screenshot is tedious and easy to leave incomplete. | H8 — codeloop_capture_all_screens. New batch tool that calls codeloop_discover_screens internally and fires captureScreenshot per screen into ONE run dir. Returns total_discovered / captured_count / failed_count plus a per-screen result list ready for codeloop_design_compare. |
An iOS / Android / Flutter project has Maestro flows under .maestro/ but codeloop_verifydoesn't run them. | H9 — Maestro in verify path. When the project has any of .maestro/, tests/maestro/, or maestro/ and the platform is xcode / android / flutter (or scope is full), runVerify now invokes runMaestroFlows alongside the native build. Skipped gracefully when the maestro CLI is not on PATH. |
The agent ignores a confirmation modal (Save? / Confirm delete / EULA / browser beforeunload) and the rest of the journey silently fails. user_journey_evidence blocks ready_for_review. | H11 — modal-aware interaction. Four layers: (1) cross-platform detector (runners/modal_detector.ts) — Windows UIA WindowPattern.IsModal, macOS AXDialog, Linux EWMH; (2) codeloop_interact action helpers stay aware of the modal-related action set; (3) every codeloop_interact response now appends a HARD POSTSCRIPT telling the agent to capture, inspect, and call codeloop_handle_modal if a modal is present BEFORE the next interaction; (4) the new codeloop_handle_modal tool with decision: confirm | cancel | dismiss | inspect translates the choice to a structured key press and logs it for the user_journey gate. The user_journey_evidence next_step message now explicitly calls out unhandled modals as the most-likely root cause. |
Stuck-modal recurrence closure (0.1.55+)
codeloop-mcp-server@0.1.55 / codeloop@0.1.46 closes the three remaining gaps in the 0.1.54 stuck-modal fix. Re-audit of Photometry-DB E2E #11 against the published 0.1.54 build revealed that the recurrence path could STILL bypass the cycle-issues channel: clicks without an intent tag never triggered E3 verification, raw codeloop_interact clicks (or raw Stop-Process) bypassed codeloop_handle_modal entirely so nomodal_close_failed entries got written, and the E4 binary check missed the actual publish/PhotometryDB-Beta/<App>.exe path it was built to catch.
| Symptom | Fix |
|---|---|
The agent issues coordinate-only clicks against a stuck dialog with no intent / descriptionfield. 0.1.54 E3 silently never fires because the close-keyword check requires intent. Workflow check explicitly flags “coordinate-only clicks without clear intent”. | F1 — verification on every desktop click. codeloop_interact now runs post-action detectModal on every desktop click / double_click / right_click / keystroke key=escape regardless of intent, tracks the modal description in an in-process per-app map, and writes a click_missed_targetcycle issue the moment the same description survives 2+ consecutive interactions. The signature is exactly the recurrence pattern from E2E #11. |
The agent skips codeloop_handle_modal and hammers the dialog with raw clicks for 5+ turns; or usesStop-Process directly. Pre-0.1.55 the cycle-issues channel had no producer for that path so cycle_issues_acknowledged passed trivially. | F3 — automatic modal_close_failed. At 3+ consecutive same-modal persistences a modal_close_failed entry is written automatically with strategies_tried: ["raw_codeloop_interact_clicks_or_escape_xN"]. The agent doesn't need to call codeloop_handle_modalfor the gate to know there's a stuck modal. |
| The H11 reminder is text-only (“BEFORE the next codeloop_interact call you MUST…”). The agent ignores it and keeps clicking. | F4 — HARD F4 directive on persistence. When the F1 tracker shows the modal has persisted across one or more interactions, the postscript upgrades from soft H11 to a HARD F4 line that names the specific modal description and points the agent at codeloop_handle_modal / codeloop_kill_modal_window. Tells the agent the cycle_issues_acknowledged gate WILL block ready_for_review if they keep ignoring it. |
codeloop_start_recording launches publish/PhotometryDB-Beta/Photometry DB.exe with stale DLLs but the 0.1.54 binary_freshness only checks publish/<appName>. The BINARY MISMATCH directive silently never fires for the actual recurrence path. | F2 — depth=1 walk under build parents. resolveBinaryPath() now walks the immediate children of bin/Release, bin/Release/net8.0-windows, publish, dist, out, and the standard Flutter / macOS / Linux build output dirs. Direct paths are still tried first; only when no direct match exists do we descend one level. Closes the actual recurrence path E4 was meant to catch. |
codeloop_generate_dev_reportresponse didn't carry cycle_issues in the report payload, so the agent's generated DEVELOPMENT_LOG.md could still open with “all gates green” even when issues had been recorded. | F5 — dev_report directive. The response now carries cycle_issues_summary, cycle_issues (full list with pre-rendered summaries), and a HARD cycle_issues_directive that requires the generated DEVELOPMENT_LOG.md to include a per-issue row under “Bugs Found & Fixed” with kind, summary, and resolution. Producing a clean “all gates green” report when issues exist becomes structurally impossible. |
Stuck modals + cycle-issue acknowledgment (0.1.54+)
codeloop-mcp-server@0.1.54 / codeloop@0.1.45 closes the failure mode where the gate accepted ready_for_review at 100% confidence even when three real recurrence-class issues happened mid-cycle and got buried in the dev log. Photometry-DB E2E #11 had a .NET 8 OpenFolderDialog that ignored every single-keystroke close attempt — the agent had to hard-restart the app to drain a stack of three modals — plus a bin/Release-vs-publish/Beta DLL mismatch and 31 silently absorbed failed clicks. None of it surfaced to the user.
| Symptom | Fix |
|---|---|
codeloop_handle_modal sends Escape, the .NET 8 OpenFolderDialog ignores it, and the agent has no fallback path. The dialog stack grows; the only recovery is hard-restarting the app. | E1 — multi-strategy close ladder. detectModal() now classifies the modal kind by ClassName (#32770, Shell_Dialog) + name pattern, and codeloop_handle_modal runs a 4-step ladder for modal_kind: "file_dialog": Escape → Alt+F4 → UIA InvokePattern.Invoke on the Close button → Win32 EndDialog(hwnd, IDCANCEL). Re-detects between steps. When all 4 fail it returns escalation: "kill_window_required" and the new codeloop_kill_modal_window tool sends PostMessage(WM_CLOSE) then TerminateProcess on the owning PID. |
The recording session has a stuck-modal cycle, the agent hard-restarts the app, the gate still returns ready_for_review, and the final summary opens with “All quality gates green” — the user never learns about the modal-close failure. | E2 — cycle_issues_acknowledged blocker. Tools now write structured entries to logs/cycle_issues.jsonl for modal_close_failed / app_restart_during_recording / binary_mismatch / click_missed_target / high_failure_rate. The new gate fails until every recorded entry has a sibling resolution OR the agent enumerates each one in its gate response. The C6 anti-rationalisation scan now ALSO bans “all gates green” / “everything looks good” boilerplate when unresolved issues exist. |
codeloop_interact dispatches a click cleanly, marks success: true, but the click missed the X close button on a stuck modal. The agent thinks the modal is gone and burns cycles trying to interact with what is really a still-blocked main window. | E3 — click-effect verification.When the agent's intent / description / purpose / step contains close / dismiss / cancel keywords (or the action is keystroke key="escape" on desktop), codeloop_interact re-detects the modal after a 500ms grace window. If the modal is still up the result is overridden to success: false with verification: "modal_still_present" and a click_missed_target cycle issue is recorded. |
The agent rebuilds bin/Release/App.exe but codeloop_start_recording launches publish/App-Beta/App.exe with stale DLLs from a previous build. The new XAML never loads and the recording captures pre-fix UI. Gate accepts the run. | E4 — binary-vs-source mtime check. codeloop_start_recording compares the resolved binary mtime against the newest source-file mtime. When the binary is older by 60s+ the response includes a HARD BINARY MISMATCH directive and a binary_mismatch cycle issue. Thecycle_issues_acknowledged gate then blocks ready_for_review until the agent rebuilds + re-records. |
dev_report action breakdown shows 27% of entries under action: undefined — the dev-report mixes interaction entries with replay-frame markers, console-error rollups, and runtime-log lines. | E5 — action classifier hygiene. dev_report and interaction_coverage.bucketOne()now skip entries that don't have a string action AND an object input_args; missing actions are coerced to "unclassified" so the breakdown stays honest. |
| The depth gate passes with 31 silently absorbed failed clicks because successful counts hit minimums; the agent gets no signal that its coordinates are missing their targets. | E6 — high-failure-rate warning. When failed / (failed + successful) > 0.10 (with at least 10 attempts), the depth gate appends a soft WARN line to its reason and writes a high_failure_rate cycle issue. The depth gate still passes if minimums are met; the cycle-issues gate forces the agent to acknowledge the warning before ready_for_review. |
change_coverage_evidence shows passed: truewith an empty reason. The agent has nothing concrete to cite in its summary and slips into “all gates green” boilerplate. | E7 — credit detail on PASS. The reason field now reads Credited X/Y manifest entries (>= 100% threshold). By kind: ui_element_added: 3, property_added: 2. Sample exercised: … so the gate response carries cite-able evidence even when the gate trivially passes. |
Stale-evidence rejection & decoder fixes (0.1.53+)
codeloop-mcp-server@0.1.53 / codeloop@0.1.44 closes the failure mode where the gate accepted a sibling-run recording from BEFORE the source change. Photometry-DB E2E #10 added Product Name + Product Code columns to the Luminaire export pipeline, never re-recorded after the edit, and the gate passed at 100% confidence on a 28-min-old video + 440-action interaction log + full CRUD arc — all from a sibling run that pre-dated the diff. Each entry below has a regression test pinning the new behaviour.
| Symptom | Fix |
|---|---|
npx codeloop doctor --prune-artifacts crashes on Windows with Error [ERR_MODULE_NOT_FOUND]: Cannot find module ... @codelooptech/shared/dist/templates/rules-version.js. | D1 — pinned shared dep range. codeloop@0.1.43 declared @codelooptech/shared: ^0.1.8, which let npx resolve to a 0.1.x version older than 0.1.22 that didn't ship dist/templates/rules-version.js yet. codeloop@0.1.44 + codeloop-mcp-server@0.1.53 both pin to ^0.1.22 so npx cannot resolve to a shared version missing the file. |
The agent edits source, never re-records, and codeloop_gate_check still passes at 100% confidence by accepting a video + interaction log from a sibling run captured 28 min before the latest edit. | D2 — evidence freshness. video_evidence, interaction_depth_evidence, user_journey_evidence, and interaction_replay_evidence now anchor the freshness check against the newest source-file mtime, not wall-clock now. A sibling-run recording captured BEFORE the latest edit fails as STALE with a Re-record AFTER the latest edit before re-gating directive. Closes the change-blind loophole that 0.1.52's manifest gate couldn't help with when an MCP server still ran 0.1.51. |
codeloop_design_compare reports “PNG decode failed for D:\…\designs\…png: unrecognised content at end of stream” for valid Windows-saved PNGs that open cleanly in Explorer / Preview / Photoshop. The user has to re-save 18 references via PowerShell System.Drawing.Bitmap.Save by hand to get the gate to pass. | D3 — three-stage decode. readPng() already retried with trimAfterIend for the PowerShell-screenshot trailing-bytes case (0.1.42). 0.1.53 adds a third stage: PNG.sync.read(trimmed, { checkCRC: false }) — pngjs is the strict outlier here, every browser / Preview / Photoshop ignores chunk-CRC mismatches when the inflate stream itself parses cleanly. Anything that survives all three stages is genuinely corrupt and skipped. |
A new codeloop-mcp-server version publishes to npm during an active agent session. The next 30 min of tool calls keep running on the older version because the update check only ran at server boot. | D4 — 15-min poll + lazy-kick. REFRESH_MS drops from 1 hour to 15 minutes and getUpdateInfo() fires a background fetch on every tool call when the cached info is older than the refresh window. A critical update lands within a few tool calls in the same session instead of waiting for the next IDE restart. |
codeloop_design_compare reports “All 18 design comparison(s) were skipped due to corrupt/truncated PNGs”when the actual root cause for 15/18 is “you haven't captured these screens yet”. The agent goes on a 30-min PowerShell re-encode hunt instead of calling codeloop_capture_screenshot for the missing names. | D5 — disambiguated skip reasons.The gate now splits skips into “reference PNG genuinely corrupt” (re-export from the design tool) and “no matching screenshot captured” (call codeloop_capture_screenshot). The dominant root cause is surfaced first so the agent acts on it; both counts and sample names appear in the per-screen note for auditability. |
Change-aware verification (0.1.52+)
codeloop-mcp-server@0.1.52 / codeloop@0.1.43 closes the change-blind failure mode that let the auto-fix loop reach 100% confidence on a recording session that NEVER exercised the new feature the agent just added. The Photometry-DB E2E #9 transcript shipped a new Product Code DataGrid column, a layout fix, and an EF migration column at 100% confidence with all 11 gates green having only run a 5-click navigation tour on an empty database. Each entry below has a regression test pinning the new behaviour.
| Symptom | Fix |
|---|---|
The agent ships a new feature, drives a generic navigation tour, and gate_check returns ready_for_review at 100% confidence — without ever exercising the new feature. | C1+C3 — change manifest + coverage gate. codeloop_verify now writes artifacts/runs/<run>/change_manifest.json built from a hybrid baseline (git diff <verified_sha>..HEAD+ uncommitted/ untracked files; falls back to mtime when there's no git). Per-file feature-shape parsers extract ui_element_added / property_added / method_added / migration_column_added / migration_table_added / layout_restructure entries from XAML / HTML / JSX / TSX / Vue / C# / TS / Dart / Swift / Kt / EF migrations / SQL DDL. The new change_coverage_evidence blocker gate cross-references every entry against the interaction log, screenshot filenames (incl. C7 anchors), replay frames, and build/runtime logs at a HARD 1.0 threshold (lower per-project via gates.change_coverage_evidence.threshold; method_added entries are implicit and credited automatically when the property they operate on is exercised). |
| The agent reads its plan, deliberates, then writes prose. The C3 gate fails with “0/5 manifest entries exercised”. | C2 — codeloop_plan_change_journey. Reads the most recent change manifest and emits a per-entry interaction script. Each step carries a verbatim target_change_entry field; the agent passes it on every codeloop_interact / codeloop_capture_screenshotcall so the C3 gate credits the correct manifest entry without fuzzy matching. The plan's preamble explicitly forbids typing into empty grids — seed first via codeloop_plan_user_journey's Create arc, a fixture script, or a pre-populated artifact. |
| The agent types into row 1 of an empty DataGrid. UIA never fires because the cell doesn't exist. The C3 gate marks the entry unexercised. | C4 — empty-state seeding enforcement. Every codeloop_interact response runs a heuristic that flags row/cell actions on a row-shaped manifest entry when no prior commit/seed action shows up in the recent log. When risky, the response appends a HARD seed-first directive listing three concrete options (Create arc / fixture script / pre-populated artifact) before the agent re-attempts the interaction. |
The agent claims tasks_completed: ["Add Stripe checkout"] but the diff has no Stripe code. | C5 — tasks_completed cross-check. codeloop_verify now accepts an optional tasks_completed array and fuzzy-matches every claim against the change manifest. Orphan claims (no matching diff) and orphan manifest entries (no claim) surface as warnings on the verify response so the agent can self-correct before gate_check. |
| The agent narrates “Comprehensive verification confirms ready for production; further interaction would be redundant” instead of driving the unexercised manifest entries. | C6 — anti-rationalisation directive. The continue_fixingpostscript ships a canonical FORBIDDEN list of rationalisation phrases ( “comprehensive verification confirms”, “further interaction would be redundant”, “grid is empty so can't test”, “declaring task complete despite”, etc). Pass recent_thinking on codeloop_gate_check and the gate scans it for specific matches and surfaces them by name so the agent stops repeating the rationalisation and acts on the per-gate next steps instead. |
| Several screenshots exist but the C3 gate can't tell which one corresponds to the new Product Code column. | C7 — target_change_entry anchoring. codeloop_capture_screenshot and codeloop_interact now accept target_change_entry. Screenshots get a deterministic --c7-<slug> filename suffix the C3 gate matches without fuzzy logic; interact args persist the value so the gate credits the correct manifest entry from the interaction log too. |
Init & auth
| Symptom | Fix |
|---|---|
codeloop_verify reports dotnet_build failed with MSB1011: Specify which project or solution file to use because this folder contains more than one project or solution file. | The workspace has multiple .sln files (e.g. App.sln + App-Dev.sln). Upgrade to codeloop@0.1.26 / codeloop-mcp-server@0.1.17 or newer — the runner now auto-picks the canonical solution (one matching the folder name, otherwise the non-Dev / non-Test variant). To pin it explicitly, add a dotnet.solution field to .codeloop/config.json: |
After npx codeloop init, the agent says “I don't have access to a codeloop_verify tool in this environment” . | Cursor requires a one-time consent click to enable any MCP server, and there is no JSON / CLI / deeplink way to flip that toggle — cursor://settings opens the wrong page (the VS Code style settings).
codeloop@0.1.26+, npx codeloop init already installs the global activation (~/.cursor/mcp.json, ~/.claude.json, ~/.cursor/rules/codeloop.mdc, ~/.claude/CLAUDE.md) so codeloop doctor goes green automatically — the MCP toggle is the only Cursor-side step that cannot be automated. Claude Code users have no manual step: Claude Code auto-loads ~/.claude.json on launch and the .claude/settings.local.json we write includes permissions.allow entries so codeloop tools are auto-authorized. |
| Does the MCP server auto-update in Claude Code too, or only Cursor? | Both. The MCP config we write to ~/.claude.json and .claude/settings.local.json uses the same npx -y codeloop-mcp-server@latest command as the Cursor config. Every time you restart Claude Code, it respawns the MCP server, npx re-resolves @latest against the npm registry, and the newest version is used — identical to Cursor's behaviour. You only need to update the hand-typed npx codeloop CLI manually (run npx codeloop@latest <cmd> when the banner prompts you). |
Doctor reports ffmpeg / Playwright / adb as missing. | From codeloop@0.1.27+, npx codeloop init auto-installs ffmpeg via the platform-native package manager (winget / Homebrew) and runs npm install -D playwright && npx playwright install chromium when the project is web. If auto-install fails (admin elevation declined, no package manager on PATH, etc.), the post-init banner prints the exact manual command. adb is intentionally left to the user — installing the Android SDK is multi-GB and rarely wanted unconditionally. To opt out of the runtime auto-install, pass --no-install-runtime to codeloop init or set CODELOOP_SKIP_RUNTIME=1. |
npx codeloop init says “ffmpeg installed via <package manager>” but npx codeloop doctor in the same shell still reports “ffmpeg not found on PATH”. | The same class of bug exists on every OS, just for different reasons:
codeloop@0.1.30+, doctor probes known install paths on every OS (Windows winget Links + package dirs, macOS /opt/homebrew/bin + /usr/local/bin + /opt/local/bin, Linux /usr/bin + /usr/local/bin + /snap/bin) so it reports “found at <path> — restart the shell” instead of a false negative. To force the running shell to see the new PATH:
|
doctor flags adb / Playwright / xcrun as missing on a project that doesn't actually need them. | From codeloop@0.1.30+, doctor is fully target-aware:
.sln files on macOS will skip all three (adb, Playwright, xcrun) — no false alarms. |
On Flutter, doctorused to skip the adb check even though I'm building for Android. | Fixed in codeloop@0.1.30. Flutter projects ship android/ and ios/ subdirs by default (created by flutter create), so doctor now reads those subdirs and only skips the platform-specific checks for platforms you actually opted out of. If you ran flutter create --platforms web my_app, adb and xcrun are correctly skipped because there's no android/ or ios/ directory. |
In Claude Code, the agent keeps asking permission to run npx codeloop ... commands. | This means .claude/settings.local.jsonin your project either doesn't exist or lacks the required permissions.allow entries. npx codeloop init writes both the mcpServers.codeloop block and an allow list that includes Bash(npx *), Bash(node *), etc. From codeloop@0.1.30+, codeloop doctor now explicitly checks this file and reports “mcpServers.codeloop configured + permissions.allow includes npx” when healthy. If the row shows a yellow !, re-run npx codeloop init to regenerate it. |
npx codeloop doctor still prompts to update the CLI itself, even after a fresh npx codeloop@latest init. | The MCP server config we write uses codeloop-mcp-server@latest, so the long-running MCP process picks up new versions on every Cursor restart. The CLI binary itself, however, is cached by npx per major version — running npx codeloop doctor reuses the cached0.1.xtarball until it's invalidated. From codeloop@0.1.28+, every CLI invocation hits the npm registry once every 6 hours (cached at ~/.codeloop/version-cache.json) and prints a one-line “Update available” banner when a newer release exists. Run npx codeloop@latest <command> once to flush the npx cache and pick up the new version. Set CODELOOP_SKIP_UPDATE_CHECK=1 to disable the probe entirely. |
You shipped a fix to codeloop-mcp-server but users still see the old behaviour. | From codeloop@0.1.27+, the MCP entry written by npx codeloop init uses npx -y codeloop-mcp-server@latest so every Cursor / Claude restart re-resolves the latest dist-tag — users get patches automatically without re-running init. To pin a specific version (for reproducible CI), edit .cursor/mcp.json and replace codeloop-mcp-server@latest with codeloop-mcp-server@<version>. |
cd Photometry DB (or any path with spaces) returns No such file or directory / cannot find path. | Wrap paths with spaces in quotes: cd "Photometry DB". The shell otherwise treats each word as a separate argument. Same on macOS, Linux, and Windows PowerShell. Tab completion (press Tab after typing a few letters) auto-quotes the path for you. |
On every Cursor startup you see CodeLoop could not write Cursor User Rules automatically (Unable to write to User Settings because cursor.rules.userRules is not a registered configuration.). | You have the broken cursor-extension@0.1.0 installed (still on the marketplace at time of writing). Run npx codeloop@latest install-cursor-extension once and quit + reopen Cursor. The CLI installs the bundled 0.1.1 VSIX over the broken one with --force; the new version writes .cursor/rules/codeloop.mdc silently and never touches Settings. Requires codeloop@0.1.22 or newer (run npx codeloop --version to confirm). See Cursor extension. |
codeloop init creates files but Cursor does not show MCP tools. | Restart Cursor. Confirm .cursor/mcp.json contains a codeloop entry; if not, re-run codeloop init. See Cursor setup. |
codeloop_init_project is the only tool that fires. | Always-on activation hasn't been registered. Run codeloop install-cursor-extension or paste the User Rule manually under Cursor settings. See Cursor extension. |
npx codeloop auth opens the browser but never receives the key. | A local firewall is blocking the loopback callback port. Use codeloop auth --no-browser to fall back to email / password prompts. |
codeloop statussays "not authenticated" but you have CODELOOP_API_KEY set. | Confirm the env var is exported in the same shell and is a real key (cl_live_…, cl_test_… for local development). On macOS / Linux add it to ~/.zshrc; on Windows use setx CODELOOP_API_KEY. |
Verify
| Symptom | Fix |
|---|---|
codeloop_verifysays "project not initialized". | Call codeloop_init_project (MCP) or npx codeloop init (CLI) first. Or set CODELOOP_PROJECT_DIR to the absolute project path. |
| Verify never finds tests on a Python / Ruby / Rails project. | Add a plugin entry — see Plugin SDK. |
Web project verify skips Playwright. doctorsays "Playwright Chromium not installed". | npx playwright install chromium --with-deps. |
Screenshots & video
| Symptom | Fix |
|---|---|
codeloop_capture_screenshot returns captured: false. | Wrong app name, multi-monitor mismatch, or missing OS permission. On macOS grant Screen Recording + Accessibility to your terminal / IDE. |
| Recorded video is 0 bytes or under 1 KB. | ffmpeg cannot capture. On Linux make sure XWayland is enabled and ffmpeg has x11grab support. On Windows make sure no group policy blocks gdigrab. |
codeloop_interaction_replaysays "ffmpeg not found". | Install ffmpeg per Cross-OS runbook. |
Gate check
| Symptom | Fix |
|---|---|
Gate returns continue_fixing but everything looks fine. | UI projects need both screenshots and video evidence. Run codeloop_capture_screenshot + codeloop_start_recording / stop_recording / interaction_replay before re-gating. |
Gate fails with design_compare_evidence. | Add references under designs/ or configure .codeloop/figma.json, then run codeloop_design_compare. Threshold is 0.85 by default — tune in .codeloop/config.json. |
codeloop_check_workflow says is_ui_project: false for my WPF / WinForms / MAUI / Avalonia desktop app, and the gate passes at 100% with no screenshots or video. | Upgrade to codeloop-mcp-server@0.1.18 or newer. The MCP server now inspects every .csproj for <UseWPF>, <UseWindowsForms>, <UseMaui>, Avalonia / WinUI <PackageReference> entries, and <OutputType>WinExe</OutputType>, and treats any match as a UI project. Steps 2 / 3 / 6 stop being n/a, and screenshot_evidence, video_evidence, and interaction_replay_evidencebecome blocker gates — so the gate can’t go green without real visual evidence. |
codeloop_diagnose returns repair_tasks: [] with confidence: 100 even though codeloop_verify failed. | Upgrade to codeloop-mcp-server@0.1.18 or newer. Diagnose now (a) recognises MSBuild (MSB####), C# (CS####), and NuGet (NU####) error codes, (b) classifies the “multiple .sln/.csproj at root” ambiguity as a config error, and (c) emits a critical “build failed but no pattern matched” fallback so an unclassified failure never reads as 100% confidence. |
codeloop_check_workflow keeps citing a stale, days-old run_ID for “Last run” even after a fresh codeloop_verify succeeded. | Upgrade to codeloop-mcp-server@0.1.18 or newer. Older builds read runs[length-1] (the oldest directory) while the run list was already sorted newest-first. Fixed to always pick the latest. |
codeloop_check_workflow / codeloop_design_compare picks up a phantom run like run_visual_v2 or run_test that has no real verify behind it. | Upgrade to codeloop-mcp-server@0.1.19 or newer. The run-list now requires the strict run_<timestamp>_<rand> shape and sorts numerically by the embedded timestamp — so ad-hoc seed directories never shadow real runs again. Lexicographic order previously placed run_v… before every numeric run because in ASCII v > 1. |
codeloop_design_compare returns 0/N match across every reference even though screenshots and references exist in the same project — or it silently resolves screenshots from a different run than the run_id I passed. | Upgrade to codeloop-mcp-server@0.1.19 or newer. Design compare now (a) accepts an explicit run_id parameter and honours it instead of defaulting to whichever run had any PNGs, and (b) the file-name matcher already accepts <screen>_<timestamp>.png (the default output of codeloop_capture_screenshot), so screenshots captured into the run you specified are actually picked up. If you still see “No screenshot found”, check that the file is in artifacts/runs/<run_id>/screenshots/ and starts with the reference name. |
codeloop_interaction_replayreports “No frames could be extracted from the video” on Windows or Linux, even though the MP4 plays fine in any desktop player. | Upgrade to codeloop-mcp-server@0.1.19 or newer. The Windows gdigrab and Linux x11grab capture pipelines now encode to libx264 + yuv420p. Older builds wrote BGRA frames into an MP4 container that desktop players read fine but ffmpeg’s own frame extractor (used by replay) could not decode. Re-record after upgrading — old MP4s captured by 0.1.18 and earlier still won’t replay. |
On Windows, codeloop_capture_screenshot / codeloop_start_recording / codeloop_interacttargets the wrong window (often the IDE) when more than one window’s title contains my app name. | Upgrade to codeloop-mcp-server@0.1.19 or newer. Window targeting on Windows now uses a priority ladder instead of the old loose MainWindowTitle -match substring: (1) exact ProcessName, (2) exact MainWindowTitle, (3) starts-with MainWindowTitle, (4) literal regex substring as last resort. Pass either the process name (e.g. Photometry DB) or the full window title — both work, and Cursor’s “Settings - <workspace>” title no longer wins. |
codeloop_gate_check goes green even though the recording was navigation-only — no typing, no form submission, no toggles, no real UX exercise. | Upgrade to codeloop-mcp-server@0.1.20 or newer. A new interaction_depth_evidence blocker gate tallies every entry in artifacts/runs/*/logs/interaction_log.jsonl across the project and requires real depth — by default input >= 3 (typing), commit >= 1 (form submission / save / login button), click >= 10 (interactive clicks that are not pure navigation), navigation >= 5, and total_successful >= 20. Pure navigation now FAILS the gate. codeloop_check_workflow step 7 shows the live bucket breakdown (e.g. click=14, input=1, commit=0) so the agent knows exactly which bucket to fill before re-gating. Override or relax per project in .codeloop/config.json under interaction_depth_minimums, e.g. {"interaction_depth_minimums": {"input": 5, "commit": 2}}. Disable entirely on read-only dashboards with {"interaction_depth_minimums": {"enabled": false}}. |
Even after codeloop-mcp-server@0.1.20, the depth gate keeps failing my WPF / mobile project —codeloop_check_workflow shows input=0, commit=0, toggle=0 even though I called win_ui_automate setValue/toggle/invoke or ran maestro_flow with N gestures. | Upgrade to codeloop-mcp-server@0.1.21 or newer. 0.1.20 persisted the wrong field names: win_ui_automate’s sub-action was read from input_args.action (never logged) so every UIA call bucketed as other; fill_form read input_args.fields while the runner actually logs field_count; sequence / maestro_flowchild steps weren’t logged at all so a 30-step Maestro flow counted as one other. 0.1.21 logs automation_action, per-step steps[] for sequence, and per-step maestro_steps[] for Maestro, and the classifier accepts every shape. Re-record on the new server and the depth buckets will fill in correctly. |
The agent stops at navigation-only on Windows desktop (WPF / WinForms / MAUI) — it never types into TextBox, never clicks a Button’s Save, never flips a ToggleSwitch. | Same fix — upgrade to codeloop-mcp-server@0.1.20 or newer. The depth gate accepts UIA actions: win_ui_automate with action: "setValue" counts toward input; action: "toggle" counts toward toggle; action: "invoke" on a control whose automation-id contains save, submit, login, update, apply counts as a commit. So a proper WPF exercise (set the Drive Current value, toggle AI mode, invoke the Save Configuration button) passes naturally. |
| The agent passes the depth gate’s default minimums (input≥3, click≥10, …) but still skips most of the app — no form filling on the photometric pages, no “AI Auto-Fill” clicks, no file uploads via the drop zone, no DataGrid cell edits, no license-key entry in Settings. | Upgrade to codeloop-mcp-server@0.1.22. The new codeloop_discover_interactions tool scans the project source (web .tsx/.jsx/.vue, Flutter .dart, WPF/WinUI/MAUI/Avalonia .xaml/.axaml) for every input, button (with submit/save hints), toggle, select, datagrid, file-drop zone, and AI feature, and the gate now enforces discovery-aware bars: input≥ 30 % of discovered inputs, ai_prompts≥ 3 substantive prompts when AI features are detected, upload ≥ 1 when drop zones exist, datagrid_edits≥ 1 when DataGrids exist. The defaults work for most projects; override per-app in .codeloop/config.json under interaction_depth_minimums.discovery_coverage. |
codeloop_interact rejects keystroke pagedown; invoke fails on a ToggleSwitch; scroll doesn’t drive a WPF ScrollViewer; sequence reports nothing about why a step failed. | Fixed in codeloop-mcp-server@0.1.22. Keystroke aliases now resolve pagedown / pageup / esc / return / arrowup / pgdn / bksp etc. to their canonical snake_case names. win_ui_automate invoke on a ToggleSwitch / CheckBox auto-falls-back to the Toggle pattern (Invoke and Toggle are mutually exclusive in UIA). scroll walks up to the nearest ancestor that exposes ScrollPattern so calls on a content element inside a ScrollViewer still scroll the viewer. sequence now accepts win_ui_automate, select_option, toggle, upload_file, navigate_back, and right_click as step actions and surfaces a per-step success / reason breakdown. |
| I want to verify the agent “really” toggled the switch / accepted the input on Windows — not just that the click happened. | codeloop-mcp-server@0.1.22 records post-action verification on every win_ui_automate call. The interaction log now includes a verified_state object with toggle_state (On / Off / Indeterminate), the readback value, is_enabled, and the resolved name. The detail field also surfaces the actual executed pattern (e.g. invoke auto-fell-back to toggle) so the agent can recover deterministically. |
| Where do CodeLoop’s verification logs live? I want to audit every tool call and its outcome. | codeloop-mcp-server@0.1.22 writes a structured event for every CodeLoop tool call (verify, diagnose, gate_check, capture_screenshot, start/stop_recording, interaction_replay, design_compare, visual_review, discover_screens, discover_interactions, generate_dev_report, check_workflow, interact) to artifacts/runs/<run_id>/logs/verification_log.jsonl. Each line has {timestamp, tool, input, success, duration_ms, run_id, output_excerpt, error} with API keys / tokens auto-redacted and string values truncated to 200 chars. codeloop_generate_dev_report reads this file so the DEVELOPMENT_LOG records exactly what ran when. |
On Windows, codeloop_capture_screenshot, codeloop_start_recording, and codeloop_interact (win_ui_*)silently exit with no output or report “Cannot find a window for <app>” even though the app is clearly running and the window title is correct. | Fixed in codeloop-mcp-server@0.1.23. Root cause was a shell-quoting bug in runCommand: every arg was naively wrapped in "..." on top of shell: true, but multi-line PowerShell scripts (used by the screenshot, recording, and UIA runners) contain inner " from [DllImport("user32.dll")]and window-title args — cmd.exe terminated the outer wrap at the first inner quote, so the child PowerShell received a truncated script. 0.1.23 introduces proper per-platform shell-escape (POSIX '...' with ' → '\''; Windows "..." with " → \" and trailing-backslash doubling) and additionally rewrites large powershell -Command <script> calls to powershell -ExecutionPolicy Bypass -File <tmp.ps1> so cmd.exe never sees the script body. After this fix, every Windows desktop adapter works end-to-end. |
codeloop_gate_check returns continue_fixing but the AI agent loops on verify → diagnose → verify forever because the failing gates are acceptance_criteria_met, interaction_depth_evidence, or design_compare_evidence— none of which another verify pass would fix. | codeloop-mcp-server@0.1.23 attaches a next_stepstring to every failing gate in the response’s evidence_summary, and the post-response auto-fix directive enumerates those steps one-by-one (“1. acceptance_criteria_met: write a regression test per uncovered criterion. 2. interaction_depth_evidence: call codeloop_discover_interactions then drive the missing buckets. 3. design_compare_evidence: re-capture using the reference filename or seed the populated state shown in the references.”). The agent now has a deterministic action per failure instead of generic “call verify again”. |
codeloop_design_compare reports actual_path: ""for every reference even though the captures clearly exist — usually because the captures live in a different run than the gate is scoped to, or are named 01-dashboard_<ts>.png while the reference is named dashboard.png. | codeloop-mcp-server@0.1.23 walks everyrun directory (newest first, preferring the gate’s run) and the matcher now accepts exact, prefix (dashboard_*), suffix (*_dashboard), substring, and 2-token-overlap matches — so 10-led-photometric-data-page_1778895588226.png correctly matches reference led-photometric-data.png. The result row annotates which run the actual was loaded from when it differs from the gate run, so the agent knows whether to copy the artifact forward or accept the cross-run match. |
codeloop_interaction_replayreturns “No frames could be extracted from the video” even though the MP4 plays fine in any player — typically the ffmpeg gdigrab/x11grabcodec didn’t produce keyframes the extractor can decode. | codeloop-mcp-server@0.1.23falls back to the run’s screenshots/directory when frame extraction returns zero. If the agent captured a screenshot per logical step during recording (the recommended “live screenshot model”), those captures are surfaced as framePaths in the replay response and satisfy the interaction_replay_evidence gate without re-recording. This makes per-step screenshot capture an officially-supported alternative to video frame extraction. |
codeloop_interact win_ui_automate with action: "toggle" fails on a WPF MahApps ToggleSwitch / Material.Avalonia switch with UnsupportedPattern. | codeloop-mcp-server@0.1.23 falls back to a coordinate click via TryGetClickablePoint() (then BoundingRectanglecentre) when the control doesn’t expose TogglePattern. The executed-action field in the log records toggle-via-click so the post-action verified_state readback still tells you whether the toggle actually flipped. |
The recording log shows lots of activity (input=20, commit=3, click=15) so the depth gate passes — but when you watch the video the AI just types "test"into one field, clicks Save three times, and never actually completes a human-like workflow. Reviewers complain the testing is “shallow” / “basic” and doesn’t actually verify the product’s logic. | codeloop-mcp-server@0.1.26 adds two pieces: (1) a new tool codeloop_plan_user_journey that combines codeloop_discover_interactions+ spec / README / docs mining to return a per-entity CRUD ARC SCRIPT (navigate → click Add → fill every discovered field with realistic example values inferred from labels — CCT=4000 K, CRI=90, Drive Current=350 mA, Email=test+codeloop@example.com — → Save → verify persisted → edit → save → delete); (2) a new blocker gate user_journey_evidence that walks the interaction log and requires at least 1 full arc (and delete / edit arcs when those controls exist in the source). Typing ‘test’ / ‘abc’ into numeric or unit-bearing fields then clicking Save thrice now fails the journey gate even when bucket counts look high — forcing the AI agent to drive the product like a human QA engineer. |
The design_compare_evidence gate is still counting against confidence even though the project has no designs/folder — or the references depict a populated state that the test database can’t match, making the comparison irrelevant rather than informative. | codeloop-mcp-server@0.1.27 hardens the skip-when-no-references behaviour and adds an explicit opt-out: (1) The gate is auto-skipped when no references exist — designs/ missing or empty, AND .codeloop/figma.json missing or declaring an empty frames: [] array. When skipped, it is NOT pushed to evidence_summary, NOT counted in the gate-denominator of the confidence score, and CANNOT lower it. (2) Users can force-skip the gate even when references exist by adding "design_compare": { "enabled": false } to .codeloop/config.json— for stale references, populated-state mismatches, or pivoted projects. The opposite is also available (enabled: true) to force the gate on in CI scaffolds before designs land. |
Dashboard & CI
| Symptom | Fix |
|---|---|
npx codeloop dashboard exits with EADDRINUSE. | Pass --port 4000 or set DASHBOARD_PORT=4000. |
| GitHub Action posts but never updates the badge. | Make sure publish-badge: true is set and the API key has badge permissions. See GitHub Action. |
| GitHub Action keeps timing out. | Increase the job timeout-minutes. The default verify + gate cycle on a medium project is 8–15 minutes. |
Still stuck?
Open an issue with the full output of codeloop doctor plus npx codeloop verify --debug at github.com/codelooptech/codeloop.