Tool Reference

CodeLoop provides 30 MCP tools that your AI agent can call. Each tool returns structured JSON results that the agent uses to make decisions.

codeloop_verify

The primary verification tool. Runs build, lint, tests, and optionally captures screenshots — all in a single call.

Parameters

Example Output

{
  "status": "fail",
  "build": { "passed": true, "duration_ms": 4200 },
  "lint": { "passed": true, "warnings": 3 },
  "tests": {
    "passed": 12,
    "failed": 2,
    "skipped": 0,
    "failures": [
      { "name": "AuthService.login", "error": "Expected 200, got 401" },
      { "name": "UserProfile.render", "error": "Missing required prop" }
    ]
  },
  "screenshots": {
    "captured": 3,
    "paths": ["screenshots/home.png", "screenshots/login.png", "screenshots/dashboard.png"]
  },
  "confidence": 0.72
}

codeloop_diagnose

Analyzes verification failures and produces categorized repair tasks, prioritized by severity.

Parameters

Example Output

{
  "issues": [
    {
      "category": "bug",
      "severity": "high",
      "description": "AuthService.login returns 401 for valid credentials",
      "file": "src/services/auth.ts",
      "line": 42,
      "repair_task": "Check password comparison logic in AuthService.login"
    },
    {
      "category": "type_error",
      "severity": "medium",
      "description": "UserProfile missing required 'email' prop",
      "file": "src/components/UserProfile.tsx",
      "line": 15,
      "repair_task": "Add email prop to UserProfile usage in Dashboard"
    }
  ],
  "priority_order": ["AuthService.login", "UserProfile.render"]
}

codeloop_gate_check

Performs a confidence-scored quality gate check. Returns pass/fail with a numerical confidence score. Gates enforce build, tests, screenshots, video evidence, and design match — the agent cannot declare done until all gates pass at the 94% threshold.

0.1.54+. New blocker gate cycle_issues_acknowledged: fails until every entry in logs/cycle_issues.jsonl (modal_close_failed / app_restart_during_recording / binary_mismatch / click_missed_target / high_failure_rate) has a sibling resolution OR the agent's gate response enumerates each one. The C6 anti-rationalisation scan also blocks “all gates green” / “everything looks good” phrasing when unresolved cycle issues exist.

Parameters

Example Output

{
  "passed": true,
  "confidence": 0.94,
  "checks": {
    "build": "pass",
    "lint": "pass",
    "tests": "pass",
    "no_regressions": "pass",
    "screenshot_evidence": "pass",
    "video_evidence": "pass",
    "design_compare_evidence": "pass"
  },
  "recommendation": "Section meets quality threshold. Safe to proceed."
}

codeloop_visual_review

Captures screenshots across multiple viewports and compares them against baselines for visual regression detection. Returns images as MCP ImageContent blocks so your agent's own vision model analyses them at zero additional cost.

Parameters

codeloop_design_compare

Compares the coded UI against a design specification — Figma export, reference image, or design URL. When Figma is configured via .codeloop/figma.json, it fetches frames automatically. A blocker gate (design_compare_evidence) prevents the agent from shipping until all viewports match within the design match threshold.

Parameters

codeloop_capture_screenshot

Captures an app window screenshot for visual review. Brings the target app to the front, takes a window-scoped capture, and restores your IDE focus afterwards.

0.1.49 hardening: on every desktop-UI framework (WPF, WinForms, MAUI, Avalonia, WinUI, UWP, Electron, Tauri, React Native, Flutter desktop), CodeLoop refuses to capture without resolving the named app window. If evidence.target_app is unset and no app_name is supplied, the call returns an error with a recovery directive instead of silently grabbing the IDE. The response also includes window_bounds.dpi_x / window_bounds.dpi_y and scaled_image_dims so codeloop_interactcan scale clicks correctly on Retina and 200 %-DPI Windows displays.

Parameters

codeloop_update_baseline

Promotes screenshots from a given run to become the new visual baselines for future regression detection.

Parameters

codeloop_interact

Performs UI interactions on the running app during a recording session. Supports 40+ actions across desktop (macOS, Windows, Linux), browser, Android emulator, and iOS Simulator. Must be used between codeloop_start_recording and codeloop_stop_recording for full interaction coverage.

Parameters

codeloop_start_recording

Starts a background window recording session. Records the target app's window with multi-monitor support, captures app logs alongside video, and handles platform-specific recording (avfoundation on macOS, gdigrab on Windows, x11grab on Linux).

Parameters

codeloop_stop_recording

Stops a background recording session. Finalizes the video file, saves captured logs, and restores IDE focus. Use codeloop_interaction_replay afterwards to analyze the recorded session.

Parameters

codeloop_record_interaction

