How does Atlas integrate with sbt for Scala projects?

Atlas runs `sbt` commands directly via its `bash` tool, allowing it to execute `sbt test` for ScalaTest, manage dependencies, and interact with your project's build lifecycle. It operates within your existing `build.sbt` configured environment.

Can Atlas refactor Scala implicits or typeclasses?

Yes, Atlas can refactor to typeclasses or add ScalaTest cases. It leverages its AST indexing with tree-sitter to understand Scala's structural elements like traits, implicits, and typeclasses, enabling intelligent transformations.

What happens if Atlas's patch fails to apply to my Scala file?

If a Scala file has drifted, Atlas's `apply_patch` tool will fail with 'Failed to find context'. This prevents unintended changes to a modified file, requiring you to resolve the drift or re-evaluate the patch before proceeding.

How does Atlas ensure my Scala code stays formatted during refactoring?

While Atlas focuses on structural changes, you can integrate `scalafmt` into your workflow by running `atlas bash "scalafmt"` after changes, or configure your `build.sbt` to apply formatting on compile, ensuring consistent code style.

How does Atlas handle large Scala codebases for refactoring?

Atlas indexes code by AST declarations using tree-sitter, not blind line windows, allowing it to understand the precise structure of large Scala codebases. It also uses hybrid semantic and keyword retrieval fused by reciprocal rank fusion for efficient and accurate searching.

Is it possible to roll back changes made by Atlas to Scala files?

Yes, Atlas snapshots file changes as `git patches` so edits can be diffed and rolled back. It also reads `git` branches and status, and can stage and create commits on your behalf, providing full version control integration.

Refactor a Legacy Scala Module with Atlas in 2026

Atlas helps Scala developers in 2026 refactor legacy modules by mapping public surfaces, pinning behavior with `sbt test` via ScalaTest, applying structural changes with `apply_patch`, and tracking progress with `todowrite`, ensuring no breaking changes to callers.

How to map a Scala module's public API and find callers with Atlas?

Atlas maps a Scala module's public API and enumerates all its callers by leveraging the `lsp` tool's `documentSymbol` and `findReferences` operations. This crucial first step, often completed in under 5 minutes, ensures you understand the module's external dependencies before any changes are made.

Before restructuring any Scala code, Atlas first builds a comprehensive understanding of the module's public surface. Using the `lsp` tool, Atlas executes `documentSymbol` on your target Scala file, such as `src/main/scala/com/example/LegacyModule.scala`, to identify all exported traits, classes, objects, and methods. For each identified symbol, Atlas then runs `lsp findReferences` across your entire `sbt` project. This process precisely enumerates every single callsite, providing a complete picture of where the legacy module is being used. This detailed mapping prevents silent breakage at unknown callsites, a common risk in refactoring efforts.

How does Atlas ensure no behavior changes in Scala refactoring?

Atlas ensures no behavior changes during Scala refactoring by strictly pinning the module's existing behavior. It achieves this by running your `ScalaTest via sbt test` suite and recording a green baseline, a process that typically takes less than 10 seconds for a well-configured project.

The core principle of safe refactoring is to prove that the module's external behavior remains unchanged. Atlas achieves this by integrating directly with your Scala project's existing test suite. Before any code modifications, Atlas executes `atlas bash "sbt test"`. This command runs all tests defined in files like `src/test/scala/com/example/LegacyModuleSpec.scala` using ScalaTest. Atlas records the output, establishing a 'green baseline' that confirms all existing tests pass. After each subsequent structural change, Atlas re-runs `atlas bash "sbt test"` to immediately verify that the module's behavior has not inadvertently shifted, providing continuous validation throughout the refactoring process.

How does Atlas apply structural changes safely to Scala code?

Atlas applies structural changes to Scala code with high precision using its `apply_patch` tool, which anchors on context lines and refuses to apply against a drifted file. This mechanism prevents unintended modifications, ensuring that a patch intended for a specific code state in 2026 only applies to that exact state.

When it's time to restructure the Scala module, Atlas uses the `apply_patch` tool. This tool is designed for robust and safe code modification. Instead of blindly overwriting lines, `apply_patch` seeks each hunk's context and old_lines within the target file, such as `src/main/scala/com/example/LegacyModule.scala`. If the file has drifted,meaning the context lines or old lines no longer match,`apply_patch` will fail with a 'Failed to find context' error. This prevents applying a patch to an outdated or modified version of the file, safeguarding against accidental corruption. After each successful hunk application, Atlas immediately re-runs `atlas bash "sbt test"` to confirm that the change did not introduce regressions, maintaining a continuous cycle of change and verification.

How does Atlas track refactoring progress and ensure code review for Scala?

Atlas tracks refactoring progress and ensures thorough code review for Scala projects by maintaining a `todowrite` list of remaining callsites and presenting a unified diff for every file edit. This transparent approach ensures that all 100% of changes are reviewed and approved before being written to disk.

