ksrc
AI 에이전트를 위한 Gradle 서드파티 의존성 소스를 원라인으로 검색하고 읽기.
귀하의 AI 에이전트가 단일 서드파티 라이브러리 함수 시그니처를 확인하는 데만 약 10단계의 과정을 거칩니다. ksrc는 이 과정을 두 개의 명령어와 약 4배 적은 토큰으로 줄여줍니다.
ksrc란 무엇인가요 (What it is)
이것은 Gradle 프로젝트에서 작업하는 AI 에이전트를 위해 효율적인 의존성 소스 검색을 가능하게 하는 CLI 유틸리티입니다.
혹시 AI 에이전트가 TypeScript/Python에서 함수 시그니처를 찾는 것을 본 적이 있나요? node_modules에 대한 간단한 rg와 sed 호출만으로 API 및 시그니처를 발견하는 데 충분합니다.
하지만 Gradle 생태계에서는 에이전트가 소스 jar 파일을 다운로드하고, 위치를 찾고, 압축을 풀고, ripgrep 검색을 수행하기 위해 15단계의 여정을 거쳐야 합니다.
ksrc는 이 과정에서 낭비되는 16k 토큰을 단 2개의 CLI 명령어로 줄여줍니다.
먼저 명령어 자체를 설치하는 것부터 시작합니다.
Homebrew (macOS/Linux) - 권장, 자동 업데이트:
brew tap respawn-llc/tap
brew install ksrc
GitHub Releases를 통한 독립 실행 바이너리:
ksrc를 수동으로 설치하면 ksrc 스킬이나 플러그인과 달리 자동 업데이트되지 않습니다. 따라서 바이너리를 최신 상태로 유지해 주십시오.
설치 스크립트 (macOS/Linux):
curl -fsSL https://raw.githubusercontent.com/respawn-llc/ksrc/main/scripts/install.sh | sh
2. 에이전트에게 사용법 가르치기 (Teach agents how to use it)
다음으로, 에이전트가 ksrc를 사용할 수 있다는 것과 그 방법을 알게 해 주기 위해 claude 코드 플러그인/스킬을 설치합니다.
Claude Code
Respawn 마켓플레이스를 추가한 후 플러그인을 설치하세요:
/plugin marketplace add respawn-llc/claude-plugin-marketplace
/plugin install ksrc@respawn-tools
Codex plugin
스킬 전용 플러그인을 설치합니다:
codex plugin marketplace add respawn-llc/ksrc
codex plugin add ksrc@ksrc
MCP (Model Context Protocol)
에이전트가 bash 도구를 가지고 있지 않을 때 사용합니다. MCP 클라이언트를 구성하여 stdio 서버를 실행하도록 설정하세요:
{
"mcpServers": {
"ksrc": {
...
기본 도구: search, cat, deps. --tools=<list>를 통해 더 많은 도구를 활성화할 수 있습니다 (예: --tools=search,cat,deps,resolve 또는 --tools=all).
MCP를 사용한다면 해당 스킬이 필요하지 않을 것이지만, 에이전트가 bash 도구에 접근할 수 있다면 mcp 대신 CLI+bash를 선호하세요.
AGENTS.md 프롬프트
.gradle에 직접 접근하는 것을 피하고, 대신 ksrc cli를 사용하여 의존성의 소스 코드를 선제적으로 검사하여 API 모양(shapes)이나 구현을 학습하세요. ksrc --help로 시작하세요.
사용법
이 도구에는 더 긴 타임아웃을 설정해 주세요. 소스를 다운로드(필요한 경우)하고 Gradle 프로젝트를 해결하는 데 최대 1분이 걸릴 수 있습니다.
- 필요한 파일 식별자 및 라인을 얻기 위해
ksrc search를 사용해 시작하세요. 예시:
$ ksrc search "updateState<"
pro.respawn.flowmvi:core:3.3.0-alpha03!/commonMain/pro/respawn/flowmvi/api/StateReceiver.kt 19:8: updateState<State.Subtype, _> { }
이 도구는 발견된 항목(hit)마다 다음과 같은 형식으로 연결 가능한 레코드 하나를 반환합니다: <file-id> <line>:<col>:<line-text>. 텍스트 세그먼트는 끝에 붙은 개행 문자(trailing newline)가 제거된 원본 소스 라인이므로, 리터럴 : 문자를 포함할 수 있습니다.
만약 --show-extracted-path를 활성화하면, 각 발견 항목은 대신 디버그 지향의 탭 구분된 형태를 사용합니다:
<file-id> <따옴표로 감싼 추출 경로> <line> <col> <따옴표로 감싼 라인 텍스트>
ksrc는 방출된 파일 ID에 대한 백킹 JAR 경로를 유지하므로, 동일한 장치에서 후속 cat/open 호출은 일반적으로 반복적인 --project 또는 스코프/설정 플래그가 필요하지 않습니다.
더 빠른 실행과 노이즈 감소를 원한다면 다음을 지정하세요:
--artifact: 검색 범위를 하나의 아티팩트로 제한합니다. (또는 버전을 통해 제한하려면 --module 사용)
--subproject: 모노레포(monorepos)/대형 모듈식 앱의 발견을 돕습니다.
--targets: 특정 KMP 타겟으로 제한합니다.
--gradle-user-home: GRADLE_USER_HOME을 재정의해야 하는 경우 사용합니다. 그렇지 않으면 ksrc는 GRADLE_USER_HOME을 존중하며 기본값은 ~/.gradle입니다.
KMP 모듈의 경우, 기본적으로 --module group:artifact는 공통/기본 소스에 더해 Gradle이 선택한 플랫폼 변형(platform variant) 소스 JAR를 검색합니다. 변형을 좁히려면 --targets 또는 --config를 사용하세요.
플랫폼 좌표를 사용하여 Android SDK 소스를 검색하세요:
Use --android-home <경로>를 사용하여 SDK를 선택합니다. 플랫폼 버전, SDK 검색 및 설치에 대해서는 Android SDK 소스를 참조하십시오.
- 원하는 아티팩트를 찾았다면, 파일 내용을 읽으십시오:
$ ksrc cat 'pro.respawn.flowmvi:core:3.3.0-alpha03!/commonMain/pro/respawn/flowmvi/api/StateReceiver.kt' --lines 10,25
- 소스 jar 내부의 경로를 이미 알고 있다면,
where를 사용하여 재사용 가능한 파일 ID 및 백업 jar 경로를 복구하십시오:
$ ksrc where kotlinx/datetime/LocalDate.kt --group org.jetbrains.kotlinx --artifact kotlinx-datetime
org.jetbrains.kotlinx:kotlinx-datetime:0.8.0!/kotlinx/datetime/LocalDate.kt|/path/to/kotlinx-datetime-0.8.0-sources.jar
경로 조회를 위해, | 앞의 텍스트는 search와 동일한 <file-id> 계약을 사용하므로, 이를 ksrc cat 또는 ksrc open에 직접 전달할 수 있습니다.
유지보수 (Maintenance)
이 저장소에서 의존성 버전 소스를 업데이트하려면:
./scripts/update-dependencies.sh
이 스크립트는 Go 모듈/툴체인, Gradle 래퍼, 샘플 Gradle 버전 카탈로그, Gradle 피처 의존성 고정값(pins), 그리고 고정된 GitHub Actions를 업데이트합니다. format/vet/test/build와 샘플 스모크 검사를 실행하려면 --verify를 추가하십시오. GitHub API 속도 제한이 우려되는 경우 GITHUB_TOKEN을 설정하십시오.
라이선스 (License)
이 프로그램은 Apache License, Version 2.0에 따라 라이선스가 부여되었습니다.
LICENSE.txt를 참조하십시오.
Copyright 2026 Respawn LLC
Apache License, Version 2.0(
해당 법률에 의해 요구되거나 서면으로 합의되지 않는 한, 본 라이선스 하에서 배포되는 소프트웨어는 '있는 그대로(AS IS)' 기준으로, 명시적이든 묵시적이든 어떠한 종류의 보증이나 조건 없이 배포됩니다. 라이선스 하에서의 권한 및 제한을 규율하는 구체적인 내용은 라이선스를 참조하십시오.