Houseofmvps/codesight

당신의 AI 어시스턴트는 프로젝트를 파악하는 데만 매 대화마다 수천 개의 토큰 (tokens)을 낭비합니다. codesight는 단 한 번의 명령으로 이 문제를 해결합니다.

4,000회 이상의 다운로드 및 지속적인 증가 중.

의존성 제로 (Zero dependencies). AST 정밀도. 30개 이상의 프레임워크 탐지기. 13개의 ORM 파서. 13개의 MCP 도구. 단 한 번의 npx 호출.

TypeScript, JavaScript, Python, Go, Ruby, Elixir, Java, Kotlin, Rust, PHP, Dart, Swift, C#, 그리고 BrightScript/BrighterScript (Roku)와 함께 작동합니다. TypeScript 프로젝트는 완전한 AST 정밀도를 제공받습니다. 그 외의 모든 언어는 동일한 30개 이상의 프레임워크에 대해 검증된 정규 표현식 (regex) 탐지를 사용합니다.

HouseofMVPs 및 Kailxlabs의 설립자인 Kailesk Khumar가 제작했습니다.

참고: ultraship (Claude Code를 위한 39가지 전문가 기술) · claude-rank (Claude Code를 위한 SEO/GEO/AEO 플러그인)

의존성 0 · Node.js >= 18 · 27개 테스트 · 13개 MCP 도구 · MIT 라이선스 · 14개 언어에 걸친 25개 이상의 오픈 소스 (OSS) 프로젝트에서 테스트됨

Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Windsurf, Cline, Aider, 그리고 마크다운 (markdown)을 읽을 수 있는 모든 도구와 호환됩니다.

npx codesight

그게 전부입니다. 어떤 프로젝트 루트에서도 실행하세요. 설정도, 설치도, API 키도 필요 없습니다.

npx codesight --wiki # 위키 지식 베이스 생성 (.codesight/wiki/)
npx codesight --init # CLAUDE.md, .cursorrules, codex.md, AGENTS.md 생성
npx codesight --open # 브라우저에서 대화형 HTML 보고서 열기
...

Karpathy의 LLM 위키 패턴에서 영감을 받았지만, LLM이 아닌 AST로부터 컴파일되었습니다. API 호출이 전혀 없습니다. 200ms 만에 완료됩니다.

npx codesight --wiki

.codesight/wiki/를 생성합니다.

— 모든 세션에 걸쳐 유지되는 코드베이스의 영구적인 지식 베이스입니다:

.codesight/wiki/
index.md — 모든 문서의 카탈로그 (~200 토큰) — 세션 시작 시 이를 읽습니다
overview.md — 아키텍처 (architecture), 서브시스템 (subsystems), 영향력이 큰 파일들 (~500 토큰)
...

이 방식이 토큰 사용량을 더욱 줄이는 이유:

매 대화마다 전체 5K 토큰 컨텍스트 맵 (context map)을 로드하는 대신, AI는 하나의 타겟팅된 문서만을 읽습니다.

질문	wiki 미사용 시	wiki 사용 시
"인증(auth)은 어떻게 작동하나요?"	~12K 토큰 (8개 이상의 파일 읽음)	~300 토큰 (auth.md)
...

세션 간 지속성 (Persistent across sessions). wiki는 git에 커밋되는 .codesight/wiki/ 디렉토리에 저장됩니다. 따라서 모든 새로운 Claude Code, Cursor 또는 Codex 세션은 첫 번째 메시지부터 전체 코드베이스 지식을 갖춘 상태로 시작됩니다.

자동 재생성 (Auto-regenerates). 코드를 작성하는 동안 wiki를 최신 상태로 유지하려면 --watch를 사용하세요. 모든 커밋 시점에 재생성하려면 --hook을 사용하세요.

wiki 접근을 위한 3가지 새로운 MCP 도구:

도구	기능
codesight_get_wiki_index	세션 시작 시 wiki 카탈로그를 가져옵니다 (~200 토큰)
codesight_get_wiki_article	이름을 통해 하나의 문서를 읽습니다: auth, database, payments 등
codesight_lint_wiki	상태 점검: 고립된 문서(orphan articles), 누락된 교차 링크(cross-links), 오래된 콘텐츠

