scalametascalameta/metals/AGENTS.md

metals

AGENTS.md2.3k starsChanged 2 months agoApache-2.0View on GitHub

This document provides instructions for AI agents working on the Metals codebase. If Metals MCP tools are available, use them to run tests. Otherwise, use the following command: Note: By convention, test names should be kebab-case with no spaces (e.g., private-member instead of private member). Make sure to use the user's default shell to run the command. For more information on filtering tests in MUnit, see the MUnit filtering documentation. Before committing: - ALWAYS format all changed Scala files using…

Apr 17, 2019Refactoring support — scalameta/metals-feature-requests65 reactions · 4 comments
Apr 11, 2022[Progress] Expose diagnostic code and related information — scala/scala338 reactions · 1 comment
Jun 16, 2021Please support .class decompiling — scalameta/metals-feature-requests15 reactions · 1 comment
Jul 20, 2022Allow to modify the bloop.json configuration file path — scalameta/metals-feature-requests11 reactions · 6 comments
Jun 8, 2026Scala 3.9.0-RC1 release procedure — scala/scala310 reactions

28 more on GitHub

Dec 5, 2021Allow editors to start an sbt session — scalameta/metals-feature-requests10 reactions · 5 comments
Nov 17, 2020sbt wrongly prints "sbt server is already booting" — sbt/sbt10 reactions · 62 comments
Aug 26, 2026Scala 3.9.0 release procedure — scala/scala38 reactions
Jul 16, 2021Allow to run single test / pass arguments to test framework — scalameta/metals-feature-requests8 reactions · 3 comments
Jun 1, 2026Release procedure for Scala 3.8.4 — scala/scala36 reactions
Feb 14, 2019Automatically register new workspace folders for source dependencies — scalameta/metals-feature-requests6 reactions · 3 comments
Jan 16, 2018Make it possible for sbt plugins to register server handlers for custom JSON-RPC methods — sbt/sbt6 reactions · 3 comments
Jun 23, 2023[VSCode] Support build files in non-workspace-root directories — scalameta/metals-feature-requests5 reactions · 1 comment
Sep 8, 2022Format type signatures in hover tooltip — scalameta/metals-feature-requests5 reactions · 2 comments
Jun 28, 2022Support dependencies & repositories in .scalafix.conf — scalacenter/scalafix5 reactions · 3 comments
Mar 25, 2021Make sure that evalaution runs with a proper classloader — scalameta/mdoc4 reactions · 2 comments
Mar 24, 2020Add BSP support — com-lihaoyi/Ammonite4 reactions · 10 comments
Apr 15, 2019Update for Metals v0.5 — laughedelic/atom-ide-scala4 reactions · 1 comment
Jan 19, 2018SemanticDB Specification, Version 3.0.0 — scalameta/scalameta4 reactions · 3 comments
Jan 8, 2026Fix opaque types displayed as `Nothing & Any` in hover and signature help — scala/scala33 reactions
Sep 9, 2025Porting XRayModeHints — scala/scala33 reactions
Oct 13, 2024Implement back publishing support — sbt/sbt-ci-release3 reactions · 15 comments
Mar 19, 2024bugfix: Fix showing Scala 3 diagnostics — JetBrains/bazel-bsp3 reactions · 2 comments
May 12, 2023Support Scala 3's Best Effort compilation — scalacenter/bloop3 reactions · 5 comments
Aug 16, 2022fix: [SemanticDB] Emit SymbolInformation and Occurrence for anonymous class — scala/scala33 reactions · 1 comment
Feb 9, 2022Fix https://github.com/scalameta/metals/issues/3477 — scalacenter/scala-debug-adapter3 reactions
May 13, 2020Add a feature to create a new Project — scalameta/metals-vscode3 reactions · 3 comments
Aug 14, 2026bugfix: Ignore unclosed string interpolation to allow completions — scala/scala2 reactions · 1 comment
Feb 17, 2026fix & feat: improvements in selection ranges — scala/scala32 reactions · 1 comment
Jun 26, 2025fix: simplify infer type for apply — scala/scala32 reactions · 1 comment
May 29, 2025Add inlay hints for by-name parameters — scala/scala32 reactions
May 23, 2025add selection ranges for more names — scala/scala32 reactions
Jan 10, 2024chore: Backport changes from Metals — scala/scala32 reactions

