Documentation

#Installation

LoopGuard has two install paths. Pick the one that matches how you work.

VS Code · Cursor · Windsurf (extension)

Open VS Code, press Ctrl+P (or Cmd+P on macOS), and run:

ext install LoopGuard.loopguard

Or search LoopGuard in the Extensions panel and click Install. Works identically in Cursor and Windsurf — the URI callback auto-detects your IDE.

Claude Code terminal (no VS Code required)

If you use Claude Code in the terminal without VS Code, install the standalone binary instead. No account, no extension, no sign-in needed — everything runs locally.

# 1. Download the binary for your platform from GitHub Releases
# macOS Apple Silicon
curl -L https://github.com/rodthenewcomer/loopguard/releases/latest/download/loopguard-ctx-darwin-arm64 -o loopguard-ctx

# macOS Intel
curl -L https://github.com/rodthenewcomer/loopguard/releases/latest/download/loopguard-ctx-darwin-x64 -o loopguard-ctx

# Linux x64
curl -L https://github.com/rodthenewcomer/loopguard/releases/latest/download/loopguard-ctx-linux-x64 -o loopguard-ctx

# 2. Install it
chmod +x loopguard-ctx && mv loopguard-ctx /usr/local/bin/

# 3. Verify
loopguard-ctx --version

# 4. Wire Claude Code (registers MCP server + installs PreToolUse hook)
loopguard-ctx setup --agent=claude

# 5. Restart Claude Code — done

After restart, Claude Code routes every file read through the context engine automatically via the PreToolUse hook. You can also call ctx_read, ctx_search, ctx_shell, and other MCP tools directly from within a Claude Code session. Run loopguard-ctx gain at any time to see your token savings.

Manual installation (.vsix)

If you prefer to install manually, download the platform-specific VSIX from GitHub Releases and run:

code --install-extension loopguard-darwin-arm64.vsix

#First launch

LoopGuard activates automatically when VS Code starts (activation event: onStartupFinished). You do not need to run any command to enable it.

What you see on first launch

• The LoopGuard status bar item appears at the bottom of VS Code — in the clean state it shows the standard check-mark variant of LoopGuard.
• The output channel "LoopGuard" is created. Open it with View → Output → LoopGuard to see diagnostics.
• A welcome notification appears with a link to sign in and connect to the web dashboard (optional).
• Loop detection starts immediately — no sign-in required for the core features.

Account (optional)

LoopGuard works fully without an account. Sign in only if you want your session metrics synced to the web dashboard. To sign in, run the command LoopGuard: Sign In from the Command Palette (Ctrl+Shift+P). A browser window opens, you authenticate, and the token is stored in your OS secure keychain (macOS Keychain, Windows Credential Manager, Linux libsecret) via VS Code SecretStorage.

#Quick reference

All LoopGuard commands are available in the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).

#How loop detection works

LoopGuard uses two independent detection methods simultaneously. Either method alone can trigger an alert. Both run entirely on your local machine with no cloud round-trip.

Method 1 — Diagnostic loop detection

LoopGuard subscribes to vscode.languages.onDidChangeDiagnostics. Every time VS Code reports a diagnostic (error, warning) for any file, LoopGuard computes a short deterministic fingerprint of the diagnostic text. If the same fingerprint appears N times in a session (where N is your sensitivity threshold), a loop is detected.

This catches the most common case: you ask AI to fix an error, it gives you the same fix with different variable names, and the same error reappears.

Method 2 — Edit-pattern loop detection

LoopGuard also watches vscode.workspace.onDidChangeTextDocument. It tracks repeated edits in the same region of a file over a short time window. If you keep revisiting the same lines without breaking out, LoopGuard can flag that as an edit loop even when the diagnostic text changes.

This catches more subtle loops — for example, when you rename a variable three times trying different things and always end up back at the same code.

What gets tracked

LoopGuard syncs only an anonymized fingerprint of the error message. The original message text is never sent to the backend. The file type (for example ts or py) is stored — never the file name or file path. See the Privacy Policy for the full data inventory.

#Alert actions

