codesight 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +136 -106
- package/dist/index.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,113 +1,148 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
### Your AI assistant wastes thousands of tokens every conversation just figuring out your project. codesight fixes that in one command.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
5
|
+
**Zero dependencies. 11 framework detectors. 4 ORM parsers. MCP server. One `npx` call.**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/codesight)
|
|
8
|
+
[](https://www.npmjs.com/package/codesight)
|
|
9
|
+
[](https://www.npmjs.com/package/codesight)
|
|
10
|
+
[](https://github.com/Houseofmvps/codesight/stargazers)
|
|
11
|
+
[](LICENSE)
|
|
12
|
+
[](https://github.com/sponsors/Houseofmvps)
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
[](https://x.com/kaileskkhumar)
|
|
17
|
+
[](https://www.linkedin.com/in/kailesk-khumar)
|
|
18
|
+
[](https://houseofmvps.com)
|
|
19
|
+
|
|
20
|
+
**Built by [Kailesk Khumar](https://www.linkedin.com/in/kailesk-khumar), solo founder of [houseofmvps.com](https://houseofmvps.com)**
|
|
8
21
|
|
|
9
|
-
|
|
22
|
+
*Also: [ultraship](https://github.com/Houseofmvps/ultraship) (39 expert skills for Claude Code) · [claude-rank](https://github.com/Houseofmvps/claude-rank) (SEO/GEO/AEO plugin for Claude Code)*
|
|
10
23
|
|
|
11
|
-
|
|
24
|
+
</div>
|
|
12
25
|
|
|
13
|
-
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
0 dependencies · Node.js >= 18 · MIT
|
|
30
|
+
```
|
|
14
31
|
|
|
15
|
-
|
|
32
|
+
## Install
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
npx codesight
|
|
36
|
+
```
|
|
16
37
|
|
|
17
|
-
|
|
38
|
+
That's it. Run it in any project root. No config, no setup, no API keys.
|
|
18
39
|
|
|
19
40
|
```bash
|
|
20
|
-
npx codesight # Scan and generate context
|
|
21
41
|
npx codesight --init # Also generate CLAUDE.md, .cursorrules, codex.md, AGENTS.md
|
|
22
42
|
npx codesight --open # Also open interactive HTML report in browser
|
|
43
|
+
npx codesight --mcp # Start as MCP server for Claude Code / Cursor
|
|
23
44
|
```
|
|
24
45
|
|
|
25
|
-
## What It
|
|
46
|
+
## What It Does
|
|
47
|
+
|
|
48
|
+
Every AI coding conversation starts the same way. Your assistant reads files, greps for patterns, opens configs, just to understand the project. That exploration costs tens of thousands of tokens before it writes a single line of code.
|
|
49
|
+
|
|
50
|
+
codesight scans your codebase once and generates a structured context map. Routes, database schema, components, dependencies, environment variables, middleware, all condensed into ~3,000 to 5,000 tokens of structured markdown. Your AI reads one file and knows the entire project.
|
|
26
51
|
|
|
27
52
|
```
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
schema.md # Database models with fields, types, PKs, FKs, relations
|
|
32
|
-
components.md # UI components with props (shadcn/radix filtered out)
|
|
33
|
-
libs.md # Library exports with function signatures
|
|
34
|
-
config.md # Env vars (required vs default), config files, key deps
|
|
35
|
-
middleware.md # Auth, rate limiting, CORS, validation, logging
|
|
36
|
-
graph.md # Dependency graph: most-imported files + import map
|
|
37
|
-
report.html # Interactive visual report (with --html or --open)
|
|
53
|
+
Output size: ~3,200 tokens
|
|
54
|
+
Exploration cost: ~52,000 tokens (without codesight)
|
|
55
|
+
Saved: ~48,800 tokens per conversation
|
|
38
56
|
```
|
|
39
57
|
|
|
40
|
-
|
|
58
|
+
Works with **Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Windsurf, Cline**, and anything that reads markdown.
|
|
41
59
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
```markdown
|
|
45
|
-
# savemrr — AI Context Map
|
|
60
|
+
## What It Generates
|
|
46
61
|
|
|
47
|
-
|
|
48
|
-
|
|
62
|
+
```
|
|
63
|
+
.codesight/
|
|
64
|
+
CODESIGHT.md Combined context map (one file, full project understanding)
|
|
65
|
+
routes.md Every API route with method, path, params, and what it touches
|
|
66
|
+
schema.md Every database model with fields, types, keys, and relations
|
|
67
|
+
components.md Every UI component with its props
|
|
68
|
+
libs.md Every library export with function signatures
|
|
69
|
+
config.md Every env var (required vs default), config files, key deps
|
|
70
|
+
middleware.md Auth, rate limiting, CORS, validation, logging, error handlers
|
|
71
|
+
graph.md Which files import what and which break the most things if changed
|
|
72
|
+
report.html Interactive visual dashboard (with --html or --open)
|
|
73
|
+
```
|
|
49
74
|
|
|
50
|
-
|
|
51
|
-
> **Token savings:** this file is ~4,041 tokens. Without it, AI exploration would cost ~68,640 tokens.
|
|
52
|
-
> **Saves ~64,599 tokens per conversation.**
|
|
75
|
+
## Routes
|
|
53
76
|
|
|
54
|
-
|
|
77
|
+
Not just paths. Methods, URL parameters, what each route touches (auth, database, cache, payments, AI, email, queues), and where the handler lives. Detects routes across 11 frameworks automatically.
|
|
55
78
|
|
|
56
|
-
|
|
79
|
+
```markdown
|
|
80
|
+
- `POST` `/auth/login` [auth, db, email]
|
|
81
|
+
- `GET` `/api/projects/:id/analytics` params(id) [auth, db, cache]
|
|
82
|
+
- `POST` `/api/billing/checkout` [auth, db, payment]
|
|
83
|
+
- `POST` `/api/webhooks/stripe` [payment]
|
|
84
|
+
```
|
|
57
85
|
|
|
58
|
-
|
|
59
|
-
- `POST` `/verify` [auth, db, cache, email]
|
|
60
|
-
- `GET` `/me` [auth, db, cache, email]
|
|
61
|
-
- `GET` `/overview` [auth, db, queue, payment, ai]
|
|
62
|
-
- `GET` `/shield` [auth, db, queue, payment, ai]
|
|
63
|
-
- `GET` `/rescue` [auth, db, queue, payment, ai]
|
|
64
|
-
- `POST` `/rescue/:id/send-now` params(id) [auth, db, queue, payment, ai]
|
|
65
|
-
...
|
|
86
|
+
## Schema
|
|
66
87
|
|
|
67
|
-
|
|
88
|
+
Models, fields, types, primary keys, foreign keys, unique constraints, relations. Parsed directly from your ORM definitions. No need to open migration files.
|
|
68
89
|
|
|
90
|
+
```markdown
|
|
69
91
|
### users
|
|
70
92
|
- id: uuid (pk, default)
|
|
71
93
|
- email: text (unique, required)
|
|
72
|
-
-
|
|
73
|
-
-
|
|
74
|
-
- settings: jsonb (required, default)
|
|
94
|
+
- plan: text (required, default)
|
|
95
|
+
- stripeCustomerId: text (fk)
|
|
75
96
|
|
|
76
|
-
###
|
|
97
|
+
### projects
|
|
77
98
|
- id: uuid (pk, default)
|
|
78
99
|
- userId: uuid (fk)
|
|
79
|
-
|
|
100
|
+
- name: text (required)
|
|
101
|
+
- domain: text (unique)
|
|
102
|
+
- _relations_: userId -> users.id
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
## Dependency Graph
|
|
80
106
|
|
|
81
|
-
|
|
107
|
+
The files imported the most are the ones that break the most things when changed. codesight finds them and tells your AI to be careful.
|
|
82
108
|
|
|
109
|
+
```markdown
|
|
83
110
|
## Most Imported Files (change these carefully)
|
|
84
|
-
- `packages/shared/src/index.ts` — imported by **
|
|
85
|
-
- `apps/api/src/lib/db.ts` — imported by **
|
|
86
|
-
- `apps/api/src/lib/auth.ts` — imported by **
|
|
111
|
+
- `packages/shared/src/index.ts` — imported by **14** files
|
|
112
|
+
- `apps/api/src/lib/db.ts` — imported by **9** files
|
|
113
|
+
- `apps/api/src/lib/auth.ts` — imported by **7** files
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
## Environment Audit
|
|
117
|
+
|
|
118
|
+
Every env var across your codebase, flagged as required or has default, with the exact file where it is referenced.
|
|
119
|
+
|
|
120
|
+
```markdown
|
|
121
|
+
- `DATABASE_URL` **required** — apps/api/src/lib/db.ts
|
|
122
|
+
- `JWT_SECRET` **required** — apps/api/src/lib/auth.ts
|
|
123
|
+
- `PORT` (has default) — apps/api/src/index.ts
|
|
87
124
|
```
|
|
88
125
|
|
|
89
|
-
##
|
|
126
|
+
## Supported Stacks
|
|
90
127
|
|
|
91
128
|
| Category | Supported |
|
|
92
129
|
|---|---|
|
|
93
130
|
| **Routes** | Hono, Express, Fastify, Next.js (App + Pages), Koa, FastAPI, Flask, Django, Go (net/http, Gin, Fiber) |
|
|
94
131
|
| **Schema** | Drizzle, Prisma, TypeORM, SQLAlchemy |
|
|
95
|
-
| **Components** | React, Vue, Svelte (filters
|
|
96
|
-
| **Libraries** | TypeScript
|
|
97
|
-
| **Config** | Environment variables (required vs defaults), config files, notable dependencies |
|
|
132
|
+
| **Components** | React, Vue, Svelte (auto-filters shadcn/ui and Radix primitives) |
|
|
133
|
+
| **Libraries** | TypeScript, JavaScript, Python, Go (exports with function signatures) |
|
|
98
134
|
| **Middleware** | Auth, rate limiting, CORS, validation, logging, error handlers |
|
|
99
135
|
| **Dependencies** | Import graph with hot file detection (most imported = highest blast radius) |
|
|
100
|
-
| **Contracts** | URL params, request types, response types
|
|
101
|
-
| **Monorepos** | pnpm, npm, yarn workspaces
|
|
102
|
-
| **Languages** | TypeScript, JavaScript, Python, Go |
|
|
136
|
+
| **Contracts** | URL params, request types, response types from route handlers |
|
|
137
|
+
| **Monorepos** | pnpm, npm, yarn workspaces (cross-workspace detection) |
|
|
103
138
|
|
|
104
|
-
##
|
|
139
|
+
## AI Config Generation
|
|
105
140
|
|
|
106
141
|
```bash
|
|
107
142
|
npx codesight --init
|
|
108
143
|
```
|
|
109
144
|
|
|
110
|
-
Generates instruction files for every major AI coding tool:
|
|
145
|
+
Generates ready-to-use instruction files for every major AI coding tool at once:
|
|
111
146
|
|
|
112
147
|
| File | Tool |
|
|
113
148
|
|---|---|
|
|
@@ -115,25 +150,9 @@ Generates instruction files for every major AI coding tool:
|
|
|
115
150
|
| `.cursorrules` | Cursor |
|
|
116
151
|
| `.github/copilot-instructions.md` | GitHub Copilot |
|
|
117
152
|
| `codex.md` | OpenAI Codex CLI |
|
|
118
|
-
| `AGENTS.md` | OpenAI Codex |
|
|
119
|
-
|
|
120
|
-
Each file includes your project's stack, key architecture facts, hot files, and required env vars so your AI assistant knows the project from the first message.
|
|
121
|
-
|
|
122
|
-
## Interactive HTML Report
|
|
153
|
+
| `AGENTS.md` | OpenAI Codex agents |
|
|
123
154
|
|
|
124
|
-
|
|
125
|
-
npx codesight --open
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
Generates a visual dashboard with:
|
|
129
|
-
- Token savings hero metric
|
|
130
|
-
- Route table with methods, contracts, and tags
|
|
131
|
-
- Schema cards with fields and relations
|
|
132
|
-
- Dependency hot files with impact bars
|
|
133
|
-
- Environment variables (required vs defaults)
|
|
134
|
-
- Full middleware map
|
|
135
|
-
|
|
136
|
-
Screenshots of this report are what go viral on Twitter.
|
|
155
|
+
Each file is pre-filled with your project's stack, architecture, high-impact files, and required env vars. Your AI reads it on startup and starts with full context from the first message.
|
|
137
156
|
|
|
138
157
|
## MCP Server
|
|
139
158
|
|
|
@@ -141,7 +160,7 @@ Screenshots of this report are what go viral on Twitter.
|
|
|
141
160
|
npx codesight --mcp
|
|
142
161
|
```
|
|
143
162
|
|
|
144
|
-
Runs as a Model Context Protocol server
|
|
163
|
+
Runs as a Model Context Protocol server. Claude Code and Cursor call it directly to get project context on demand.
|
|
145
164
|
|
|
146
165
|
```json
|
|
147
166
|
{
|
|
@@ -154,23 +173,31 @@ Runs as a Model Context Protocol server that Claude Code and Cursor can connect
|
|
|
154
173
|
}
|
|
155
174
|
```
|
|
156
175
|
|
|
157
|
-
Your AI
|
|
176
|
+
Exposes one tool: `codesight_scan`. Your AI calls it whenever it needs to understand the project.
|
|
158
177
|
|
|
159
|
-
##
|
|
178
|
+
## Visual Report
|
|
160
179
|
|
|
161
180
|
```bash
|
|
162
|
-
npx codesight --
|
|
181
|
+
npx codesight --open
|
|
163
182
|
```
|
|
164
183
|
|
|
165
|
-
|
|
184
|
+
Opens an interactive HTML dashboard in your browser. Routes table with method badges and tags. Schema cards with fields and relations. Dependency hot files with impact bars. Env var audit. Token savings breakdown. Useful for onboarding or just seeing your project from above.
|
|
185
|
+
|
|
186
|
+
## Watch Mode and Git Hook
|
|
166
187
|
|
|
167
|
-
|
|
188
|
+
**Watch mode** re-scans when files change:
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
npx codesight --watch
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
**Git hook** regenerates context on every commit:
|
|
168
195
|
|
|
169
196
|
```bash
|
|
170
197
|
npx codesight --hook
|
|
171
198
|
```
|
|
172
199
|
|
|
173
|
-
|
|
200
|
+
Context stays fresh without thinking about it.
|
|
174
201
|
|
|
175
202
|
## All Options
|
|
176
203
|
|
|
@@ -178,36 +205,39 @@ Installs a git pre-commit hook that regenerates context on every commit. Context
|
|
|
178
205
|
npx codesight # Scan current directory
|
|
179
206
|
npx codesight ./my-project # Scan specific directory
|
|
180
207
|
npx codesight --init # Generate AI config files
|
|
181
|
-
npx codesight --open # Open
|
|
182
|
-
npx codesight --html # Generate HTML report
|
|
208
|
+
npx codesight --open # Open visual HTML report
|
|
209
|
+
npx codesight --html # Generate HTML report without opening
|
|
183
210
|
npx codesight --mcp # Start MCP server
|
|
184
211
|
npx codesight --watch # Watch mode
|
|
185
212
|
npx codesight --hook # Install git pre-commit hook
|
|
186
|
-
npx codesight --json # Output JSON
|
|
213
|
+
npx codesight --json # Output as JSON
|
|
187
214
|
npx codesight -o .ai-context # Custom output directory
|
|
188
215
|
npx codesight -d 5 # Limit directory depth
|
|
189
216
|
```
|
|
190
217
|
|
|
191
|
-
##
|
|
192
|
-
|
|
193
|
-
Repomix dumps your entire codebase into one file. codesight maps your architecture.
|
|
218
|
+
## Contributing
|
|
194
219
|
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
| **Schema understanding** | Read every migration | Instant from schema.md |
|
|
203
|
-
| **Change blast radius** | Unknown | Visible in dependency graph |
|
|
204
|
-
| **AI config generation** | No | CLAUDE.md, .cursorrules, codex.md, AGENTS.md |
|
|
205
|
-
| **Runtime deps** | 26 | **Zero** |
|
|
206
|
-
|
|
207
|
-
## Zero Dependencies
|
|
220
|
+
```bash
|
|
221
|
+
git clone https://github.com/Houseofmvps/codesight.git
|
|
222
|
+
cd codesight
|
|
223
|
+
pnpm install
|
|
224
|
+
pnpm dev # Run locally
|
|
225
|
+
pnpm build # Compile TypeScript
|
|
226
|
+
```
|
|
208
227
|
|
|
209
|
-
|
|
228
|
+
PRs welcome. Open an issue first for large changes.
|
|
210
229
|
|
|
211
230
|
## License
|
|
212
231
|
|
|
213
232
|
MIT
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
<div align="center">
|
|
237
|
+
|
|
238
|
+
If codesight saves you tokens, [star it on GitHub](https://github.com/Houseofmvps/codesight) so others find it too.
|
|
239
|
+
|
|
240
|
+
[](https://github.com/Houseofmvps/codesight/stargazers)
|
|
241
|
+
[](https://github.com/sponsors/Houseofmvps)
|
|
242
|
+
|
|
243
|
+
</div>
|
package/dist/index.js
CHANGED
|
@@ -14,7 +14,7 @@ import { calculateTokenStats } from "./detectors/tokens.js";
|
|
|
14
14
|
import { writeOutput } from "./formatter.js";
|
|
15
15
|
import { generateAIConfigs } from "./generators/ai-config.js";
|
|
16
16
|
import { generateHtmlReport } from "./generators/html-report.js";
|
|
17
|
-
const VERSION = "1.0.
|
|
17
|
+
const VERSION = "1.0.1";
|
|
18
18
|
const BRAND = "codesight";
|
|
19
19
|
function printHelp() {
|
|
20
20
|
console.log(`
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "codesight",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.1",
|
|
4
4
|
"description": "See your codebase clearly. Universal AI context generator that maps routes, schema, components, dependencies, and more for Claude Code, Cursor, Copilot, Codex, and any AI coding tool.",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"bin": {
|