Claude Code Setup

This page does one thing: get CodeLoop to trigger automatically, on every Claude Code session, in every project— without you remembering to ask. It takes about 60 seconds. Claude Code is actually easier to make always-on than Cursor because it reads CLAUDE.md files on its own, so there's no “User Rule” field to paste into.

Why this works without a “rule paste” step

Claude Code's memory model is two-layer:

• User memory at ~/.claude/CLAUDE.md — loaded on every session in every project. codeloop init --global writes the verify-diagnose-fix loop instructions here.
• Project memory at <repo>/CLAUDE.md— loaded only when you're in that repo. codeloop init writes richer per-project instructions plus the three specialised subagents here.

Both files are plain Markdown and you can edit them by hand. Run codeloop initagain at any time to re-sync them with the current best-practice template — it preserves your custom additions in a fenced block.

Prerequisites

• Node.js 18+ — run node --version to check
• Claude Code installed and working on your machine
• A CodeLoop API key — get one from the Dashboard or by running npx codeloop signup (14-day free trial, no credit card)

Step 1 — Set Your API Key

The MCP server reads your key from the CODELOOP_API_KEY environment variable. Add it to your shell profile so it persists:

macOS / Linux

# ~/.zshrc or ~/.bashrc
export CODELOOP_API_KEY="cl_live_your_key_here"

# Reload
source ~/.zshrc

Windows (PowerShell)

[System.Environment]::SetEnvironmentVariable(
  "CODELOOP_API_KEY", "cl_live_your_key_here", "User"
)

Step 2 — Configure the MCP Server

Automatic Setup (Recommended)

cd your-project
npx codeloop init

The init command detects Claude Code and creates all necessary files automatically:

Manual Setup

If you prefer to set things up manually, create .claude/settings.local.json in your project root:

{
  "mcpServers": {
    "codeloop": {
      "command": "npx",
      "args": ["-y", "codeloop-mcp-server"],
      "env": {
        "CODELOOP_API_KEY": "cl_live_your_key_here"
      }
    }
  }
}

Then copy the agent files and CLAUDE.md from the claude-toolkit templates.

Step 3 — Understand the Subagents

CodeLoop creates three specialised agent definition files in .claude/agents/. Claude Code uses these to delegate specific tasks:

codeloop-loop.md — QA Loop Runner

The main workhorse. This agent orchestrates the full verify-diagnose-fix cycle:

1. Calls codeloop_verify to run all checks (build, lint, tests, screenshots)
2. If anything fails, calls codeloop_diagnose to classify failures into categories with repair tasks
3. Fixes only the confirmed issues from the repair tasks
4. Re-verifies until everything passes
5. Calls codeloop_gate_check to produce a confidence score
6. Stops when confidence is ≥ 94% or escalates if blockers are found

codeloop-qa.md — Visual Review Specialist

Handles UI/UX verification by calling codeloop_visual_review and codeloop_design_compare. It captures screenshots of your running application, analyses them for visual regressions, and compares the coded UI against design reference images. Reports structured issues with severity levels, evidence, and fix suggestions.

codeloop-advisor.md — Infrastructure Advisor

Uses codeloop_recommend_tool to provide evidence-based recommendations for tools, services, and infrastructure. It analyses your project stack, budget constraints, and requirements to suggest the best options — always with reasoning and tradeoffs.

The CLAUDE.md File

Claude Code automatically reads CLAUDE.md from your project root on every interaction — similar to how Cursor reads .cursor/rules/ files. This file contains persistent instructions that tell Claude Code:

• When to call CodeLoop tools (after implementing or modifying any feature)
• How to handle the verification loop (verify → diagnose → fix → re-verify)
• When to stop — only mark a task complete when codeloop_gate_check returns confidence ≥ 94%
• When to escalate — after 8 failed repair attempts or when blockers are found

Available tools (29 total)

