Set up LoopGuard

Works with VS Code, Cursor, Windsurf, Codex CLI, Claude Code in terminal, and supported shells like bash, zsh, and fish. Pick your tool below.

VS Code Cursor Windsurf Codex CLI Claude Code (terminal)Shell hooks

VS Code

extension

Install from Marketplace

Search for LoopGuard in the Extensions panel, or run:

ext install LoopGuard.loopguard

The Rust binary is bundled. No Cargo or extra install needed.

Activate automatically

Open any workspace. LoopGuard activates and the status bar shows ✓ LoopGuard. Loop detection is live.

Optional: sign in to sync metrics

Open the Command Palette and run:

LoopGuard: Sign In

Your browser opens. Sign in and VS Code connects automatically.

Cursor

extension

Install the VS Code extension in Cursor

Cursor is compatible with VS Code extensions. Open Cursor’s Extensions panel and search LoopGuard, or install the VSIX manually:

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

Download the correct platform VSIX from GitHub Releases.

Sign in (works with cursor:// scheme)

Run LoopGuard: Sign In from the Command Palette. The auth callback automatically uses cursor:// — not vscode://.

Wire MCP for inline compression (recommended)

Run from the Command Palette:

LoopGuard: Configure MCP Server → Cursor

Restart Cursor so LoopGuard's MCP tools are available to the agent.

Windsurf

extension

Install the VS Code extension in Windsurf

Windsurf supports VS Code extensions. Install via the Extensions panel or manually with the VSIX for your platform.

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

Sign in (uses windsurf:// scheme)

Run LoopGuard: Sign In. The auth callback uses windsurf://LoopGuard.loopguard/auth automatically.

Configure MCP for Windsurf

LoopGuard: Configure MCP Server → Windsurf

Restart Windsurf so LoopGuard's MCP tools are available.

Codex CLI

MCP

Codex supports MCP servers. LoopGuard can plug into Codex so focused reads and shell compression are available through the local loopguard-ctx binary.

If you already installed the LoopGuard extension

Run this from VS Code, Cursor, or Windsurf:

LoopGuard: Configure MCP Server → Codex CLI

LoopGuard writes ~/.codex/config.toml for you using the bundled binary path.

Manual Codex config

If you are using the standalone binary instead of the extension, add this to ~/.codex/config.toml:

[mcp_servers.loopguard-ctx]
command = "loopguard-ctx"
args = []

Restart Codex

Restart Codex after editing the config so it reloads the MCP server list.

Claude Code (terminal)

no VS Code needed

No VS Code required. Claude Code can connect to LoopGuard over MCP for focused reads, compact search results, and cleaner shell output.

Download the loopguard-ctx binary

Get the binary for your platform from GitHub Releases:

loopguard-ctx-darwin-arm64macOS Apple Silicon

loopguard-ctx-darwin-x64macOS Intel

loopguard-ctx-linux-x64Linux x64

loopguard-ctx-linux-arm64Linux ARM64

loopguard-ctx-win32-x64.exeWindows x64

Open GitHub Releases

Install to your PATH

chmod +x loopguard-ctx && mv loopguard-ctx /usr/local/bin/

Verify it works:

loopguard-ctx --version

Configure MCP for Claude Code

This writes the MCP server config to ~/.claude/settings.json:

loopguard-ctx setup --agent=claude

Restart Claude Code

Close and reopen your terminal session. Claude Code will now see LoopGuard’s MCP tools and can use them for focused context reads.

What you get

· Focused file reads through ctx_read
· Compact code search and directory tools
· Shell output compression through ctx_shell
· A larger MCP toolset exposed by the local binary

Shell Hooks

any terminal

Install the shell helper so supported command output can be routed through LoopGuard locally before you paste it into an AI tool.

Install the binary (if not already done)

Same binary as the Claude Code setup above.

loopguard-ctx --version

Install shell hooks

loopguard-ctx init

Adds hooks to ~/.zshrc / ~/.bashrc.

Restart your terminal

Open a new terminal session. Supported commands can now use LoopGuard’s shell path:

$ npm install

...

[LoopGuard: compressed 3,420 → 280 tokens · 91% reduction]

Supported: bash · zsh · fish (manual config available via loopguard-ctx init --help)

Questions or issues? Check the docs or open an issue on GitHub.

Full Documentation GitHub Issues