Context Map
Generate a compressed context map for the current project.
The map pre-compiles structural knowledge that AI assistants
would otherwise discover through expensive Read/Grep calls,
saving thousands of tokens per session.
When To Use
- At the start of a session to understand project layout
- Before implementing features to identify entry points
- When exploring an unfamiliar codebase
- To reduce token waste from Read calls
- To identify hot files (high blast radius) before changes
When NOT To Use
- Context is already over budget mid-session (use
conserve:clear-context)
- Auditing the codebase for bloat (use
conserve:bloat-detector)
What It Detects
| Category |
Description |
| Structure |
Directory layout with file counts and languages |
| Dependencies |
Multi-ecosystem: Python, Node, Rust, Go, Java |
| Frameworks |
Framework detection from dependency analysis |
| Entry Points |
main.py, index.ts, CLI scripts, etc. |
| Import Graph |
File-to-file import relationships |
| Hot Files |
Files imported by 3+ others (high blast radius) |
| Routes |
FastAPI, Flask, Express, Hono API endpoints |
| Env Vars |
Environment variable references with defaults |
| Middleware |
Auth, CORS, rate-limit, logging patterns |
| Models/Schemas |
SQLAlchemy, Django, Pydantic, Prisma definitions |
| Token Savings |
Estimated tokens saved vs manual exploration |
Procedure
- Run the scanner on the project root:
PYTHONPATH="$(find . -path '*/conserve/scripts' -type d \
-print -quit 2>/dev/null || \
echo 'plugins/conserve/scripts')" \
python3 -m context_scanner .
Present the output to the user as the project overview.
Use the context map to guide subsequent file reads.
Prioritize hot files and entry points first.
Options
Output
--format json for structured output
--max-tokens N to adjust output size (default: 5000)
--output FILE to save to a file
Modes
--blast FILE to show blast radius for a specific file
--section NAME to output a single section
(routes, deps, env, hot-files, models, structure,
middleware, frameworks)
--wiki-only to generate wiki articles without stdout
Opt-out
--no-cache to force a fresh scan
--no-wiki to skip wiki article generation
Wiki Articles
The scanner generates per-topic knowledge articles in
.codesight/ for selective context loading:
python3 scanner.py .
# Creates .codesight/INDEX.md, auth.md, database.md, etc.
Load only what you need per session instead of the full map:
python3 scanner.py --section routes .
# ~200 tokens vs ~5,000 for the full map
Example Output
# Context Map: myproject
Files: 127
## Structure
src 42 files (Python)
tests 18 files (Python)
docs 5 files (Markdown)
## Dependencies (Python)
Package manager: uv
- fastapi 0.104.0
- pydantic 2.5.0
- sqlalchemy 2.0.0
...12 more
## Frameworks Detected
- FastAPI
- SQLAlchemy
- Pytest
## Routes
GET /users (src/routes/users.py)
POST /users (src/routes/users.py)
GET /users/{id} (src/routes/users.py)
## Hot Files (high blast radius)
- src/models/base.py (12 importers)
- src/utils/auth.py (8 importers)
## Environment Variables
- DATABASE_URL (required)
- SECRET_KEY (has default)
## Token Savings: ~12,600 tokens saved
Routes: ~1,200
Hot files: ~300
Env vars: ~200
File scanning: ~10,200
Exit Criteria
1---2name: context-map3description: Generates a compressed project context map to avoid expensive Read/Grep calls. Use at session start or before implementing features in an unfamiliar codebase.4category: optimization5tags:6 - context7 - scanning8 - token-conservation9 - exploration10 - import-graph11 - routes12tools: []13complexity: low14model_hint: fast15estimated_tokens: 30016metadata:17 source: https://skillmd.com/skills/athola/context-map18---1920# Context Map2122Generate a compressed context map for the current project.23The map pre-compiles structural knowledge that AI assistants24would otherwise discover through expensive Read/Grep calls,25saving thousands of tokens per session.2627## When To Use2829- At the start of a session to understand project layout30- Before implementing features to identify entry points31- When exploring an unfamiliar codebase32- To reduce token waste from Read calls33- To identify hot files (high blast radius) before changes3435## When NOT To Use3637- Context is already over budget mid-session (use38 `conserve:clear-context`)39- Auditing the codebase for bloat (use `conserve:bloat-detector`)4041## What It Detects4243| Category | Description |44|----------|-------------|45| Structure | Directory layout with file counts and languages |46| Dependencies | Multi-ecosystem: Python, Node, Rust, Go, Java |47| Frameworks | Framework detection from dependency analysis |48| Entry Points | main.py, index.ts, CLI scripts, etc. |49| **Import Graph** | File-to-file import relationships |50| **Hot Files** | Files imported by 3+ others (high blast radius) |51| **Routes** | FastAPI, Flask, Express, Hono API endpoints |52| **Env Vars** | Environment variable references with defaults |53| **Middleware** | Auth, CORS, rate-limit, logging patterns |54| **Models/Schemas** | SQLAlchemy, Django, Pydantic, Prisma definitions |55| **Token Savings** | Estimated tokens saved vs manual exploration |5657## Procedure58591. Run the scanner on the project root:6061```bash62PYTHONPATH="$(find . -path '*/conserve/scripts' -type d \63 -print -quit 2>/dev/null || \64 echo 'plugins/conserve/scripts')" \65 python3 -m context_scanner .66```67682. Present the output to the user as the project overview.69703. Use the context map to guide subsequent file reads.71 Prioritize hot files and entry points first.7273## Options7475### Output7677- `--format json` for structured output78- `--max-tokens N` to adjust output size (default: 5000)79- `--output FILE` to save to a file8081### Modes8283- `--blast FILE` to show blast radius for a specific file84- `--section NAME` to output a single section85 (routes, deps, env, hot-files, models, structure,86 middleware, frameworks)87- `--wiki-only` to generate wiki articles without stdout8889### Opt-out9091- `--no-cache` to force a fresh scan92- `--no-wiki` to skip wiki article generation9394## Wiki Articles9596The scanner generates per-topic knowledge articles in97`.codesight/` for selective context loading:9899```bash100python3 scanner.py .101# Creates .codesight/INDEX.md, auth.md, database.md, etc.102```103104Load only what you need per session instead of the full map:105106```bash107python3 scanner.py --section routes .108# ~200 tokens vs ~5,000 for the full map109```110111## Example Output112113```114# Context Map: myproject115Files: 127116117## Structure118 src 42 files (Python)119 tests 18 files (Python)120 docs 5 files (Markdown)121122## Dependencies (Python)123Package manager: uv124 - fastapi 0.104.0125 - pydantic 2.5.0126 - sqlalchemy 2.0.0127 ...12 more128129## Frameworks Detected130 - FastAPI131 - SQLAlchemy132 - Pytest133134## Routes135 GET /users (src/routes/users.py)136 POST /users (src/routes/users.py)137 GET /users/{id} (src/routes/users.py)138139## Hot Files (high blast radius)140 - src/models/base.py (12 importers)141 - src/utils/auth.py (8 importers)142143## Environment Variables144 - DATABASE_URL (required)145 - SECRET_KEY (has default)146147## Token Savings: ~12,600 tokens saved148 Routes: ~1,200149 Hot files: ~300150 Env vars: ~200151 File scanning: ~10,200152```153154## Exit Criteria155156- [ ] Scanner produces output covering at minimum: file count,157 directory structure, detected frameworks, and hot files (imported158 by 3+ others); output appears in the session before any feature159 implementation reads begin160- [ ] "Token Savings" line is present in the output with a numeric161 estimate (e.g., `~12,600 tokens saved`)162- [ ] If `--blast FILE` is used, blast-radius output names the163 specific file and lists its importers by count164- [ ] Context map guides subsequent reads: hot files and entry points165 are consulted before any other file read in the session