범용 wiki 도구와의 핵심적인 차이점은 다음과 같습니다: codesight는 AST (Abstract Syntax Tree)로부터 이미 귀하의 라우트(routes), 스키마(schema), 영향 범위(blast radius), 미들웨어(middleware)를 알고 있습니다. 즉, 코드 구조를 추출하기 위해 LLM(Large Language Model)이 필요하지 않습니다. wiki는 코드베이스가 이미 보유하고 있는 데이터 위에 구축된 서사 계층 (narrative layer)입니다.

단순히 코드뿐만이 아닙니다. 귀하의 결정 사항, 회의록, ADR (Architecture Decision Records), 회고(retrospectives)는 코드베이스 자체만큼이나 많은 컨텍스트 (context)를 담고 있습니다. --mode knowledge는 codesight가 코드를 매핑하는 것과 동일한 방식으로 이들을 매핑합니다.

npx codesight --mode knowledge # 현재 디렉토리에서 .md 파일 스캔
npx codesight --mode knowledge ~/vault # Obsidian vault 스캔
npx codesight --mode knowledge ./docs # 프로젝트 문서 폴더 스캔

결과물로 .codesight/KNOWLEDGE.md를 생성합니다. 이는 압축된 AI 컨텍스트 프라이머 (context primer) 역할을 합니다:

# Knowledge Map — my-project
> 47개의 노트 · 12개의 결정 · 8개의 미결 질문 · 2025-09-01 → 2026-04-01
## 주요 결정 사항 (12)
...

자동으로 감지하는 항목:

