I've spent a fair amount of time in my career fighting with IDEs that felt like they were actively working against me. In the Scala world, because the language is so expressive and the compiler is so powerful, the "intelligence" of your editor is everything. That's where Metals comes in. It's not an IDE itself, but a Language Server. It basically tells your editor (VS Code, Vim, Emacs) exactly what the Scala compiler is thinking in real-time.

Where is this method actually defined?

Let's look at a scenario I run into all the time. I've got a project with a trait called UserRepository and a couple of implementations—one for a real database and one for testing. I'm looking at a service class that uses the repository, and I see a call to repo.findByEmail(email).

case class User(id: Long, email: String, name: String)

trait UserRepository {
  def findByEmail(email: String): Option[User]
  def save(user: User): Unit
}

class InMemoryUserRepository extends UserRepository {
  private var users = Map.empty[String, User]
  def findByEmail(email: String): Option[User] = users.get(email)
  def save(user: User): Unit = {
    val u = user
    users = users + (u.email -> u)
  }
}

class UserService(repo: UserRepository) {
  def getUser(email: String): Option[User] = {
    repo.findByEmail(email) // I'm here. But where is the logic?
  }
}

If I'm just using a plain text editor, I have to search the whole project for "findByEmail". But with Metals running, I can just Cmd+Click (or F12) on that method call. Now, here's the catch: because repo is typed as the trait UserRepository, Metals initially takes me to the trait definition. That's technically correct, but it's not what I want. I want the implementation.

I'll look at the "Code Lens" (those tiny grey pieces of text above the method name). Metals shows me 1 implementation. I click that, and boom—I'm jumped straight into InMemoryUserRepository. This saves me from hunting through files manually, which is a lifesaver when you're dealing with a codebase of 500+ files.

Waiting for the build server to catch up

I've noticed that when I first open a project or pull a fresh branch from Git, the "intelligence" disappears. My code is suddenly covered in red squiggles, even though I know it's correct. I see a notification in the corner: Build server: Import build?

I'll hit "Import". This is Metals communicating with SBT (or Mill). It's basically saying, "Hey, I see you have a build.sbt file. I need to compile this in the background so I can build a semantic map of your types." I usually take this as my cue to go grab a coffee. If you try to ignore this, you're essentially flying blind; autocomplete won't work, and "Go to Definition" will fail because Metals doesn't yet know which libraries are on your classpath.

Fixing the red squiggles

Let's intentionally break something to see how Metals handles compiler errors. I'll change the UserService to pass an integer where a string is expected:

def getUser(email: String): Option[User] = {
  repo.findByEmail(12345) // This should be a String
}

Almost instantly, a red squiggle appears under 12345. I hover over it, and instead of me having to run sbt compile and scroll through a messy terminal output, Metals shows me the exact error: type mismatch; found: Int, required: String.

What's really useful here is that Metals doesn't just report the error; it often suggests a "Quick Fix." If I hit Cmd+. (or Ctrl+.), it might suggest importing a conversion or changing the type. It’s effectively bringing the compiler's brain directly into the text editor.

The magic of global renaming

Finally, let's say I realize findByEmail is too wordy and I want to call it findUser. If I just find-and-replace "findByEmail" with "findUser" across the project, I run the risk of accidentally renaming a variable or a comment that happens to have the same name, or worse, missing a spot in a different file.

I'll put my cursor on the method name in the trait, hit F2, and type findUser. I hit enter, and Metals doesn't just change the text in this file—it updates the trait, the InMemoryUserRepository, and every single call site in UserService across the entire project. It's doing a semantic rename, meaning it understands the AST (Abstract Syntax Tree) of your code and only changes the actual references to that specific method.

📋 Practical Task

Refactoring the Order Processing Domain with Metals

You have been provided with a small project containing three files: Order.scala (a case class), OrderRepository.scala (a trait and implementation), and OrderManager.scala (a service class). The project is currently riddled with "type mismatch" errors and inconsistent naming.

Perform the following steps using Metals features:

• Build Import: Trigger the build import via the Metals notification to resolve all classpath issues.
• Semantic Renaming: Use the F2 (Rename) feature to change the method fetchOrderById to getOrder across the entire project.
• Error Resolution: Locate the red squiggle in OrderManager.scala where a Long is being passed into a method expecting a String. Fix the type mismatch so the project compiles.
• Navigation: Use the "Go to Implementation" Code Lens to jump from the OrderRepository trait to the SqlOrderRepository class.

Verify that the project compiles without errors by running the build command in your terminal.