All-in-one recording tool that combines start recording, interaction, and stop recording into a single call for simpler workflows.

Parameters

codeloop_interaction_replay

Analyzes a recorded video against an expected interaction flow. Extracts key frames as images, includes captured app logs, and returns MCP ImageContent blocks for your agent's vision model to verify the interactions visually.

Parameters

codeloop_section_status

Tracks progress across multiple project sections for autonomous multi-section development.

Parameters

codeloop_integration_check

Cross-section integration verification. Checks for regressions introduced by one section that break another, and reports per-section confidence.

Parameters

codeloop_replan

Detects spec drift and updates section states after changes to the master spec. Recalculates the dependency graph and re-queues affected sections for verification.

Parameters

codeloop_discover_screens

Static scan for routes and screens in your project. Returns discovered routes, navigation triggers, confidence scores, and file paths. Supports Flutter, web, mobile, Xcode, Android, and .NET projects.

Parameters

codeloop_capture_all_screens

0.1.51+. Batch-capture screenshots for every screen returned by codeloop_discover_screens. Pins all captures into a SINGLE run directory so a downstream codeloop_design_compare picks them up as a coherent set. Returns total_discovered / captured_count / failed_count plus a per-screen result list.

Parameters

codeloop_plan_change_journey

0.1.52+. Build a per-change-entry interaction plan from the most recent change manifest (produced by codeloop_verify). Where codeloop_plan_user_journey enumerates entity-level CRUD arcs across the WHOLE app, this tool is narrower: it only enumerates the steps the agent must drive to satisfy the new change_coverage_evidence gate for the features that just shipped in this change.

Each step carries a target_change_entry field — pass it verbatim on every codeloop_interact / codeloop_capture_screenshot call so the gate credits evidence to the correct manifest entry without fuzzy matching.

The plan's preamble explicitly forbids typing into empty grids / clicking buttons that empty-state UI hides; seed data first viacodeloop_plan_user_journey's Create arc, a fixture script (SeedDb.bat, dotnet ef database update,npm run seed), or a pre-populated artifact.

Parameters

codeloop_handle_modal

0.1.51+. Resolve a modal / dialog / overlay that has appeared during the recording session. Cross-platform detection (UIA on Windows, AXDialog on macOS, EWMH on Linux, [role="dialog"] on web). Use this whenever the post-interact [CodeLoop H11] directive nudges you to look for a modal — failing to handle a modal blocks every subsequent interaction, and the user_journey_evidence gate will block ready_for_review.

0.1.54+. The detector now classifies modals by ClassName + name pattern into file_dialog / confirm / alert / custom. When modal_kind is file_dialog and the decision is cancel or dismiss, the handler runs a 4-strategy close ladder: Escape → Alt+F4 → UIA InvokePattern.Invoke on the Close button → Win32 EndDialog(hwnd, IDCANCEL), with re-detection between steps. When all 4 fail the response includes escalation: "kill_window_required" and a HARD directive pointing at codeloop_kill_modal_window; the failure also writes a modal_close_failed entry to cycle_issues.jsonl so the new cycle_issues_acknowledged blocker forces the agent to surface the issue in its gate response.

Parameters

codeloop_kill_modal_window

0.1.54+. Last-resort escalation to kill a stuck modal that codeloop_handle_modal could not close with its 4-strategy ladder. ONLY call this when codeloop_handle_modal returned escalation: "kill_window_required".

What it does: (1) sends PostMessage(WM_CLOSE)to the specific HWND, (2) waits 2 s and re-detects, (3) if the modal is still up, calls TerminateProcess on the owning PID. After success you MUST call codeloop_stop_recording + rebuild + codeloop_start_recording again — the recording will be partial and the user-journey must resume from the start of the affected flow. Windows-only; macOS / Linux modal handling does not need this escalation.

Parameters

codeloop_check_workflow

Enforcement checklist before declaring work complete. Verifies that a verification run was performed, screenshots were captured, video recording with interactions was done, gate check passed, dev log was written, and interaction coverage matches discovered screens.

Parameters

codeloop_init_project

Bootstraps a project for CodeLoop. Creates .codeloop/config.json, agent rule files, MCP config, artifacts directory, and gitignore entries. This is the mandatory first call when CodeLoop has not been initialized in a workspace.

Parameters

codeloop_self_test

0.1.49+. Synthetic pre-flight diagnostic. Walks every critical CodeLoop precondition for the current workspace in < 1 s and returns a structured pass / fail report plus a single next_stepdirective. Run this as the FIRST MCP call on any new project — it surfaces project-shaped issues (missing init, unset evidence.target_app on a desktop app, broken PNG decoder, miscalibrated coordinate translation) before you waste a full verify run discovering them.

Checks performed:

