<picture> <source media="(prefers-color-scheme: dark)" srcset="site/readme-banner-dark.png"> <source media="(prefers-color-scheme: light)" srcset="site/readme-banner-light.png"> <img src="site/readme-banner-dark.png" alt="Scalex — Scala code intelligence for coding agents" width="839" height="440"> </picture> Grep knows text. Scalex knows Scala. Think grep, but it understands Scala's AST — so it finds symbols, not just strings.

Why Scalex?
The Problem
Design Principles
How It Works
Quick Start
Usage Examples
Commands
What Makes It Coding-Agent-Friendly
Scalex vs Grep — Honest Comparison
Scalex vs Metals
Credits
Name
Mascot
License

Why Scalex?

No build server. Nothing to leak. No daemon, no background process, no socket. No build server silently eating RAM, leaking threads, or grinding your CPU. The index is a single file in your repo — when scalex exits, nothing is left running. See how it works.
Zero setup. Just works. Install the skill, point it at any git repo, start navigating. No build files, no config, no "import build" dialog, no "connecting to build server". Clone a repo you've never seen and explore it in seconds. See quick start.
Smarter than grep. Categorized references with confidence ranking. Wildcard import resolution (finds 1,205 importers where grep finds 17). Transitive inheritance trees. Structural AST search. Things grep fundamentally cannot do. See the honest comparison for real examples.
Composite commands. explain returns definition + scaladoc + members + implementations + import count in one shot. refs --count triages impact in one line. Designed to minimize tool calls — the biggest cost for coding agents isn't latency, it's the number of round trips. See what makes it coding-agent-friendly for the full picture.

After installing, clone a project and ask Claude to explore it:

| Project | Clone | Prompt | |---|---|---| | Scala 3 compiler | git clone --depth 1 https://github.com/scala/scala3.git | "Use scalex to explore how the Scala 3 compiler turns source file into bytecode." | | Scala.js | git clone --depth 1 https://github.com/scala-js/scala-js.git | "Use scalex to explore how Scala.js turns Scala code into JavaScript." |

Scalex indexes the codebase in seconds, then navigates definitions, traces implementations, and explores the architecture — all without a build server or compilation.

https://github.com/user-attachments/assets/09391648-1e3a-409c-ad52-19afa99ea81f

The Problem

Coding agents (Claude Code, Cursor, Codex) are powerful, but they're blind in large Scala codebases. When an agent needs to find where PaymentService is defined, it has two options:

Grep — fast, but dumb. Returns raw text. Can't filter by symbol kind, doesn't know a trait from a usage. The agent has to construct regex patterns and parse raw output.
Metals LSP — smart, but heavy. Requires a build server, full compilation, minutes of startup. Designed for humans in IDEs, not agents making quick tool calls.

Design Principles

Scalex takes only the source-level indexing layer of a language server — definitions, references, implementations, hierarchy — and parses it directly from source with Scalameta. No build, no classpath, no daemon. The tradeoff: when two packages both define a class called Config, scalex can't tell which one extends Config refers to — that requires type resolution. The upside: clone any repo, index 17k files in seconds, and start navigating immediately.

One command = one answer. No multi-step reasoning, no regex construction.
Structured output. Symbol kind, package, file path, line number. Not raw text.
Scala 2 and 3. Enums, givens, extensions, implicit classes, procedure syntax — auto-detected per file.
Java files. .java files are also indexed with lightweight regex extraction (class/interface/enum/record).
Honest about limits. When it can't find something, it tells the agent what to try next.

How It Works

Here's the architecture (generated with scalex graph --render):

                   ┌──────────┐
                   │scalex CLI│
                   └─────┬────┘
                         │
                         v
                 ┌──────────────┐
                 │WorkspaceIndex│
                 └───┬────┬──┬──┘
                     │    │  │
        ┌────────────┘    │  └──────────────┐
        │                 │                 │
        v                 v                 v
 ┌─────────────┐ ┌─────────────────┐ ┌────────────┐
 │Scalameta AST│ │.scalex/index.bin│ │git ls-files│
 └─────────────┘ └─────────────────┘ └────────────┘