When a loop is detected, a VS Code notification appears with the exact minutes wasted and three action buttons:

#Sensitivity settings

Sensitivity controls how many times the same error hash must appear before a loop is declared. Lower sensitivity = more alerts, fewer false negatives.

Change sensitivity in your settings:

// settings.json
{
  "loopguard.sensitivity": "medium"
}

#Copy Optimized Context

Instead of pasting an entire file into your AI chat, use LoopGuard: Copy Optimized Context. It extracts only what the AI needs to solve your current error and copies it to your clipboard. Paste it directly into Claude, ChatGPT, Cursor chat, or any AI tool.

What gets extracted

• Import and dependency lines near the top of the file when they can be identified
• A focused window around the first active error in the current document (about 30 lines on each side in the TypeScript fallback)
• A local token estimate so LoopGuard can report approximate savings after the copy
• When the bundled loopguard-ctx binary is available, a richer entropy-based read path instead of the plain TypeScript fallback

Keyboard shortcut

Bind it to a key for one-keystroke context compression:

// keybindings.json
{
  "key": "ctrl+shift+c",
  "command": "loopguard.copyContext",
  "when": "editorFocus"
}

#Rust engine vs TypeScript engine

LoopGuard ships two context engine implementations. The TypeScript engine runs on every install. When the bundled loopguard-ctx binary is available, LoopGuard can use that richer local read path automatically.

The binary runs as a local subprocess (loopguard-ctx) and has no network access. The percentage shown in the extension UI is an estimate, not a tokenizer-perfect billing guarantee.

#Supported languages

Loop detection itself is language-agnostic because it listens to IDE diagnostics. Context copy works best on common code and config files, and the binary path has broader language-aware support than the TypeScript fallback.

#VS Code session dashboard

Run LoopGuard: Show Dashboard to open the in-IDE webview. It updates during the current session and shows:

• Current session duration, total time wasted, tokens saved, and estimated cost saved
• The active loop count and the current loop list
• Whether the bundled binary is active or LoopGuard is using the TypeScript fallback
• Short next-step suggestions when you are visibly stuck

The dashboard is a VS Code webview panel. It updates automatically as the session progresses — no refresh needed.

#Account and session sync

If you are signed in, LoopGuard syncs session metrics to the web dashboard every 5 minutes and again on session end. Synced data is your account’s only — Supabase row-level security ensures no other user can access it.

The web dashboard refreshes periodically for signed-in users, so it feels near-real-time, but it is still limited by the extension’s sync cadence.

To connect your account: run LoopGuard: Sign In → a browser tab opens → sign in with email/password or Google → you are redirected back to VS Code automatically.

#MCP server

loopguard-ctx can run as an MCP server over stdio, exposing focused file, search, tree, and shell tools to compatible AI agents. That means the agent can ask LoopGuard for a smarter read instead of grabbing full files every time.

Today, LoopGuard can configure MCP for Claude Code, Cursor, Windsurf, Codex CLI, Zed, and VS Code / Copilot. If a tool supports custom MCP stdio servers, LoopGuard can usually plug into it.

Setup (one command)

Run LoopGuard: Configure MCP Server from the Command Palette. LoopGuard writes the correct config for your tool automatically, including the absolute path to the local loopguard-ctx binary.

If you prefer to configure manually, use the config format your agent expects:

// JSON-style MCP config (Cursor / Claude Code / Windsurf)
{
  "mcpServers": {
    "loopguard-ctx": {
      "command": "/absolute/path/to/loopguard-ctx"
    }
  }
}

# Codex CLI (~/.codex/config.toml)
[mcp_servers.loopguard-ctx]
command = "/absolute/path/to/loopguard-ctx"
args = []

Available MCP tools

#Shell helper

The shell helper installs LoopGuard’s local command wrapper so supported shell output can be reduced before you paste it into an AI tool or route it through a compatible agent flow.

For example, npm install, git log, or docker buildoften generate far more output than an AI tool needs. LoopGuard’s shell path is designed to keep the useful parts and drop repetitive noise.

Installation

# From the extension
LoopGuard: Install Shell Hooks