노트 유형	신호 (Signals)
결정 기록 (Decision records)	ADR 형식 (## Decision), "decided to", "going with", "chose X over Y"
...

지원 사항:

• Obsidian vaults (YAML frontmatter, [[backlinks]], #tags)
• Notion 내보내기 (.md 파일 및 frontmatter)
• ADR 도구 (adr-tools)

, Log4brains

, raw markdown) - 모든 마크다운 파일이 포함된 폴더

함께 사용 시:

.codesight/CODESIGHT.md 읽기 → 코드가 무엇을 하는지 파악
.codesight/KNOWLEDGE.md 읽기 → 결정이 내려진 이유를 파악

CI: 기존 codesight 단계와 함께 npx codesight --mode knowledge를 추가하세요. 두 파일 모두 매 푸시(push)마다 최신 상태로 유지됩니다.

아래의 모든 수치는 실제 프로덕션 코드베이스 — 소규모 SaaS 프로젝트(v1.6.2)와 4,000~10,000개 이상의 파일을 가진 대규모 오픈 소스 플랫폼(v1.6.4) — 에 codesight를 실행하여 얻은 결과입니다. 출력 토큰(Output tokens)은 실제 파일 크기(문자 수 / 4)를 기준으로 측정되었습니다. 탐색 토큰(Exploration tokens)은 추출된 항목을 바탕으로 추정되었습니다 — 라우트(routes) × 400, 모델(models) × 300, 컴포넌트(components) × 250 등. 라우트 수와 모델 수는 실제 소스 파일과 대조하여 확인되었습니다.

codesight는 두 개의 별도 계층에서 토큰을 절약합니다. 위키(v1.6.2)는 기본 절약 기능 위에 두 번째 계층을 추가합니다:

프로젝트	수동 탐색	codesight 스캔	codesight --wiki (타겟팅)	총 절감률
SaaS A	46,020 토큰	3,936 토큰 (11.7x)	~550 토큰	83.7x
SaaS B	26,130 토큰	3,629 토큰 (7.2x)	~440 토큰	59.4x
SaaS C	47,450 토큰	4,162 토큰 (11.4x)	~360 토큰	131.8x

평균 결합 절감률: 91배. 위키의 "타겟팅(targeted)" 수치는 세션 시작 시 index.md를 읽는 것(~200 토큰) + 프로젝트에 따라 하나의 관련 문서(~160-350 토큰)를 읽는 것을 의미합니다. 귀하의 AI는 타겟팅된 질문을 위해 전체 컨텍스트 맵(context map)을 로드하지 않습니다.

두 가지 절약 계층은 독립적이며 복리로 작용합니다:

계층 1 — codesight 스캔은 수동 파일 탐색을 제거합니다. AI가 프로젝트를 이해하기 위해 40~138개의 파일에 대해 glob/grep/read를 실행하는 대신, 미리 컴파일된 하나의 맵을 읽습니다.

계층 2 — --wiki는 모든 질문에 대해 전체 맵을 로드하는 것을 제거합니다. 세션 시작 시 3,000~5,000 토큰의 전체 컨텍스트를 로드하는 대신, AI는 200 토큰의 인덱스를 읽고 각 질문에 대해 하나의 관련 문서(~160-350 토큰)를 가져옵니다.

codesight 미사용 시: AI가 파일을 탐색하며 세션당 26K-47K 토큰을 읽음
codesight 사용 시: AI가 ~3K-5K 토큰(컴파일된 맵)을 읽음
--wiki 사용 시: AI가 시작 시 ~200 토큰 + 타겟 질문당 ~300 토큰을 읽음

프로젝트	스택 (Stack)	파일 (Files)	라우트 (Routes)	모델 (Models)	컴포넌트 (Components)	출력 토큰 (Output Tokens)	탐색 토큰 (Exploration Tokens)	절감 (Savings)	스캔 시간 (Scan Time)
SaaS A	Hono + Drizzle	138	38	12	0	3,936	46,020	11.7x	186ms
SaaS B	Hono + Drizzle, 3개 워크스페이스	53	17	8	10	3,629	26,130	7.2x	201ms
SaaS C	FastAPI + MongoDB	40	56	0	0	4,162	47,450	11.4x	890ms

SaaS C는 MongoDB를 사용하기 때문에 모델 (Models)이 0개입니다. 즉, codesight가 파싱할 SQL ORM 선언이 없습니다. 이는 잘못된 탐지(False Negative)가 아닌 정확한 탐지입니다.

지원되는 모든 언어와 프레임워크를 아우르는 실제 오픈 소스 코드베이스(Open-source codebases)를 대상으로 테스트되었습니다. 출력 토큰 (Output tokens)은 실제 파일 크기를 기준으로 측정되었습니다. 탐색 토큰 (Exploration tokens)은 추정치입니다 (라우트×400 + 모델×300 + 컴포넌트×250 + 재방문 승수). 모든 테스트에서 위양성 (False positives)은 0건이었습니다.

언어 (Language)	스택 (Stack)	파일 (Files)	라우트 (Routes)	모델 (Models)	컴포넌트 (Components)	출력 토큰 (Output tokens)	추정 탐색 (Est. exploration)	절감률 (Savings)
TypeScript · Next.js	Next.js + tRPC + Prisma · 110+ workspaces	7,509	479	173	1,309	158,660	~1,485,000	~9x
TypeScript · NestJS	NestJS + TypeORM + Mongoose	162	19	8	0	5,300	~67,500	~12.7x
TypeScript · Hono	Hono	—	8	0	0	—	—	✓
TypeScript · Remix	Remix + Prisma	36	11	0	9	—	—	✓
TypeScript · SvelteKit	SvelteKit	—	0³	0	23	—	—	✓
TypeScript · Nuxt	Nuxt	141	8	0	64	—	—	✓
JavaScript · Express	Express + Mongoose	51	10	5	0	1,241	~20,800	~17x
Ruby · Rails	Rails + ActiveRecord	4,172	607	116	0	21,711	~386,100	~17.8x
PHP · Laravel	Laravel + Eloquent	3,896	652	59	0	30,739	~493,285	~16x
Python · Django	Django + pyproject.toml	4,232	7¹	56	0	83,842	~631,020	~7.5x
Python · Flask

¹ Django 프로젝트는 GraphQL-first 방식입니다 — 7개의 REST 유틸리티 엔드포인트(endpoints)를 정확하게 탐지했으며, 오탐(false positives)은 0개입니다.
² 작은 보일러플레이트(boilerplate)에서 높은 비율을 보입니다: Spring Boot 라우트 메타데이터는 압축 효율이 매우 좋습니다.
³ SvelteKit RealWorld 앱은 JSON API 엔드포인트(+server.ts)가 아닌 페이지 라우트(+page.svelte)를 사용합니다. 0개의 라우트가 탐지된 것은 정확합니다.

탐색 토큰(exploration tokens) 추정 방식: routes×400 + models×300 + components×250 + hot_files×150 + env_vars×30에 재방문 승수(revisit multiplier) 1.3을 곱한 후 출력 크기를 뺍니다. 이는 AI가 수동 탐색 세션에서 "어떤 라우트가 존재하나요?", "스키마를 보여주세요" 등을 물어보며 소비할 양을 근사화한 것입니다. 출력 토큰(Output token) 수는 실제 측정된 파일 크기입니다.

프로젝트	전체 CODESIGHT.md	위키(Wiki) 인덱스만	인덱스 + 기사 1개	생성된 위키 기사 수
SaaS A	3,936 토큰	~200 토큰	~550 토큰	9
SaaS B	3,629 토큰	~200 토큰	~440 토큰	11
SaaS C	4,162 토큰	~200 토큰	~360 토큰	17

"인증(auth)은 어떻게 작동하나요?" — 위키가 없을 때: 3,945 토큰을 로드합니다. 위키가 있을 때: auth.md (~350 토큰)를 읽습니다. 타겟 질문당 11배 개선, 수동 방식 대비 총 84배 개선되었습니다.

실제 소스 파일과 대조하여 검증되었습니다. 라우트 수는 라우트 정의와 교차 확인되었으며, 스키마 모델은 ORM 테이블 선언과 교차 확인되었습니다.

프로젝트	라우트 재현율(Route Recall)	스키마 재현율(Schema Recall)	오탐(False Positives)	탐지 방법
SaaS A	38/43 (88%)	12/12 (100%)	0	스키마: AST (Drizzle), 라우트: AST (Hono)
SaaS B	17/17 (100%)	8/8 (100%)	0	전체 AST (Hono + Drizzle + React)
SaaS C	56/59 (~95%)	0/0 (정확함)	0	AST (FastAPI + MongoDB)

SaaS A에서 놓친 5개의 라우트는 요청 핸들러(request handlers) 내부에서 동적 url.match(/pattern/)를 사용합니다. 이는 정적 분석(static analysis)이 스캔 시점에 해결할 수 없는 개발 패턴입니다. 이는 프레임워크의 결함이 아니라 정적 분석의 내재적 한계입니다. SaaS C는 59개의 FastAPI 라우트 중 약 3개를 놓쳤습니다. 세 프로젝트 모두 오탐은 0개였습니다.

실제 운영 중인 SaaS에서 테스트한 결과, 데이터베이스 모듈을 변경했을 때 다음과 같은 사항들을 정확히 식별했습니다:

API, 인증(auth), 서버 레이어 전반에 걸친 5개의 영향받은 파일
데이터베이스에 접근하는 모든 라우트 (All routes)
12개의 영향받은 모델 (전체 스키마 (schema))
BFS 깊이 (BFS depth): 임포트 그래프 (import graph)를 통한 3홉 (3 hops)

세 가지 벤치마크 프로젝트를 통해 측정한 결과입니다:

탐지기 (Detector)	SaaS A (138개 파일)	SaaS B (53개 파일)	SaaS C (40개 파일)
라우트 (Routes)	38	17	56
스키마 모델 (Schema models)	12	8	0
컴포넌트 (Components)	0	10	0
환경 변수 (Env vars)	12	7	15
핫 파일 (Hot files)	20	20	20

codesight는 8개의 탐지기를 모두 병렬로 실행한 다음, 결과를 구조화된 마크다운 (markdown) 형식으로 작성합니다. 출력물은 AI가 단일 파일 로드만으로 읽을 수 있도록 설계되었습니다.

.codesight/
CODESIGHT.md 통합 컨텍스트 맵 (단일 파일, 프로젝트 전체 이해)
routes.md 메서드, 경로, 파라미터 및 관련 요소를 포함한 모든 API 라우트
...

스캔 중인 프로젝트에 TypeScript가 설치되어 있는 경우, codesight는 실제 TypeScript 컴파일러 API (compiler API)를 사용하여 코드를 구조적으로 파싱 (parse)합니다. 정규 표현식 (regex)을 통한 추측은 하지 않습니다.

AST가 가능하게 하는 것	정규 표현식 (Regex)만 사용할 경우
router.use('/prefix', subRouter) 체인을 추적	중첩된 라우터 (nested routers)를 놓침
@Controller('users') + @Get(':id')를 /users/:id로 결합	접두사 (prefix)를 놓칠 수 있음
router({ users: userRouter }) tRPC 중첩 파싱	라인 단위 매칭 (Line-by-line matching)
.primaryKey().notNull() 체인에서 정확한 Drizzle 필드 타입 추출	패턴 매칭 (Pattern matching)
TypeScript 인터페이스 및 구조 분해 할당에서 React props 추출	{ prop }에 대한 정규 표현식 사용
라우트 체인 내의 미들웨어 (middleware) 탐지: app.get('/path', auth, handler)	캡처되지 않음
c.get('userId')와 같은 비라우트 호출 필터링	오탐 (false-positive) 가능성 있음

AST 탐지 결과는 출력물에 다음과 같이 보고됩니다:

Analyzing... done (AST: 60 routes, 18 models, 16 components)