Configuration

Every CodeLoop knob is in a small set of files under .codeloop/ in your project root, plus a handful of environment variables. npx codeloop initseeds sensible defaults — this page documents everything you can change.

File layout

your-project/
├── .codeloop/
│   ├── config.json        # core config (this page)
│   ├── plugins.json       # custom CLI runners — see /docs/plugins
│   ├── figma.json         # Figma frame map — see /docs/design-compare
│   ├── sections.json      # multi-section state — see /docs/multi-section
│   ├── baselines/         # visual baselines — see /docs/visual-review
│   └── runs/              # local artifact directory (gitignored)
├── designs/               # local design references (optional)
├── .cursor/
│   ├── mcp.json           # auto-generated
│   └── rules/*.mdc        # auto-generated
└── .claude/
    ├── settings.local.json # auto-generated
    └── agents/*           # auto-generated

config.json — full reference

{
  "project_type": "auto",
  "runners": {
    "build": { "command": "npm run build", "timeout_ms": 60000 },
    "lint":  { "command": "npm run lint",  "timeout_ms": 30000 },
    "test":  { "command": "npm test",      "timeout_ms": 120000 }
  },
  "evidence": {
    "target_app": "Photometry DB"
  },
  "screenshots": {
    "enabled": true,
    "tool": "playwright",
    "base_url": "http://localhost:3000",
    "wait_for": "networkidle",
    "full_page": true,
    "viewports": [
      { "name": "mobile",  "width": 375,  "height": 812  },
      { "name": "tablet",  "width": 768,  "height": 1024 },
      { "name": "desktop", "width": 1440, "height": 900  }
    ],
    "urls": ["/", "/about", "/checkout"]
  },
  "visual_review": {
    "threshold": 0.02,
    "baseline_dir": ".codeloop/baselines",
    "ignore_regions": [
      { "screen": "home", "rect": [0, 0, 1440, 64] }
    ]
  },
  "design_compare": {
    "threshold": 0.85,
    "scoring": "weighted_lab"
  },
  "recording": {
    "enabled": true,
    "max_duration_ms": 300000,
    "fps": 30
  },
  "gate_check": {
    "min_confidence": 0.94,
    "require_all_tests": true,
    "allow_lint_warnings": true,
    "visual_severity": "warning",
    "design_severity": "warning"
  },
  "sections": {
    "enabled": false,
    "spec_file": "docs/specs/_master.md",
    "acceptance_dir": "docs/acceptance"
  }
}

Field reference

Deep-E2E journey — the e2e block

A full codeloop_verify on a UI project automatically runs the deep-E2E journey as its final phase: it boots the device or browser, launches the app, drives the planned interactions (Maestro labels on mobile, Playwright on web, CGEvent / user32 on desktop), and captures per-screen screenshots, video, and app logs. The e2e block in .codeloop/config.json controls every part of that launch-and-drive phase. All keys are optional — the defaults auto-detect the right target.

{
  "e2e": {
    "auto_journey": true,
    "target": "ios_simulator",
    "platforms": ["ios", "android"],
    "android_avd": "Pixel_8_API_35",
    "ios_device": "iPhone 16 Pro",
    "device_id": "emulator-5554",
    "boot_device": true,
    "web_url": "http://localhost:3000",
    "flutter_driver": false,
    "launch_timeout_seconds": 1800,
    "launch_stall_seconds": 180,
    "boot_timeout_seconds": 180,
    "ios_scheme": "MyApp-Staging",
    "ios_configuration": "Debug",
    "gradle_install_task": ":app:installDevDebug",
    "android_app_id": "com.example.myapp.dev"
  }
}

Per-OS toolchain setup for the journey lives in the macOS + iOS Simulator and Windows + Android emulator quickstarts. What works on which host OS is documented honestly in the compatibility matrix.

Platform recipes

Flutter

{
  "project_type": "flutter",
  "runners": {
    "build": { "command": "flutter build apk --debug" },
    "test":  { "command": "flutter test" },
    "lint":  { "command": "dart analyze" }
  },
  "screenshots": {
    "tool": "maestro",
    "device": "Pixel_6_API_33"
  }
}

Next.js / React

{
  "project_type": "nextjs",
  "runners": {
    "build": { "command": "npm run build" },
    "test":  { "command": "npx jest" }
  },
  "screenshots": {
    "tool": "playwright",
    "base_url": "http://localhost:3000",
    "urls": ["/", "/dashboard", "/settings"]
  }
}

Vue / Nuxt

{
  "project_type": "vue",
  "runners": {
    "build": { "command": "npm run build" },
    "test":  { "command": "npx vitest run" }
  }
}

Django / Rails / Go (via plugin)

For non-built-in stacks, use .codeloop/plugins.jsonto wire your existing CLI test runner into the loop. Plugins behave exactly like first-party runners — failures count toward the gate and surface in the dashboard.

iOS (Xcode)

{
  "project_type": "xcode",
  "runners": {
    "build": { "command": "xcodebuild -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'" },
    "test":  { "command": "xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'" }
  },
  "screenshots": { "tool": "simctl" }
}

Android (gradle)

{
  "project_type": "android",
  "runners": {
    "build": { "command": "./gradlew assembleDebug" },
    "test":  { "command": "./gradlew test" }
  },
  "screenshots": { "tool": "adb", "device": "emulator-5554" }
}

.NET / WPF

{
  "project_type": "dotnet",
  "runners": {
    "build": { "command": "dotnet build" },
    "test":  { "command": "dotnet test" }
  },
  "screenshots": { "tool": "powershell" }
}

Desktop-app mode (0.1.49+)

Whenever codeloop init detects a desktop UI framework, it sets evidence.target_app in config.jsonand every screenshot / video / interaction call from then on attaches to THAT process — not the IDE, not the primary monitor.

Frameworks classified as desktop-app projects (and therefore covered by this auto-protection):

• .NET — WPF, WinForms, MAUI, Avalonia, WinUI, UWP (anything with <UseWPF>true</UseWPF>, <UseWindowsForms>true</UseWindowsForms>, MAUI / Avalonia / WinUI SDK refs, or <OutputType>WinExe</OutputType>). Pure ASP.NET / Blazor Server projects are not considered desktop-app projects — they ship as web apps.
• Xcode — any iOS / macOS / tvOS / watchOS project.
• Android — any project with an AndroidManifest.xml or build.gradle(.kts) at the root.
• Node desktop wrappers — Electron (electron dependency), Tauri (@tauri-apps/cli), React Native (react-native), Expo (expo).
• Flutter desktop — any Flutter project with a windows/, macos/, or linux/ sub-target.

If the target app is not running when codeloop_capture_screenshot is called, CodeLoop attempts to launch it via launch_app. On Windows that includes parsing <OutputPath> and <BaseOutputPath> out of the picked .csproj, and a fallback to Get-StartApps for MSIX / Microsoft Store apps.

Run codeloop_self_testas your first MCP call on any new desktop project — it walks the auto-detection, target-app resolution, and PNG decoder paths in < 1 s and tells you exactly which preflight check would have failed.

codeloop_interact coords reference (0.1.49+)

codeloop_interact accepts a coords enum that tells the MCP server how to interpret x / y:

DPI awareness: window_bounds on the capture response now includes dpi_x and dpi_yfor high-DPI displays (Retina, 200 % Windows scaling, Linux GDK_SCALE).codeloop_interact applies the inverse factor in window and screenshotmodes so a click on a 4K monitor at 200 % lands at the right pixel.

Environment variables

Plugin configuration

Drop a .codeloop/plugins.json in the project root to wire any CLI test runner into the verify suite. See the full schema in Plugin SDK. Plugin entries appear next to first-party runners in codeloop_verify output and contribute to the gate score.

Multi-section configuration

Enable sections.enabled = true and create per-section spec / acceptance files. codeloop_section_status reads and writes the state machine; see Multi-section orchestration for the full lifecycle.

Design references

Two paths:

• Figma — .codeloop/figma.json + FIGMA_API_TOKEN env var. See Design compare.
• Local PNG — designs/<screen>/<viewport>.png. No credentials, no network.

OSS plan project marker

If you applied for the free OSS plan via /oss-application, your approval ties the API key to your repo. There is no per-project config to add — the backend resolves the plan from the key itself.

Self-host configuration

Point CODELOOP_API_URL at your stack and set CODELOOP_MODE=local. See Self-host runbook for the full Docker Compose env reference.

Next Steps

• Tool Reference — understand each tool's capabilities
• CLI reference — invoke any of these from the terminal
• Plugin SDK — wire any test runner into the loop
• FAQ — common questions