index

codeindex:index — Repository Indexing

Generate AI-friendly index files (README_AI.md) for codebases using the codeindex CLI.

Prereq: codeindex CLI must be on PATH. If not, install with pipx install ai-codeindex (plugin SessionStart hook surfaces this).

Workflow

Step 1: Initialize (if needed)

cat .codeindex.yaml 2>/dev/null || codeindex init --yes

--yes for non-interactive default config (CI-friendly).

Step 2: Review Configuration

cat .codeindex.yaml

Key settings to verify:

• languages — Detected programming languages (python, java, php, swift, etc.)
• include — Directories to scan
• exclude — Patterns to skip
• ai_command — AI CLI for --ai mode (defaults to claude haiku)

Step 3: Preview Indexable Directories

codeindex list-dirs

Step 4: Scan

# Structural-only (fast, no AI calls):
codeindex scan-all

# Structural + AI-enriched blockquote descriptions (cache-aware):
codeindex scan-all --ai

# Force re-enrich every dir, ignoring cache:
codeindex scan-all --ai --retry-all

# Single dir:
codeindex scan ./src/module
codeindex scan ./src/module --ai
codeindex scan ./src/module --ai --dry-run   # preview prompt only

Step 5: Verify Coverage

codeindex status

Step 6 (Optional): Set Up Auto-Updates

If user wants README_AI.md to stay in sync on commit, hand off to the codeindex:hooks skill:

"Want READMEs to auto-update when you commit code? Use the codeindex:hooks skill to set up the post-commit hook."

Scan Modes Cheat Sheet

Mode	Command	When
Auto (default)	codeindex scan-all	Structural + AI enrichment if ai_command configured
Structural-only	codeindex scan-all --no-ai	Zero AI cost; fastest
Re-enrich all	codeindex scan-all --ai --retry-all	After prompt or model changes
Single dir	codeindex scan ./dir --ai	Deep AI README for one directory

Troubleshooting

Problem	Solution
AI CLI timeout	codeindex scan ./dir --ai --timeout 180
AI not configured	Use codeindex scan-all (structural mode) — ai_command is optional
Want to inspect AI prompt	codeindex scan ./dir --ai --dry-run
Missing language parser	pipx inject ai-codeindex tree-sitter-<lang>
Rate limit hit mid-scan	Just re-run codeindex scan-all --ai — Phase 2 is idempotent, only failed dirs hit AI again

Post-Indexing Recommendations

1. Commit README_AI.md files for team/AI sharing (or add to .gitignore if you regenerate them per developer — codeindex init auto-adds this).
2. Set up git hooks for auto-updates (use the codeindex:hooks skill).
3. Add to your project's CLAUDE.md: "Read README_AI.md before modifying code."