# Safe Mass Index Core

> Build and query bounded metadata-only repository indexes without rg process churn. Use when working in very large repos and you need deterministic file discovery by path, extension, language, scope, or freshness.

- Skill: `grtninja/safe-mass-index-core` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add grtninja/safe-mass-index-core`
- Raw SKILL.md: https://api.skillmd.com/api/skills/grtninja/safe-mass-index-core/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: grtninja (https://skillmd.com/u/grtninja)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/grtninja/safe-mass-index-core

---


# Safe Mass Index Core

Use this skill to index large repositories safely without `rg` subprocess churn.

## Workflow

1. Set bounded policies (time/files/read-bytes, exclusions).
2. Build incremental or full metadata index.
3. Query by path/ext/lang/size/freshness/scope.
4. Use run artifacts to verify deterministic bounded execution.

## Policy

1. Do not use `rg`/`rg.exe` for mass indexing.
2. Use only local filesystem metadata and bounded lightweight probing.
3. Keep runs bounded with file/time/read-byte budgets.

## Build Command

```bash
python3 "$CODEX_HOME/skills/safe-mass-index-core/scripts/index_build.py" \
  --repo-root <path> \
  --index-dir .codex-index \
  --mode incremental \
  --max-files-per-run 12000 \
  --max-seconds 25 \
  --max-read-bytes 67108864 \
  --exclude-dir .git \
  --exclude-dir node_modules \
  --exclude-dir .venv \
  --exclude-dir venv \
  --exclude-dir __pycache__ \
  --exclude-dir dist \
  --exclude-dir build \
  --exclude-dir target \
  --exclude-dir .cache \
  --exclude-dir .codex-index \
  --json-out .codex-index/run.json
```

For very large repos, enable sharded storage:

```bash
python3 "$CODEX_HOME/skills/safe-mass-index-core/scripts/index_build.py" \
  --repo-root <path> \
  --index-dir .codex-index \
  --mode incremental \
  --max-files-per-run 12000 \
  --max-seconds 25 \
  --max-read-bytes 67108864 \
  --sharded
```

## Query Command

```bash
python3 "$CODEX_HOME/skills/safe-mass-index-core/scripts/index_query.py" \
  --index-dir .codex-index \
  --path-contains <text> \
  --ext <extension> \
  --lang <language_tag> \
  --min-size <bytes> \
  --max-size <bytes> \
  --changed-since-epoch <seconds> \
  --scope <top_level_dir_or_all> \
  --limit 200 \
  --format table
```

## Outputs

- `.codex-index/manifest.json`
- `.codex-index/state.json`
- `.codex-index/files.jsonl` (non-sharded)
- `.codex-index/shards/*.jsonl` (sharded)
- `.codex-index/run.json`
## Scope Boundary

Use this skill only for the `safe-mass-index-core` lane and workflow defined in this file and its references.

Do not use this skill for unrelated lanes; route those through `$skill-hub` and the most specific matching skill.

## Reference

- `references/index-schema.md`

## Loopback

If this lane is unresolved, blocked, or ambiguous:

1. Capture current evidence and failure context.
2. Route back through `$skill-hub` for chain recalculation.
3. Resume only after the updated chain returns a deterministic next step.