project-indexer

Harness-agnostic skill that indexes any project into a root-level PROJECT_INDEX.md — a tree of every file with a one-line description — then wires it into whichever AI-agent context file exists (CLAUDE.md, AGENTS.md, GEMINI.md, .cursor/rules/, .windsurf/rules/, .github/copilot-instructions.md, .clinerules/). Works for Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Copilot, Cline, and anything else that reads an agent-context markdown file.

Future sessions understand the layout without running Glob / Grep / find every turn.

• Full tree of every tracked file (honors .gitignore, .claudeignore, .aiignore)
• One-line descriptions generated by reading each file
• Root-level output (PROJECT_INDEX.md) — visible to every agent and human
• Auto-detects installed harnesses and wires the index into each one's context file
• Two modes: manual (on request) and auto (via PostToolUse hook — Claude Code + Codex only)
• Incremental updates — only re-describes changed files (via git diff or mtime)
• Idempotent updates via marked <!-- project-indexer:start --> / <!-- project-indexer:end --> blocks
• Fast on any repo size — parallel reads (20 per batch) + subagent dispatch for >50 files
• Skip-read for heavy files — images, fonts, media, archives, binaries, >1 MB blobs, and >2000-line text files never get full-Read; descriptions come from filename or a signatures-only scan

Install

One-command install (any agent)

npx skills add pccly/project-indexer            # auto-detect agent
npx skills add pccly/project-indexer -a cursor
npx skills add pccly/project-indexer -a windsurf
npx skills add pccly/project-indexer -a cline
npx skills add pccly/project-indexer -a github-copilot

See vercel-labs/skills for the full list of supported agents (40+).

Manual install

# Claude Code
git clone https://github.com/pccly/project-indexer ~/.claude/skills/project-indexer

# Codex / agents honoring ~/.agents/skills/
git clone https://github.com/pccly/project-indexer ~/.agents/skills/project-indexer

Uninstall: npx skills remove project-indexer or just remove the directory.

Usage

Trigger phrases (work in any agent):

• "index this project"
• "update the project index"
• "map the codebase"
• "refresh PROJECT_INDEX.md"
• "rebuild the index from scratch"
• "enable auto indexing" / "disable auto indexing" (Claude Code / Codex only)

The skill will:

1. Scan the repo respecting .gitignore + .claudeignore + .aiignore
2. Read each file to generate a one-line description
3. Write PROJECT_INDEX.md at the repo root with a full tree + per-file entries
4. Detect which agent context files exist and update each with a pointer to the index:
   • CLAUDE.md — uses @PROJECT_INDEX.md import (Claude Code loads it automatically)
   • AGENTS.md / GEMINI.md / Cursor rules / Windsurf rules / Copilot instructions / Cline rules — plain reference
5. If no agent file exists, create AGENTS.md at root as a universal fallback

Slash commands (Claude Code)

If you copy commands/ into ~/.claude/commands/, you also get:

• /project-index — create or incrementally update
• /project-index-rebuild — force full rebuild
• /project-index-auto on|off — toggle the auto-update hook

Per-harness behavior

Harness	Context file written	Auto mode
Claude Code	CLAUDE.md (with @ import)	✅ via .claude/settings.json hook
Codex	AGENTS.md	✅ via .codex/hooks.json (syntax varies)
Cursor	.cursor/rules/project-index.mdc	❌ no hook system — run manually
Windsurf	.windsurf/rules/project-index.md	❌ run manually
Gemini CLI	GEMINI.md	❌ run manually
Copilot	.github/copilot-instructions.md	❌ run manually
Cline	.clinerules/project-index.md	❌ run manually
Any other	AGENTS.md (universal fallback)	❌ run manually

The skill never creates a tool's context file unless its config directory (.cursor/, .gemini/, etc.) already exists — no silent opt-in to tools you don't use.

Auto mode (Claude Code + Codex)

Auto mode writes a PostToolUse hook that regenerates the index in the background after every Write or Edit. The script:

• Debounces — skips if the index was updated < 60 seconds ago
• Skip-if-missing — never auto-creates; only refreshes existing indexes
• Non-blocking — runs detached via &
• Single-flight — lock file prevents concurrent runs

Enable: "enable auto project indexing" or /project-index-auto on. Disable: /project-index-auto off.

Example output

# Project Index

_Last updated: 2026-04-24 (mode: incremental)_
_Root: /Users/you/code/my-app_
_Files indexed: 87_

<!-- indexed-at-sha: 3a2e9f1 -->

## Tree

\`\`\`
src/
  main/
    ipc.ts
    index.ts
  renderer/
    App.tsx
package.json
\`\`\`

## Files

### `src/main/ipc.ts`
IPC handlers for workspaces, memories, skills, agents, MCP, plugins.

### `src/main/index.ts`
Electron main entry — creates BrowserWindow, wires native menu.

### `src/renderer/App.tsx`
Root React component — renders tool switcher, sidebar, main panel.

Why

Every Glob / Grep call burns tokens and adds latency. One 200-line index replaces dozens of search calls for navigation tasks — and it travels with the repo, so every agent (Claude, Cursor, Copilot, Codex) benefits equally. The index also surfaces dead files, unclear naming, and coverage gaps every time you review it.

License

MIT

Documentation

Polished project notes (kept in the CCLY Obsidian vault, ~/Nextcloud/CCLY/Projects/project-indexer/):

• project-indexer.md — hub note: purpose, how it works, harness-wiring matrix, triggers, status.
• Skill.md — polished skill spec (supersedes the in-tree SKILL.md for prose / tightening; the in-tree SKILL.md remains the runtime artifact loaded by Claude Code / agent skill harnesses).

In-tree references for runtime / contributors:

• SKILL.md — runtime skill definition (frontmatter trigger + full process). Loaded by Claude Code / agent harnesses.
• commands/project-index.md, commands/project-index-rebuild.md, commands/project-index-auto.md — slash-command definitions.
• scripts/auto_update.sh — debounced PostToolUse refresher invoked by the auto-mode hook.