jahala/tilth

Smart code reading for humans and AI agents. Definitions, callers, dependencies and function-level diffs from tree-sitter. One binary, no index. MCP server + CLI. Install: cargo install tilth or npx tilth

tilth – 인간과 AI 에이전트를 위한 스마트 코드 읽기

개요 – tilth는 소스 코드를 tree‑sitter로 파싱하고 인덱스를 구축하지 않고 코드베이스의 구조를 쿼리할 수 있는 단일 바이너리 명령줄 도구(및 MCP 서버)입니다. 심볼이 정의된 위치, 호출자, 파일이 의존하는 항목, 심지어 커밋 간의 함수 수준 diff도 표시할 수 있습니다.

AI 에이전트에게 중요한 이유 – 대규모 언어 모델은 함수를 찾기 위해 값싼 도구(glob→grep→read)의 체인에 의존하는 경우가 많으며, 호출자나 종속성을 발견하려면 많은 파일을 읽어야 합니다. tilth는 한 단계로 무거운 작업을 수행합니다. 구문 트리를 이해하므로 에이전트는 정확한 정의, 호출 그래프, 파일 수준 개요를 즉시 얻을 수 있어 도구 호출 수와 일반 텍스트 검색으로 인한 오탐 가능성을 줄입니다.

핵심 기능

기능	제공 내용
파일 개요 / 섹션 보기	작은 파일은 전체가 출력되고, 큰 파일은 줄 범위 블록이 포함된 구조적 개요를 반환합니다. `--section`을 사용하여 특정 범위나 마크다운 제목을 가져옵니다.
심볼 검색	`tilth <심볼> --scope <디렉토리>`는 먼저 정의를 찾은 다음 주변 코드 스니펫과 함께 사용처를 표시합니다. `--expand`는 상위 일치 항목의 소스를 추가하고, `--full`은 일치 한도를 높입니다.
호출자 및 피호출자	`--callers`는 모든 호출 사이트를 나열합니다(텍스트 일치가 아닌 구조적으로). 확장된 정의에는 호출하는 함수를 포함하는 `-- calls --` 푸터가 포함됩니다.
파일 수준 종속성	`tilth <파일> --deps`는 파일이 가져오는 것/사용하는 것과 그것을 가져오는 다른 파일을 보고합니다 – 리팩터링 전에 유용합니다.
`grok`	심볼의 시그니처, 문서 주석, 본문, 피호출자, 호출자, 형제 및 관련 테스트를 반환하는 원샷 명령입니다.
구조적 diff	`tilth diff <커밋>`은 추가/제거/변경된 함수를 줄 번호와 함께 표시합니다(원시 diff뿐만 아니라).
MCP 서버 모드	동일한 기능을 MCP 프로토콜로 노출하여 AI 에이전트(Claude‑code, Cursor, Gemini 등)가 도구 체인에서 직접 `tilth_search`, `tilth_deps`, `tilth_grok` 등을 호출할 수 있습니다.
편집 모드	`--edit`를 사용하면 서버는 해시 앵커 줄 참조를 사용하여 파일을 안전하게 편집하는 `tilth_write`/`tilth_read`도 제공합니다.

일반적인 사용 사례

AI 어시스턴트 도구 – tilth를 Claude‑code, Cursor 또는 MCP 호환 에이전트에 플러그인하여 모델이 사용자 지정 스크립트 없이 "ServeHTTP를 호출하는 사람은?" 또는 "recovery.go에서 무엇이 변경되었나?"라고 물을 수 있게 합니다.
개발자 탐색 – 터미널에서 함수 정의를 빠르게 찾고, 호출 그래프를 확인하고, 파일의 외부 종속성을 이해합니다.
코드 리뷰 및 리팩터링 – 커밋 간의 함수 수준 diff를 생성하거나 이름 변경이 호출자를 깨뜨리지 않는지 확인합니다.
대규모 코드베이스 – 구문 트리를 병렬로 탐색하므로 수천 개의 파일(FastAPI, Gin)이 있는 프로젝트에서 수십 밀리초 만에 작동합니다.

설치 및 시작

# Rust의 패키지 관리자 사용
cargo install tilth
# 또는 npm으로 일회성 바이너리(컴파일된 바이너리 번들)
npx tilth

사전 빌드된 바이너리는 GitHub 릴리스 페이지에서도 사용할 수 있습니다.

MCP 서버로 실행하려면(대부분의 에이전트가 사용하는 모드):

tilth --mcp            # 서버 시작
# 에이전트용 클라이언트 구성 설치, 예:
tilth install claude-code   # ~/.claude.json 작성

서버는 --edit로 시작하여 안전한 파일 편집 기능을 활성화할 수 있습니다.

아키텍처 개요

언어 파싱 – tree‑sitter(17개 지원 언어)를 사용하여 각 파일에 대한 인메모리 구문 트리를 구축합니다. 타입 해석은 없고 구조 분석만 수행합니다.
검색 엔진 – tree‑sitter 쿼리(정의, 호출자, 피호출자)를 ripgrep 크레이트와 결합하여 일반 텍스트/정규식/glob 검색을 수행합니다.
병렬 처리 – 디렉토리 탐색(ignore 크레이트) 및 심볼 조회는 rayon으로 병렬화되어 중간 규모 저장소에서 100ms 미만의 응답 시간을 제공합니다.
캐싱 – 개요 캐시(DashMap 경유)는 파일의 수정 시간이 변경되면 무효화되어 반복 쿼리를 빠르게 유지합니다.
런타임 종속성 없음 – 바이너리는 순수 Rust(약 35,000줄)이며 네트워크 호출을 하지 않으므로 모든 코드가 로컬에 유지됩니다.

제한 사항

타입 추론 없음 – tilth는 순전히 구문에 기반하여 작동합니다. 제네릭 타입이나 오버로드를 해결할 수 없습니다.
호출자의 이름만 일치 – 다른 모듈에서 같은 이름의 함수가 두 개 있으면 호출자가 모호할 수 있습니다.
언어 범위 – tree‑sitter 문법이 있는 언어만 완전히 지원되며, 그 외의 언어는 일반 텍스트 검색으로 대체됩니다.
동적 디스패치 – 리플렉션이나 런타임 코드 생성을 통해 호출되는 함수는 감지되지 않습니다.

라이선스 및 커뮤니티

라이선스: MIT – 허용적이며 상업 및 오픈소스 프로젝트에 적합합니다.
지원: 저자는 Buy‑Me‑A‑Coffee를 통해 기부를 받습니다. 문제 및 기능 요청은 GitHub에서 처리됩니다.

TL;DR

tilth는 AI 에이전트(및 개발자)에게 빠르고 인덱스가 필요 없으며 구문을 인식하는 코드베이스 보기를 제공합니다. 정의 검색, 호출 그래프 추적, 파일 종속성 검사, 함수 수준 diff 보기를 작은 Rust 바이너리 또는 MCP 서버에서 모두 수행할 수 있습니다. 원시 grep 스타일 도구와 헤비급 언어 서버 사이의 간극을 메워 코드 이해 도구를 더 효율적이고 안정적으로 만듭니다.