playbooks

home / skills / jeremylongshore / claude-code-plugins-plus-skills / cursor-indexing-issues

cursor-indexing-issues skill

/plugins/saas-packs/cursor-pack/skills/cursor-indexing-issues

This skill helps you troubleshoot Cursor codebase indexing issues and optimize search reliability for AI features.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill cursor-indexing-issues

Review the files below or copy the command above to add this skill to your agents.

Files (6)
SKILL.md
1.8 KB
---
name: "cursor-indexing-issues"
description: |
  Manage troubleshoot Cursor codebase indexing problems. Triggers on "cursor indexing",
  "cursor index", "cursor codebase", "@codebase not working", "cursor search broken". Use when working with cursor indexing issues functionality. Trigger with phrases like "cursor indexing issues", "cursor issues", "cursor".
allowed-tools: "Read, Write, Edit, Bash(cmd:*)"
version: 1.0.0
license: MIT
author: "Jeremy Longshore <[email protected]>"
---

# Cursor Indexing Issues

## Overview

This skill helps troubleshoot Cursor codebase indexing problems. It provides solutions for stuck indexing, empty search results, performance issues, and configuration optimization to ensure your codebase is properly indexed for AI features.

## Prerequisites

- Cursor IDE with indexing enabled
- Access to Cursor settings
- Command line access for cache clearing
- Understanding of project file structure

## Instructions

1. Check indexing status in status bar
2. Identify the specific issue (stuck, empty results, performance)
3. Review and update `.cursorignore` configuration
4. Try manual refresh via Command Palette
5. Clear index cache if issues persist
6. Restart Cursor and allow re-indexing

## Output

- Functional codebase indexing
- Working `@codebase` search queries
- Optimized indexing performance
- Properly configured exclusion patterns

## Error Handling

See `{baseDir}/references/errors.md` for comprehensive error handling.

## Examples

See `{baseDir}/references/examples.md` for detailed examples.

## Resources

- [Cursor Indexing Documentation](https://cursor.com/docs/indexing)
- [File Watcher Configuration](https://code.visualstudio.com/docs/setup/linux#_visual-studio-code-is-unable-to-watch-for-file-changes-in-this-large-workspace-error-enospc)
- [Cursor GitHub Issues](https://github.com/getcursor/cursor/issues)

Overview

This skill helps troubleshoot and resolve Cursor codebase indexing problems so your AI features and @codebase searches work reliably. It guides you through diagnosing stuck indexing, empty search results, and performance bottlenecks, and offers concrete steps to refresh and optimize the index. Use it to restore search functionality and minimize future indexing disruptions.

How this skill works

The skill inspects Cursor indexing state, common configuration causes, and local cache integrity. It walks you through status checks, .cursorignore review, manual refresh commands, cache clearing, and restart procedures. It also highlights file-watcher and workspace-size considerations that commonly break indexing.

When to use it

  • Search queries return no results or @codebase finds nothing
  • Indexing shows as stuck or never completes in the status bar
  • Cursor is slow or indexing causes high CPU/disk activity
  • You changed large directories or added many files and indexing failed
  • After updating .cursorignore or workspace configuration with unexpected behavior

Best practices

  • Check the status bar and Command Palette for active indexing messages before troubleshooting
  • Keep .cursorignore updated to exclude build, node_modules, and large generated folders
  • Use manual refresh and clear index cache as first-line recovery steps
  • Limit watched files and use file-watcher settings for very large workspaces
  • Restart Cursor after cache clearing and allow a full re-index without interruption

Example use cases

  • Resolve empty @codebase search after adding a huge dependency folder
  • Fix a stalled index after a crash by clearing the index cache and re-indexing
  • Improve performance by excluding generated assets and large binaries via .cursorignore
  • Recover from inconsistent search results following a large refactor or repo rename
  • Diagnose file-watcher limits on Linux when Cursor cannot track file changes

FAQ

How do I tell if indexing is running or stuck?

Check the status bar for indexing progress and use the Command Palette to view indexing actions; if progress doesn't change after a few minutes, treat it as stuck and try a manual refresh.

When should I clear the index cache?

Clear the cache when manual refresh doesn't help, search results are inconsistent, or after major repo changes; always restart Cursor afterward to force a clean re-index.

What folders should I put in .cursorignore?

Exclude node_modules, build/dist folders, large generated assets, vendor directories, and any binary blobs that are not needed for code search to reduce indexing load.