After setup, Claude Code has access to all 29 CodeLoop MCP tools, grouped here by what the agent uses them for. The full parameter reference for every tool lives at /docs/tools.

Example Workflow

Here is a typical session showing how Claude Code uses CodeLoop automatically:

You: "Add a password reset feature to the auth module."

Claude Code:
  1. Reads CLAUDE.md → knows to use CodeLoop after every implementation step
  2. Implements the password reset endpoint, email template, and route
  3. Calls codeloop_verify →
     Result: 2 test failures, 1 lint error
  4. Calls codeloop_diagnose →
     Repair tasks:
       - Fix missing import in reset-password.ts (lint)
       - Fix test assertion for expired token case (test)
  5. Applies both fixes
  6. Calls codeloop_verify →
     Result: all checks pass ✓
  7. Calls codeloop_gate_check →
     Result: "ready_for_review", confidence: 92%
  8. Reports: "Password reset feature implemented and verified.
     All tests pass with 92% confidence."

Multi-Section Project Example

You: "Continue building the app according to the dev plan."

Claude Code:
  1. Calls codeloop_section_status →
     Section 3 of 6 is "in_progress", integration_due: false
  2. Implements the remaining tasks for Section 3
  3. Runs the verify-diagnose-fix loop (as above)
  4. Calls codeloop_gate_check → confidence: 88%
  5. Calls codeloop_section_status → moves to Section 4
  6. ...continues through all sections...
  7. After Section 6, calls codeloop_release_readiness →
     "Release ready. All sections pass. 0 blockers."

Verify it's actually triggering

After the activation chain, do a 30-second smoke test so you know the loop is live before you start coding:

1. Start a newClaude Code session (existing sessions don't reload CLAUDE.md).
2. Type: “Add a one-line README. Then run codeloop_verify and show me the result.”
3. You should see Claude Code edit the file, then call codeloop_verify, then return structured JSON with passed, failed, and a path to artifacts/runs/<run_id>/meta.json.
4. From now on, Claude Code will call verify on its own — you will not need to ask.

If anything looks off, run npx codeloop doctor. It checks the API key, the global MCP registration, both CLAUDE.md locations, and Node version, and prints a fix command for whatever is broken.

Troubleshooting

Claude Code never calls codeloop_verify on its own

This is almost always one of three things, in this order:

• The global memory is missing. Check cat ~/.claude/CLAUDE.md— it should contain the CodeLoop loop instructions. If empty, re-run npx codeloop init --global.
• You're in an old session. Claude Code loads CLAUDE.md at session start; quit and start a new session to pick up changes.
• The MCP server isn't registered. Run claude mcp list — you should see codeloop. If not, re-run npx codeloop init --global.

Tools not showing up in Claude Code

• Run claude mcp list— the canonical way to see which MCP servers Claude Code knows about. codeloop should appear there.
• If you used per-project setup, verify .claude/settings.local.json exists and is valid JSON.
• Check that CODELOOP_API_KEY is set: echo $CODELOOP_API_KEY (it must start with cl_live_).
• Restart Claude Code after creating or editing the config.
• Look for MCP connection errors in Claude Code's output panel.

MCP server won't connect

• Ensure Node.js 18+ is installed: node --version
• Try running the server directly: npx -y codeloop-mcp-server
• Check internet connectivity (first validation requires network)

API key validation fails

• Verify your key starts with cl_live_
• Check if your trial has expired at the Dashboard
• Ensure there are no trailing spaces or newlines in the key

Claude Code doesn't follow CLAUDE.md instructions

• Ensure CLAUDE.md is in the project root (same level as package.json)
• Re-run npx codeloop init to regenerate the file
• Check that the file is not empty or corrupted

Next Steps

• API Keys — manage, rotate, and secure your keys
• Cursor Setup — if you also use Cursor
• Tool Reference — detailed guide for each MCP tool
• Configuration — customise CodeLoop settings
• FAQ — common questions and answers