glincker/stacklit

108,000줄의 코드. 4,000 토큰의 인덱스.

단 한 번의 명령으로 어떤 저장소(repo)든 AI 에이전트(AI-agent)를 위한 준비를 마칠 수 있습니다. 서버도, 설정도 필요 없습니다.

npx stacklit init

이것이 전부입니다. 바이너리(binary)를 다운로드하고, 코드베이스(codebase)를 스캔하며, 인덱스(index)를 생성하고, 시각적 지도(visual map)를 엽니다. 단 한 번의 명령으로 말이죠.

다른 설치 옵션:

npm install -g stacklit # 전역(globally) 설치 후, 다음 실행: stacklit init
go install github.com/glincker/stacklit/cmd/stacklit@latest

또는 GitHub Releases에서 바이너리(binary)를 가져올 수 있습니다 (macOS, Linux, Windows).

glincker/stacklit-action을 사용하여 인덱스를 자동으로 최신 상태로 유지하세요. 푸시(push) 시 자동 커밋(auto-commit)하거나, 체크 모드(check mode)로 PR(Pull Request)을 제어할 수 있습니다:

- uses: actions/checkout@v4
- uses: glincker/stacklit-action@v1 # 자동 커밋 (기본값)
# 또는: with: { mode: check } # 인덱스가 오래된 경우 PR 실패 처리

auto-commit 모드를 사용할 때는 작업(job)에 permissions: contents: write를 추가하세요.

$ stacklit init
[stacklit] found 342 files
[stacklit] parsed 342 files (0 errors)
...

프로젝트에 세 개의 파일이 나타납니다:

파일	역할	커밋 여부?
`stacklit.json`	AI 에이전트(AI agents)를 위한 코드베이스 인덱스	예
`DEPENDENCIES.md`	Mermaid 의존성 다이어그램 (dependency diagram)	예 (GitHub에서 렌더링됨)
`stacklit.html`	대화형 시각적 지도 (4가지 뷰)	아니요 (gitignored 처리, 재생성됨)

git add stacklit.json DEPENDENCIES.md
git commit -m "add stacklit codebase index"

완료되었습니다. 이제 이 저장소를 여는 모든 AI 에이전트는 파일을 일일이 스캔하는 대신 stacklit.json을 읽을 수 있습니다.

AI 코딩 에이전트(AI coding agents)는 파일들이 어디에 위치하는지 파악하는 데 컨텍스트 윈도우(context window)의 대부분을 소모합니다. 함수 시그니처(function signature)를 찾기 위해 하나의 큰 파일을 읽는 것만으로도 수천 개의 토큰(tokens)이 소모됩니다. 동일한 저장소에 있는 다섯 명의 에이전트가 각각 처음부터 똑같은 멘탈 모델(mental model)을 구축하게 됩니다.

stacklit이 없을 때: 에이전트가 8~12개의 파일을 읽음. 약 400,000 토큰 소모. 코드 한 줄을 쓰기 전까지 45초 소요.

stacklit이 있을 때: 에이전트가 stacklit.json을 읽음. 약 4,000 토큰 소모. 즉시 구조를 파악함.

프로젝트	언어	코드 라인 수	인덱스 토큰
Express.js	JavaScript	21,346	3,765
...
전체 출력 결과는 `examples/`를 참조하세요.