# Or with the standalone binary
loopguard-ctx init

This adds a hook to your shell rc file (~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish). Restart your terminal or run source ~/.zshrc to activate.

How it works

The helper uses loopguard-ctx locally. The original command still runs on your machine; LoopGuard just gives you a cleaner representation for AI-facing workflows.

#Binary installation details

The loopguard-ctx Rust binary is bundled inside the platform-specific VSIX. VS Code selects the correct VSIX based on your platform at install time.

The binary lives under the extension’s bin/<platform-arch>/ directory and is called as a subprocess by the extension. It communicates over stdin/stdout and has no network access.

If you need the binary separately (e.g. for shell hooks in a terminal without VS Code), download it from GitHub Releases.

#All settings

#settings.json reference

Copy-paste this into your .vscode/settings.json or user settings:

{
  "loopguard.sensitivity": "medium",       // "low" | "medium" | "high"
  "loopguard.loopThreshold": 3,            // exact count (overrides sensitivity)
  "loopguard.enableContextEngine": true,
  "loopguard.enableNotifications": true
}

#Loops not being detected

• Check that detection is not paused. Run LoopGuard: Toggle Detection if needed.
• Check the sensitivity — "low" requires the same error 5 times. Try "high" (2×) to test.
• Make sure the error is actually appearing in the VS Code Problems panel (View → Problems). LoopGuard only sees errors that VS Code diagnostics report — it does not read terminal output.
• Open the LoopGuard output channel (View → Output → LoopGuard). It logs LoopGuard activity and errors while you reproduce the issue.
• Some linters report slightly different messages each time. If the message changes, LoopGuard treats it as a different fingerprint. Use "high" sensitivity to catch these earlier.

#Binary not found

If you see loopguard-ctx: binary not found in the output channel:

• Uninstall and reinstall the extension — make sure you install the platform-specific VSIX, not the generic one.
• Check that the binary exists: open a terminal and run: ls ~/.vscode/extensions/LoopGuard.loopguard-*/bin/
• On macOS, the binary may be quarantined by Gatekeeper. Run: xattr -d com.apple.quarantine ~/.vscode/extensions/LoopGuard.loopguard-*/bin/loopguard-ctx
• On Linux, the binary may not be executable. Run: chmod +x ~/.vscode/extensions/LoopGuard.loopguard-*/bin/loopguard-ctx
• If none of the above works, download the binary directly from GitHub Releases and place it in the bin/ directory.

#MCP setup failed

If LoopGuard: Configure MCP Server fails or the tools do not appear in your AI tool:

• Make sure loopguard-ctx binary is working first — run LoopGuard: Copy Optimized Context to verify the context engine loads.
• Check that the target config file was actually updated: for example ~/.cursor/mcp.json, ~/.claude.json, ~/.codeium/windsurf/mcp_config.json, ~/.codex/config.toml, or your VS Code user mcp.json.
• Restart your AI tool (Cursor, Claude Code, etc.) after running Configure MCP Server — the config is only read on startup.
• Check your AI tool's MCP log for errors if it has one.
• No Node.js install is required for LoopGuard MCP. The server is the local loopguard-ctx binary.

#Sign-in issues

LoopGuard sign-in uses a browser deep-link callback. The extension opens a browser tab and waits for a redirect back to VS Code via the URI scheme (e.g. vscode://LoopGuard.loopguard/auth).

• Make sure your browser is set as the default browser — VS Code uses xdg-open (Linux), open (macOS), or start (Windows) to open the URL.
• On Linux with xdg-open, make sure a default browser is set: xdg-settings get default-web-browser
• If the browser opens but the redirect does not come back, check that your OS allows the vscode:// URI scheme. On Linux this may need to be registered: xdg-mime default code.desktop x-scheme-handler/vscode
• In Cursor, the URI scheme is cursor:// — LoopGuard detects this automatically via vscode.env.uriScheme.
• If you are on a remote / SSH session, deep-link callbacks may not work yet. Core loop detection and local context copy still work offline, but dashboard sign-in is best done from a local desktop session for now.