Quick Start

npx codeloop doctor

Verify it's working

1. Open a chat with Cursor or Claude Code in your project.
2. Ask: “Run codeloop_verify on this project.”
3. You should see structured JSON come back — tests passed, screenshots captured, gate score. That's it; CodeLoop is live.

From here on, the agent will call verify, diagnose, and gate-check on its own after every code change. You write code; CodeLoop keeps it green.

Alternative setup paths

Skip this section unless the three-command path above didn't suit you (corporate firewall, headless box, want to stay in the browser, etc.).

Path 1: Website Signup

1. Sign up at codeloop.tech/signup — no credit card required.
2. Copy your API keyfrom the post-signup screen (it's shown only once).
3. Set the environment variable in your shell:

   # macOS / Linux — add to ~/.zshrc or ~/.bashrc
   export CODELOOP_API_KEY="cl_live_your_key_here"
   
   # Windows PowerShell — set as user env var
   [System.Environment]::SetEnvironmentVariable("CODELOOP_API_KEY", "cl_live_your_key_here", "User")

4. Initialize in your project:

   cd your-project
   npx codeloop init

   This auto-detects your project type, creates the MCP config for Cursor or Claude Code, and sets up rule files.

Path 2: CLI Signup (Terminal-First)

Prefer doing everything from the terminal? No problem.

# Create your CodeLoop account
npx codeloop signup

# Follow the prompts: name, email, password
# Your API key will be displayed and saved automatically

# Then initialize in your project
cd your-project
npx codeloop init

Path 3: Browser Key Flow

Run codeloop auth from the terminal — it opens codeloop.tech/cli-auth, where you sign in (GitHub, Google, Apple, or email), confirm the request, and the browser hands a fresh API key back to the CLI over a one-time loopback callback. No copy-pasting, no environment-variable surgery.

# Open the browser-based auth flow
npx codeloop auth

# After approval, the key is saved to ~/.codeloop/config.json
# and codeloop status will show "authenticated"

Pass --no-browserto fall back to email / password prompts if you're on a headless box.

Path 4: Agent-Guided Setup

If your AI agent (Cursor or Claude Code) recommends CodeLoop during a coding session, you can set it up right from the integrated terminal:

# Run in the integrated terminal when your agent suggests CodeLoop
npx codeloop init

# If you don't have an account yet, init will offer to create one
# Just follow the inline prompts

Manual sanity checks (optional)

If you want to confirm the wiring before opening a chat:

1. Check MCP config exists:

   # Cursor
   cat .cursor/mcp.json
   
   # Claude Code
   cat .claude/settings.local.json

2. Look for CodeLoop toolsin your AI agent's tool list. You should see tools like codeloop_verify, codeloop_diagnose, etc.
3. Ask your agent: “Run codeloop_verify on this project” — the agent should call the tool and return structured results.

Optional: make it even more hands-off

CodeLoop already works after the three commands above. The two polish steps below remove the last bit of friction so the agent can run completely on its own.

Enable Auto-Run (Cursor users)

By default, Cursor shows a “Skip / Run” prompt for every terminal command the AI agent runs. This slows down the CodeLoop verification loop. To enable automatic execution:

1. Open Cursor Settings: Cmd+Shift+J (Mac) or Ctrl+Shift+J (Windows/Linux)
2. Go to Features > Terminal
3. Find “Auto-Run Mode”
4. Set to “Yolo” (runs everything automatically) or “Auto-Run with Allowlist” (safer — only auto-runs commands you approve)

This is a one-time setting. Once enabled, CodeLoop can run flutter test, npm install, git status, and other commands without manual approval.

Claude Code users: No action needed — codeloop init automatically configures permissions.allow in .claude/settings.local.json.

Always-on (across every future project)

Good news — this is now the default. Since codeloop@0.1.27, running npx codeloop init in any project also performs the global setup automatically: it writes ~/.cursor/mcp.json, ~/.claude.json, and ~/.claude/CLAUDE.mdif they're missing or out-of-date. So opening any future project in Cursor or Claude Code already has the MCP server registered.

If you want global registration without touching the current directory (e.g. on a fresh machine before you have any project), the explicit form still works:

npx codeloop init --global

Conversely, --skip-global on a regular initopts out of the global write — useful in CI or multi-tenant setups where ~/.cursor/mcp.jsonshouldn't be touched.

Claude Code — Fully Automatic

No extra steps required. codeloop init writes the global MCP config, the agent memory file (~/.claude/CLAUDE.md), and .claude/settings.local.json with permissions.allowentries that auto-authorize the CodeLoop tools. Every new project triggers CodeLoop with zero manual intervention — no toggle, no consent prompt.

Cursor — One Required Manual Step

Cursor requires you to paste a User Rule into Cursor Settings. This is a one-time setup that takes 30 seconds and ensures CodeLoop triggers automatically in every project:

1. Open Cursor Settings — press Cmd + , (Mac) or Ctrl + , (Windows/Linux).
2. In the left sidebar, click “Rules, Skills, Subagents”(or “Rules” in older versions).
3. Find the User Rules text box at the top of the page. Click inside it.
4. Paste the following rule (on a new line if you have existing rules):

   After EVERY code change, you MUST call codeloop_verify from the CodeLoop MCP server. If .codeloop/config.json does not exist, call codeloop_init_project FIRST. After verify: diagnose failures with codeloop_diagnose, fix, re-verify until codeloop_gate_check returns ready_for_review with confidence >= 94%. For UI projects: screenshots + video capture are MANDATORY. Never declare a task complete without passing codeloop_gate_check.

5. Click Save.

That's it. This User Rule is global — it applies to every project you open in Cursor, not just the current workspace. You only need to do this once.

Why is this step needed for Cursor?

Claude Code supports file-based global agent rules (~/.claude/CLAUDE.md), so CodeLoop can auto-configure them. Cursor stores its User Rules in an internal database — not in a file — so the only way to set a global rule is through the Settings UI. CodeLoop also uses MCP tool description hints and project-level rule files as additional reinforcement layers, but the User Rule paste is the most reliable method for always-on activation.

Per-Project Alternative (No Global Paste)

If you prefer not to set a global User Rule, run npx codeloop init inside each project. This creates a .cursor/rules/codeloop.mdc file that Cursor loads automatically for that workspace. The downside is you must run init in every new project.

Restart the MCP Server After Setup

After running codeloop init --global, restart the CodeLoop MCP server in Cursor to load the latest tool descriptors:

1. Open Cursor Settings → click “Tools & MCPs” in the sidebar.
2. Find the codeloop server in the list.
3. Click the restart button (circular arrow icon).

Then start a new chat— the current chat session won't pick up the new rules until you open a fresh conversation.

If something doesn't work

Run the built-in diagnostics — it's the single command we recommend before reading anything else:

npx codeloop doctor

Doctor checks every layer of the activation chain — global MCP registrations, agent rules, project config, network — and prints green checkmarks or actionable red fixes for anything missing. If it's green, CodeLoop is set up correctly.

Still stuck? See /docs/troubleshooting (symptom-first index).

You're done. Optional next reads:

• How the loop works — the mental model, if you're curious
• API key management — rotate keys, set env vars, security best practices
• Cursor setup — detailed Cursor-specific configuration
• Claude Code setup — Claude Code-specific setup
• Tool reference — all 29 MCP tools explained (you don't need to read this to use CodeLoop)