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
Source: athola/claude-night-market → plugins/conserve/skills/context-map/SKILL.md
1---2name: context-map-23description: Generates a compressed project context map to avoid expensive Read/Grep calls. Use at session start or before implementing features in an unfamiliar codebase.4---5
6
7# Context Map
8
9Generate a compressed context map for the current project.
10The map pre-compiles structural knowledge that AI assistants
11would otherwise discover through expensive Read/Grep calls,
12saving thousands of tokens per session.
13
14## When To Use
15
16- At the start of a session to understand project layout
17- Before implementing features to identify entry points
18- When exploring an unfamiliar codebase
19- To reduce token waste from Read calls
20- To identify hot files (high blast radius) before changes
21
22## When NOT To Use
23
24- Context is already over budget mid-session (use
25 `conserve:clear-context`)
26- Auditing the codebase for bloat (use `conserve:bloat-detector`)
27
28## What It Detects
29
30| Category | Description |
31|----------|-------------|
32| Structure | Directory layout with file counts and languages |
33| Dependencies | Multi-ecosystem: Python, Node, Rust, Go, Java |
34| Frameworks | Framework detection from dependency analysis |
35| Entry Points | main.py, index.ts, CLI scripts, etc. |
36| **Import Graph** | File-to-file import relationships |
37| **Hot Files** | Files imported by 3+ others (high blast radius) |
38| **Routes** | FastAPI, Flask, Express, Hono API endpoints |
39| **Env Vars** | Environment variable references with defaults |
40| **Middleware** | Auth, CORS, rate-limit, logging patterns |
41| **Models/Schemas** | SQLAlchemy, Django, Pydantic, Prisma definitions |
42| **Token Savings** | Estimated tokens saved vs manual exploration |
43
44## Procedure
45
461. Run the scanner on the project root:
47
48```bash
49PYTHONPATH="$(find . -path '*/conserve/scripts' -type d \
50 -print -quit 2>/dev/null || \
51 echo 'plugins/conserve/scripts')" \
52 python3 -m context_scanner .
53```
54
552. Present the output to the user as the project overview.
56
573. Use the context map to guide subsequent file reads.
58 Prioritize hot files and entry points first.
59
60## Options
61
62### Output
63
64- `--format json` for structured output
65- `--max-tokens N` to adjust output size (default: 5000)
66- `--output FILE` to save to a file
67
68### Modes
69
70- `--blast FILE` to show blast radius for a specific file
71- `--section NAME` to output a single section
72 (routes, deps, env, hot-files, models, structure,
73 middleware, frameworks)
74- `--wiki-only` to generate wiki articles without stdout
75
76### Opt-out
77
78- `--no-cache` to force a fresh scan
79- `--no-wiki` to skip wiki article generation
80
81## Wiki Articles
82
83The scanner generates per-topic knowledge articles in
84`.codesight/` for selective context loading:
85
86```bash
87python3 scanner.py .
88# Creates .codesight/INDEX.md, auth.md, database.md, etc.
89```
90
91Load only what you need per session instead of the full map:
92
93```bash
94python3 scanner.py --section routes .
95# ~200 tokens vs ~5,000 for the full map
96```
97
98## Example Output
99
100```
101# Context Map: myproject
102Files: 127
103
104## Structure
105 src 42 files (Python)
106 tests 18 files (Python)
107 docs 5 files (Markdown)
108
109## Dependencies (Python)
110Package manager: uv
111 - fastapi 0.104.0
112 - pydantic 2.5.0
113 - sqlalchemy 2.0.0
114 ...12 more
115
116## Frameworks Detected
117 - FastAPI
118 - SQLAlchemy
119 - Pytest
120
121## Routes
122 GET /users (src/routes/users.py)
123 POST /users (src/routes/users.py)
124 GET /users/{id} (src/routes/users.py)
125
126## Hot Files (high blast radius)
127 - src/models/base.py (12 importers)
128 - src/utils/auth.py (8 importers)
129
130## Environment Variables
131 - DATABASE_URL (required)
132 - SECRET_KEY (has default)
133
134## Token Savings: ~12,600 tokens saved
135 Routes: ~1,200
136 Hot files: ~300
137 Env vars: ~200
138 File scanning: ~10,200
139```
140
141## Exit Criteria
142
143- [ ] Scanner produces output covering at minimum: file count,
144 directory structure, detected frameworks, and hot files (imported
145 by 3+ others); output appears in the session before any feature
146 implementation reads begin
147- [ ] "Token Savings" line is present in the output with a numeric
148 estimate (e.g., `~12,600 tokens saved`)
149- [ ] If `--blast FILE` is used, blast-radius output names the
150 specific file and lists its importers by count
151- [ ] Context map guides subsequent reads: hot files and entry points
152 are consulted before any other file read in the session
153
154---
155
156**Source:** [`athola/claude-night-market`](https://github.com/athola/claude-night-market) → `plugins/conserve/skills/context-map/SKILL.md`
athola