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