classpath-surfer

[!WARNING] This project is in alpha stage. APIs, CLI flags, index format, and configuration schema are subject to breaking changes without notice. Use at your own risk and expect rough edges. Bug reports and feedback are very welcome!

---

Why

Coding agents (like Claude Code) working on Gradle Java/Kotlin projects repeatedly struggle with external library symbols — blindly crawling ~/.gradle/caches/, accessing artifacts outside the actual classpath, decompiling classes when source JARs exist, and rediscovering this fragile workflow from scratch every time.

classpath-surfer solves this by building a local Tantivy full-text index over all symbols in your resolved classpath. Agents (and humans) can search symbols and read source code instantly.

Features

	Feature	Description
:mag:	Symbol search	Smart search with auto FQN detection, CamelCase token splitting, and prefix matching — filter by kind, dependency, access level, or classpath
:zap:	Fast indexing	Auto-extract Gradle project classpath and index all symbols in seconds with parallel JAR parsing via rayon; incremental updates via GAV-level diff
:globe_with_meridians:	Kotlin signatures	Decode @kotlin.Metadata protobuf to display native Kotlin signatures like suspend fun and data class
:package:	JVM-language agnostic	Java, Kotlin, Scala, Groovy, Clojure — search symbols from dependencies written in any JVM language
:page_facing_up:	Source code lookup	Auto-focus on a symbol with surrounding context; source JARs when available, otherwise on-demand CFR/Vineflower decompilation — Kotlin shows original .kt source with a secondary decompiled Java view
:robot:	AI agent integration	--agentic JSON output with classified exit codes for any AI agent; optional Claude Code plugin for slash-command skills

Quick Start

Install

[!NOTE] Pre-built binaries are currently available for Apple Silicon (aarch64) only. For other platforms or building from source, see CONTRIBUTING.md.

brew install rscarrera27/tap/classpath-surfer

The binary is also installed as cpsurf — a short alias you can use anywhere in place of classpath-surfer:

cpsurf search symbol ImmutableList   # same as: classpath-surfer search symbol ImmutableList

Set up a project

cd your-gradle-project
classpath-surfer index init      # writes config, Gradle init script, then runs initial refresh

# Verify the index was built
classpath-surfer index status
# → 38 dependencies, 77,219 symbols indexed, 2.1 MB on disk

Find a symbol

# Search by name
classpath-surfer search symbol ImmutableList

# CamelCase token matching — finds ImmutableList, ImmutableMap, ImmutableSet, etc.
classpath-surfer search symbol Immutable

# Find coroutine launchers in kotlinx-coroutines
classpath-surfer search symbol launch --type method --dependency "org.jetbrains.kotlinx:*"

# List all symbols in a specific dependency
classpath-surfer search symbol --dependency "com.google.guava:guava"

# Glob search for HTTP client classes
classpath-surfer search symbol "Http*Client" --type class

# Filter by classpath (compile, runtime, testCompile, testRuntime, ...)
classpath-surfer search symbol Annotation --type class --classpath compile

# FQN-like queries are auto-detected
classpath-surfer search symbol com.google.common.collect.ImmutableList

Read the source

# Show source — auto-focuses on the symbol with 25 lines of context
classpath-surfer show com.google.common.collect.ImmutableList
classpath-surfer show com.google.common.collect.ImmutableList.of

# Widen context / show the full file
classpath-surfer show com.google.common.collect.ImmutableList --context 50
classpath-surfer show com.google.common.collect.ImmutableList --full

# Kotlin sources display original .kt files (suspend fun, data class, etc.)
classpath-surfer show kotlinx.coroutines.CoroutineScope

If a -sources.jar is available it will be used; otherwise the class is decompiled with CFR (default) or Vineflower.