Branch-aware local context indexer for Codex new-thread priming.
This project packages a local indexing layer that improves first-prompt file discovery without modifying Codex internals. It is for Codex users working in real repositories where branch switching and cold-start prompts make context retrieval noisy.
Quick start:
./scripts/index_bootstrap.sh
./scripts/index_prime.sh --query "where is auth middleware configured?"- Call the skill and provide your prompt.
- Root is auto-detected from current thread
cwd. - Do not pass a root path manually.
New threads start without shared conversational memory. This project keeps project context on disk and retrieves relevant files/chunks for the first prompt, with branch-awareness to avoid stale context bleed.
- Per-project local index state under
<repo>/.codex/index-state/ - Branch-aware retrieval view: base + active overlay
- Hybrid retrieval pipeline:
- lexical top 30
- semantic top 30
- reciprocal rank fusion (
k=60) - rerank top 20
- attach top 8 chunks
- Incremental refresh path for frequent branch switching
- Optional git hook templates (not auto-installed)
# 1) Bootstrap once per project
./scripts/index_bootstrap.sh
# 2) Refresh after local changes / branch switch
./scripts/index_incremental.sh
# 3) Prime first prompt in a new thread
./scripts/index_prime.sh --query "where is auth middleware configured?"
# 4) Evaluate retrieval quality
./scripts/index_eval.shindex_bootstrap.sh [--root <abs_repo_path>]index_sync.sh [--root <abs_repo_path>]index_incremental.sh [--root <abs_repo_path>]index_prime.sh [--root <abs_repo_path>] --query "<text>"index_eval.sh [--root <abs_repo_path>]
Default root is current working directory.
File: <repo>/.codex/index-policy.yaml
Keys:
include_globsexclude_globsmax_file_size_bytesskip_binaryskip_minifiedpriority_files
<repo>/.codex/index-state/base/index.db<repo>/.codex/index-state/base/vectors.db<repo>/.codex/index-state/overlays/<branch>/<head>/index.db<repo>/.codex/index-state/manifest.json<repo>/.codex/index-state/last_eval.json
src/project_context_indexer/: core indexer + CLIscripts/: wrapper commandsconfig/eval_queries.yaml: default eval settests/: unit/integration/e2e testsskill/: Codex skill contract docshooks/: optional git hook templatesdocs/: full design/ops docs
- docs/WHY.md
- docs/HOW.md
- docs/IMPLEMENTATION.md
- docs/BRANCH_STRATEGY.md
- docs/OPERATIONS.md
- docs/TROUBLESHOOTING.md
PY_FILES="$(find src tests -name '*.py' -type f)"
python3 -m py_compile $PY_FILES
python3 -m unittest discover -s tests -p 'test*.py' -v
for f in scripts/*.sh hooks/*.sample; do bash -n "$f"; done
PYTHONPATH=src python3 -m project_context_indexer.indexer_cli --helpMIT. See LICENSE.