• Workspace exists on disk and is a directory.
• .codeloop/config.json present (else suggest codeloop_init_project).
• Platform detection produced a known platform.
• Desktop-app honesty mode toggles correctly for WPF, WinForms, MAUI, Avalonia, WinUI, UWP, Electron, Tauri, React Native, and Flutter desktop projects.
• evidence.target_app is set when desktop-app mode is ON.
• The PNG decoder skip path classifies corrupt PNGs as skips, not 0 % matches.
• Coordinate translation round-trips through auto, window, screen, and screenshot modes on a synthetic high-DPI fixture.

Parameters

Example output

{
  "ok": false,
  "checks": [
    { "id": "workspace_exists",   "ok": true },
    { "id": "init_present",       "ok": true },
    { "id": "platform_detected",  "ok": true,  "value": "dotnet" },
    { "id": "desktop_app_mode",   "ok": true,  "value": "on" },
    { "id": "target_app_set",     "ok": false, "reason": "evidence.target_app is unset on a desktop-app project" },
    { "id": "png_decoder_skip",   "ok": true },
    { "id": "coord_translation",  "ok": true }
  ],
  "next_step": "Set \"evidence\": { \"target_app\": \"<window title>\" } in .codeloop/config.json so codeloop_capture_screenshot can attach to your app instead of the IDE."
}

codeloop_recommend_tool

Ranks third-party tools and services from CodeLoop's knowledge base for a given category, stack, and budget. Useful for choosing hosting, databases, email services, analytics, and other infrastructure.

Parameters

codeloop_recommend_action

A smart router that infers category and budget from project context, then returns relevant recommendations. Simpler than codeloop_recommend_tool for quick, context-aware suggestions.

Parameters

codeloop_generate_dev_report

Aggregates all runs, screenshots, videos, logs, and interaction data into a structured report. Outputs a mandatory prompt to write docs/DEVELOPMENT_LOG.md — a comprehensive development log with evidence from every verification pass.

Parameters

codeloop_release_readiness

Comprehensive release quality check that evaluates whether the project (or section) is ready for human review. Checks all sections, aggregates confidence, and provides a clear go/no-go recommendation.

Parameters

Example Output

{
  "ready": true,
  "overall_confidence": 0.91,
  "sections": [
    { "name": "authentication", "confidence": 0.95, "status": "pass" },
    { "name": "dashboard", "confidence": 0.88, "status": "pass" },
    { "name": "settings", "confidence": 0.90, "status": "pass" }
  ],
  "recommendation": "Project meets release criteria. Ready for human UAT."
}

codeloop_run_history

Query the run history for the current project — past verifications and their outcomes, with full lineage (commit, branch, section, parent run, prompt template version, config version) and pass/fail counts. Useful for confidence trends and finding the run that introduced a regression.

Parameters

codeloop_visual_attribution

Identify which commit, branch, and section introduced each visual diff. Walks the run lineage and per-screen baselines, then attributes every screenshot change to its source. Use when you need to trace a visual regression to the exact commit that caused it.

Parameters

codeloop_generate_spec

Generate a design specification from Figma design tokens. Reads.codeloop/figma.json, fetches the file via the Figma REST API, extracts colors, typography and spacing tokens, and writesdocs/specs/design_tokens.json plusdocs/ui_rules.md. The output is consumed bycodeloop_design_compare and the design_compare_evidence gate.

Parameters

None — driven entirely by .codeloop/figma.json and the FIGMA_API_TOKEN env var.

codeloop_list_env_presets

List available environment-normalisation presets used by codeloop_verify for reproducible runs: viewports (mobile_se, tablet_portrait, desktop_1920…), network throttling profiles (3g, 4g, wifi, offline), locale and timezone presets, simulator targets (iphone_15, pixel_7…), seed-data fixtures, and API mock/real/record modes.

Parameters

None — returns the full preset catalog.

codeloop_get_prompt

Retrieve a context-aware prompt template for the current stage of multi-section app development. The prompt manager has five layers:master_human (top-level framing for a new user goal),planning (translate master spec into an ordered build plan), section_implement (per-section build prompt with acceptance criteria), repair (constrained fix loop when verify or gate fails), and integration (cross-section verification at checkpoints).

Parameters

codeloop_list_prompts

List every prompt layer with id, description, and required variables. Call this before codeloop_get_prompt when you need to know which variables a layer expects.

Parameters

None — returns the full layer catalog.

codeloop_flush_usage

Drain the persisted offline usage queue and POST events to the CodeLoop backend. Use when the MCP server was running in self-hosted or local mode and the user has switched to cloud, or when a prior session had networking issues and queued events to disk (.codeloop/offline_queue.json).

Parameters

Next Steps

• Configuration — customize tool behavior
• Quick Start — get set up