Throughout the refactoring of a Scala module, Atlas provides mechanisms for tracking progress and ensuring rigorous review. The `todowrite` tool is used to maintain a list of remaining callsites that still need migration, preventing a partially refactored module from being mistaken for a finished one. For every proposed file edit, Atlas computes a unified diff, clearly showing the changes to files like `src/main/scala/com/example/LegacyModule.scala` or `build.sbt`. This diff is surfaced for your approval before Atlas writes any changes to disk. Furthermore, Atlas reads `git` branches, status, and diffs, and can stage and create commits on your behalf, allowing for easy rollback of edits via `git patches` if needed, ensuring a controlled and auditable refactoring workflow.

Step by step

01Map the Scala module's public surface: Use `atlas lsp documentSymbol` on your target Scala file (e.g., `src/main/scala/com/example/LegacyModule.scala`) to identify all exported symbols.
02Enumerate all callers: For each identified symbol, run `atlas lsp findReferences` across your `sbt` project to list every callsite.
03Pin behavior: Execute `atlas bash "sbt test"` to run your ScalaTest suite and record a green baseline, ensuring all existing tests pass before any changes.
04Restructure with precision: Apply structural changes to your Scala files (e.g., `src/main/scala/com/example/LegacyModule.scala`) using `atlas apply_patch`, which anchors on context lines and will fail if the file has drifted.
05Verify after each change: Immediately re-run `atlas bash "sbt test"` after each `apply_patch` hunk lands to confirm that the module's behavior remains unchanged.
06Track remaining work: Use `atlas todowrite` to keep a list of any remaining callsites that still need to be migrated or updated, ensuring a complete refactor.
07Review and approve: Review the unified diff presented by Atlas for every file edit and approve the changes before they are written to disk.

Frequently asked questions

How does Atlas integrate with sbt for Scala projects?: Atlas runs `sbt` commands directly via its `bash` tool, allowing it to execute `sbt test` for ScalaTest, manage dependencies, and interact with your project's build lifecycle. It operates within your existing `build.sbt` configured environment.
Can Atlas refactor Scala implicits or typeclasses?: Yes, Atlas can refactor to typeclasses or add ScalaTest cases. It leverages its AST indexing with tree-sitter to understand Scala's structural elements like traits, implicits, and typeclasses, enabling intelligent transformations.
What happens if Atlas's patch fails to apply to my Scala file?: If a Scala file has drifted, Atlas's `apply_patch` tool will fail with 'Failed to find context'. This prevents unintended changes to a modified file, requiring you to resolve the drift or re-evaluate the patch before proceeding.
How does Atlas ensure my Scala code stays formatted during refactoring?: While Atlas focuses on structural changes, you can integrate `scalafmt` into your workflow by running `atlas bash "scalafmt"` after changes, or configure your `build.sbt` to apply formatting on compile, ensuring consistent code style.
How does Atlas handle large Scala codebases for refactoring?: Atlas indexes code by AST declarations using tree-sitter, not blind line windows, allowing it to understand the precise structure of large Scala codebases. It also uses hybrid semantic and keyword retrieval fused by reciprocal rank fusion for efficient and accurate searching.
Is it possible to roll back changes made by Atlas to Scala files?: Yes, Atlas snapshots file changes as `git patches` so edits can be diffed and rolled back. It also reads `git` branches and status, and can stage and create commits on your behalf, providing full version control integration.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related guides

Refactor a Legacy Module with Atlas in 2026

How to refactor a legacy module with Atlas in 2026: findReferences maps every callsite, apply_patch refuses to apply against a drifted file, and bash proves behavior.

Atlas for Scala in 2026

Atlas is a terminal-native AI coding agent for Scala in 2026. Run it in a project with a build.sbt, let it read your traits and implicits, and approve every diff.

Plan a Multi-File Change Before Editing in Scala With Atlas (2026)

How to plan a multi-file Scala change before editing with Atlas in 2026: the plan agent denies edit for every path except .atlas/plans/*.md until you approve.

Onboard to an Unfamiliar Scala Codebase with Atlas (2026)

Build a mental model of a Scala repo without reading every file. Atlas starts from meaning in 2026 with codebase_search and glob, and delegates sweeps to a read-only subagent.

Write Unit Tests for Untested Code in Scala with Atlas (2026)

How to add ScalaTest coverage to an untested Scala module with Atlas in 2026: enumerate symbols with lsp documentSymbol, copy repo conventions, then run sbt test.

Run the Test Suite and Triage the Failures in Scala with Atlas (2026)

Atlas runs ScalaTest via sbt test with a generous timeout, retains the full log when output truncates at 2000 lines, and turns red output into a todowrite list.

Extract a shared helper from duplicated code in Scala with Atlas in 2026

Refactor Scala code efficiently in 2026 by extracting shared helpers from duplicated logic using Atlas. Leverage semantic search, `sbt test`, and `scalafmt` for safe, reviewable changes.

Rename a symbol across the repo in Scala with Atlas in 2026

Refactor Scala code with Atlas in 2026. Safely rename functions, classes, or constants across your entire sbt project, ensuring all references, including comments and strings, are updated accurately.

Browse this resource hub