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