{
"modules": {
"src/auth": {
...

모듈 (Modules), 의존성 (dependencies), 시그니처가 포함된 내보내기 (exports with signatures), 타입 정의 (type definitions), git 활동 히트맵 (git activity heatmap), 프레임워크 감지 (framework detection), 그리고 기능을 추가할 위치와 테스트 실행 방법에 대한 힌트 (hints)를 제공합니다.

stacklit setup

Claude Code, Cursor, Aider를 자동으로 감지합니다. 각 도구에 대해 다음을 수행합니다:

도구의 설정 파일에 약 250 토큰 규모의 압축된 코드베이스 맵 (codebase map)을 주입합니다.
MCP 서버 통합을 구성합니다.
매 커밋마다 맵을 최신 상태로 유지하기 위해 git 훅 (git hook)을 설치합니다.

또는 특정 도구를 구성할 수 있습니다:

stacklit setup claude # CLAUDE.md + .mcp.json 업데이트
stacklit setup cursor # .cursorrules + .cursor/mcp.json 업데이트
stacklit setup aider # .aider.conf.yml 업데이트

stacklit derive # stdout으로 출력

에이전트의 탐색에 소모되는 3,000~8,000 토큰을 대체하는 약 250 토큰 규모의 내비게이션 맵 (navigation map)을 생성합니다:

myapp | go | 14 modules | 8,420 lines
entry: cmd/api/main.go | test: go test ./...
modules:
...

대신 수동으로 구성하기

Claude Code - CLAUDE.md에 추가:

파일을 탐색하기 전에 stacklit.json을 읽으세요. 모듈을 사용하여 코드를 찾고, 힌트를 사용하여 컨벤션 (conventions)을 확인하세요.

Claude Desktop / Cursor (MCP) - MCP 설정에 추가:

{
"mcpServers": {
"stacklit": {
...

MCP 서버는 7가지 도구를 노출합니다: get_overview, get_module, find_module, list_modules, get_dependencies, get_hot_files, get_hints.

기타 모든 에이전트 - stacklit.json은 일반적인 JSON 파일입니다. 파일을 읽을 수 있는 모든 도구가 이를 사용할 수 있습니다.

stacklit init --hook

매 커밋마다 인덱스를 재생성하는 git 훅을 설치합니다. 문서나 설정 파일만 변경된 경우에는 Merkle 해싱 (Merkle hashing)을 사용하여 재생성을 건너뜁니다.

최신 상태를 유지하는 다른 방법들:

stacklit generate # 수동 재생성
stacklit generate --quiet # 무음 모드 (스크립트/CI용)
stacklit diff # 인덱스가 오래되었는지 확인

자동 업데이트를 위한 GitHub Action

name: Update stacklit index
on:
  push:
...

stacklit view

대화형 HTML을 엽니다. 네 가지 뷰(View)를 제공합니다:

Graph (그래프)-- 힘 지향(Force-directed) 의존성 맵. 노드를 클릭하여 내보내기(exports), 타입(types), 파일(files)을 확인합니다.
Tree (트리)-- 파일 및 라인 수(line counts)를 포함한 접기 가능한 디렉토리 계층 구조.
Table (테이블)-- 검색 필터가 포함된 정렬 가능한 모듈 테이블.
Flow (플로우)-- 엔트리포인트(entrypoints)에서 리프(leaves) 노드까지의 하향식 의존성 흐름.

언어 (Language)	추출 항목 (Extracts)
Go	임포트(imports), 시그니처가 포함된 내보내기(exports with signatures), 구조체 필드(struct fields), 인터페이스 메서드(interface methods)
...
그 외 다른 언어는 기본적인 지원(라인 수 + 언어 감지)을 제공합니다.

stacklit init # 스캔, 생성, HTML 열기
stacklit init --hook # git post-commit hook도 설치
stacklit init --multi repos.txt # 멀티 레포(polyrepo): 여러 레포지토리 스캔
...

설정 (.stacklitrc.json)

{
"ignore": ["vendor/", "generated/"],
"max_depth": 3,
...

도구 (Tool)	접근 방식 (Approach)	토큰 (Tokens)	커밋 가능 여부 (Committable)	시각적 맵 (Visual map)
Stacklit	구조화된 인덱스 (Structured index)	~250	예 (Yes)	예 (Yes)
Repomix	전체 덤프 (Full dump)	50k-500k	아니오 (No)	아니오 (No)
code2prompt	전체 덤프 (Full dump)	50k-500k	아니오 (No)	아니오 (No)
Aider repo-map	Tree-sitter + PageRank	~1k	아니오 (No)	아니오 (No)

다음 항목을 자동 감지합니다: pnpm, npm, yarn workspaces, Go workspaces, Turborepo, Nx, Lerna, Cargo workspaces, 그리고 관례적인 디렉토리(apps/, packages/, services/).

Repomix는 모든 파일을 하나의 프롬프트로 결합합니다 (50k-500k 토큰). Stacklit은 코드 구조를 파싱하여 약 250토큰 규모의 내비게이션 맵을 생성합니다. 작은 규모의 레포지토리와 원샷 채팅(one-shot chats)에는 Repomix를 사용하세요. 더 큰 코드베이스에서 매일 AI 보조 개발을 수행할 때는 Stacklit을 사용하세요. 전체 비교를 확인하세요.

Stacklit이 제 코드를 읽나요?
네, 로컬에서 읽습니다. tree-sitter를 사용하여 소스 파일을 파싱하고 구조(임포트, 내보내기, 타입)를 추출합니다. 선택 사항인 --summary 플래그(Claude API를 호출함)를 사용하지 않는 한, 코드는 어디로도 전송되지 않습니다.

지원되지 않는 언어를 사용하면 어떻게 되나요?
Stacklit은 tree-sitter 목록에 없는 언어에 대해 기본 지원(줄 수 계산 + 언어 감지) 방식으로 전환됩니다. 모듈 맵 (module map), 의존성 그래프 (dependency graph), 그리고 git 활동 (git activity) 기능은 여전히 작동합니다.

git hook이 커밋 속도를 느리게 하나요?
아니요. Stacklit은 문서나 설정 파일만 변경된 경우 재생성 과정을 건너뛰기 위해 Merkle hashing을 사용합니다. 10,000줄 규모의 저장소(repo)에서 재생성에는 약 50ms가 소요됩니다.

GitHub Copilot과 함께 Stacklit을 사용할 수 있나요?
네. stacklit derive --inject claude를 실행한 후

출력된 파일의 이름을 .github/copilot-instructions.md로 변경하거나,

단순히 stacklit.json을 커밋하고 Copilot 지침(instructions)에서 이를 참조하면 됩니다.

USAGE.md -- 전체 사용 가이드, 명령어 참조, MCP 도구, 설정
COMPARISON.md -- Repomix, code2prompt, Codebase-Memory와의 직접 비교
SKILL.md -- AI 에이전트가 stacklit.json을 사용하는 방법에 대한 지침
examples/ -- Express.js, FastAPI, Gin, Axum의 실제 stacklit.json 출력 예시
Discussions -- 가이드, Q&A, 기능 요청

make build # 바이너리 빌드
make test # 모든 테스트 실행

기여(Contributions)를 환영합니다. 열려 있는 이슈(open issues)를 확인하거나 토론(discussion)을 시작해 주세요.

MIT

glincker/stacklit

요약

핵심 포인트

대신 수동으로 구성하기

자동 업데이트를 위한 GitHub Action

설정 (.stacklitrc.json)

댓글