On Hacker News · 1

Mar 8, 2018Metals – Language Server for Scala2 points · 1 comment

On Bluesky · 1

Nov 13, 2024I’ve learned this lesson multiple times in my career, but the most vivid example is the Metals codebase (github.com/scalameta/me...).… — @gabro27.bsky.social0 likes and reposts · 1 reply

Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

15 rules. About 0 are common, 5 are distinctive, and 10 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
If Metals MCP tools are available, use them to run tests.
line 8
Distinctive:
Make sure to use the user's default shell to run the command.
line 18
Very specific:
ALWAYS format all changed Scala files using Metals MCP format-file tool or ./bin/scalafmt if the former is not available.
line 33
Very specific:
ALWAYS run sbt --client scalafixAll to fix any Scala code issues.
line 35
Very specific:
Don't use .iterator unless really necessary.
line 39
Distinctive:
Prefer for-loops over map/flatmap, unless they fit in one line (one or maximum two calls)
line 41
Very specific:
don't call .toList unless it's necessary
line 43
Very specific:
ALWAYS use Metals MCP tools to compile and run tests instead of relying on bash commands.
line 44
Very specific:
PREFER use Metals MCP tools to format code instead of relying on bash commands
line 46
Very specific:
ALWAYS use Metals MCP get-source tool to get the sources of a dependencies
line 47
Distinctive:
If MCP tools are not available report that to the user
line 48
Very specific:
after adding a dependency to build.sbt, ALWAYS run the import-build tool
line 49
Very specific:
use sbt --client instead of sbt to connect to a running sbt server for faster execution
line 52
Distinctive:
NEVER use non-local returns
line 54
Distinctive:
always create new commits, instead of amending existing ones
line 58

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

AGENTS.md

This document provides instructions for AI agents working on the Metals codebase.

Running Tests

If Metals MCP tools are available, use them to run tests. Otherwise, use the following command:

sbt --client SBT_PROJECT/testOnly TEST_CLASS "-- *TEST_NAME_GLOB"

Note: By convention, test names should be kebab-case with no spaces (e.g., private-member instead of private member).

Make sure to use the user's default shell to run the command.

Example

sbt --client javapc/testOnly pc.CompletionIdentifierSuite "-- *private-member"

For more information on filtering tests in MUnit, see the MUnit filtering documentation.

Preparing for PRs

Before committing:

ALWAYS format all changed Scala files using Metals MCP format-file tool or ./bin/scalafmt if the former is not available.
ALWAYS run sbt --client scalafixAll to fix any Scala code issues.

Working with Scala code

Don't use .iterator unless really necessary. Prefer working with higher order functions, like filter, map, flatmap directly on collections
Prefer for-loops over map/flatmap, unless they fit in one line (one or maximum two calls)
don't call .toList unless it's necessary
ALWAYS use Metals MCP tools to compile and run tests instead of relying on bash commands. Only use sbt if the MCP tools are not available.
PREFER use Metals MCP tools to format code instead of relying on bash commands
ALWAYS use Metals MCP get-source tool to get the sources of a dependencies
If MCP tools are not available report that to the user
after adding a dependency to build.sbt, ALWAYS run the import-build tool
to lookup a dependency or the latest version, use the find-dep tool
to lookup the API of a class, use the inspect tool
use sbt --client instead of sbt to connect to a running sbt server for faster execution
NEVER use non-local returns

Git

always create new commits, instead of amending existing ones

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free