name: scan-codebase description: '$codemap-py:scan-codebase [flags] only: Python index; never auto-invoke; skip query/integration.' metadata: version: "1.0.1"

Before asking, read User Questions.

Scan Codebase

Python only: ast.parse records imports plus classes/functions/methods and line ranges for every .py; non-Python files excluded. Writes .cache/codemap/<project>.json, no external dependencies. A zero-Python project writes a valid empty index; downstream queries return no results. Symbol data lets $codemap-py:query-code symbol/find-symbol return target source instead of full-file reads (~70–94% fewer Read tokens).

NOT for: existing-index query (use $codemap-py:query-code); integration health (use $codemap-py:integration).

Explicit invocation only — Codex cannot declare disable-model-invocation; never call this skill autonomously, only for the user's literal $codemap-py:scan-codebase trigger.

Runtime note

Codex has no bin/ PATH entry or plugin-root variable. Resolve installed root once, replace PLUGIN_ROOT literally in commands, retain in reasoning; shell state doesn't persist.

Workflow

1. Scan

Parse only --root <path> and --incremental. For any other -- token, report ! Unknown flag(s): <tokens> then Supported: --root <path>, --incremental and stop; do not guess. Use this exact Unknown flag(s) wording.

PLUGIN_ROOT/bin/codemap-py index [--root <path>] [--incremental]

On Windows use PLUGIN_ROOT\bin\codemap-py.cmd index .... --root names index from basename(<path>), unlike default git-root basename. After a custom-root scan, retain exact path printed by scanner as <emitted-index-path>. A later query may pass --root <same-root> to select that root's canonical index; pass --index <emitted-index-path> --root <same-root> to pin the emitted file. --root also sets query path resolution and the accepted custom-index boundary. Scanner writes <root>/.cache/codemap/<project>.json (or $CODEMAP_INDEX_DIR/<project>.json), prints indexed/degraded counts. On non-zero exit, report it and stop; never retry silently (1 index/filesystem failure, 2 syntax).

2. Report

Report module and degraded counts; degraded is informational and the index remains usable. For zero Python, report valid but empty. Then suggest:

Index ready. Query it with $codemap-py:query-code — central --top 10, deps/rdeps <module>, coupled --top 10.
See $codemap-py:query-code for the full subcommand list.