scalex CLI — 30 commands: search, def, impl, refs, imports, members, graph, ...
WorkspaceIndex — lazy indexes: symbolsByName, parentIndex, filesByPath, bloom filters
git ls-files — --stage returns path + OID per tracked file (change detection)
Scalameta AST — Source → AST → SymbolInfo, BloomFilter, imports, parents
.scalex/index.bin — binary cache with string interning (skip unchanged files)

Pipeline

  1. git ls-files --stage
     │  Every tracked .scala file with its content hash (OID).
     │  ~40ms for 18k files.
     │
  2. Compare OIDs against cached index
     │  Unchanged files are skipped entirely.
     │  0 changes = 0 parses.
     │
  3. Scalameta parse (parallel)
     │  Source → AST → symbols, bloom filters, imports, parents.
     │  All CPU cores via Java parallel streams.
     │
  4. Save to .scalex/index.bin
     │  Binary format with string interning.
     │  Loads in ~225ms for 144k+ symbols.
     │
  5. Answer the query
     │  Maps build lazily — each query only pays for the indexes it needs.

Performance

| Project | Files | Symbols | Cold Index | Warm Index | |---|---|---|---|---| | Production monorepo | 14,219 | 170,094 | 5.3s | 445ms | | Scala 3 compiler | 18,485 | 144,211 | 2.7s | 349ms |

Quick Start

Claude Code (recommended)

Installs the binary + skill (teaches Claude when and how to use scalex) in one step:

/plugin marketplace add nguyenyou/scalex
/plugin install scalex@scalex-marketplace

Then try:

"use scalex to explore how authentication works in this codebase"

Other coding agents

Copy the skill folder to wherever your agent reads skills — that's it. The included bootstrap script auto-downloads and caches the native binary on first run.

# Clone and copy the skill folder
git clone --depth 1 https://github.com/nguyenyou/scalex.git /tmp/scalex
cp -r /tmp/scalex/plugins/scalex/skills/scalex /path/to/your/agent/skills/

The skill folder contains everything: SKILL.md (teaches the agent when and how to use scalex), reference docs, and a bootstrap script that downloads the correct binary for your platform.

How the bootstrap script works

You don't install scalex manually — the skill includes a bootstrap script (scripts/scalex-cli) that handles everything:

Detects your platform (macOS arm64, macOS x64, Linux x64)
Downloads the correct native binary from GitHub Releases on first run
Verifies the SHA-256 checksum against pinned hashes in the script
Caches the binary at ~/.cache/scalex/ (follows XDG spec)
Auto-upgrades when the skill version changes — old cached binaries are left in place, new version is downloaded alongside

The coding agent invokes scalex through this script on every call. After the first run (~2s download), subsequent calls go straight to the cached binary with zero overhead.

Advanced: customize or override

If you prefer to build from source or use your own binary, you have two options:

Option A: Put your binary on PATH and edit the skill. Build scalex, place it anywhere on your PATH, then update SKILL.md to invoke scalex directly instead of bash "/path/to/scripts/scalex-cli".

Option B: Edit the bootstrap script to use a local binary. Set the BINARY variable in scripts/scalex-cli to point to your local build — the script will skip the download and exec your binary directly.

Build from source

Requires scala-cli + GraalVM:

git clone https://github.com/nguyenyou/scalex.git
cd scalex
./build-native.sh
# Output: ~30MB standalone binary, no JVM needed

Run from source (no native image)

If you have scala-cli installed, you can run directly from source without building a native image:

git clone https://github.com/nguyenyou/scalex.git
scala-cli run scalex/src/ -- search /path/to/project MyClass

Downloads dependencies on first run (~5s), then starts in ~1s. Useful for development or quick testing.

Usage Examples

cd /path/to/your/scala/project

# Discover
scalex search Service --kind trait         # Find traits by name
scalex search hms                          # Fuzzy camelCase: finds HttpMessageService
scalex search find --returns Boolean       # Filter by return type
scalex file PaymentService                 # Find files by name (like IntelliJ)
scalex packages                            # List all packages
scalex package com.example                 # Explore a specific package
scalex api com.example

Scalex

Install / Use

README

Table of Contents