How does Atlas find *all* deprecated Nim API calls, including dynamic ones?

Atlas combines the `lsp` tool's `findReferences` operation, which uses AST declarations indexed by tree-sitter, with a `grep` search for the deprecated symbol. This dual approach ensures that both static and dynamic or string-based usages in Nim are identified.

Can Atlas handle Nim compile-time macros during API migration?

Yes, Atlas indexes Nim code by AST declarations using tree-sitter, which allows it to understand the structural context of your code, including how compile-time macros might define or use symbols, to accurately identify relevant callsites.

How does Atlas ensure my Nim tests pass after each API change?

After each file modification during the migration, Atlas uses the `bash` tool to execute `nimble test`, the standard Nim test runner. The corresponding `todowrite` entry is only marked complete if `nimble test` passes, ensuring continuous verification of your Nim codebase.

What if a Nim file drifts while Atlas is working on it?

Atlas's `apply_patch` tool is designed for safety. It uses context-anchored patches that will explicitly fail with "Failed to find expected lines" if the target Nim file has changed since the patch was generated, preventing misapplication to a drifted file.

How does Atlas integrate with my existing Nim development workflow?

Atlas runs within your Nim package, reading your `.nimble` file, modules, and exported symbols. It leverages your existing `nimble test` setup for verification and can format touched modules with `nph`, direct fitting into your Nim development environment.

Does Atlas keep my Nim code local?

Yes, Atlas is designed with privacy in mind. It can build its code index with local Ollama embeddings, ensuring that your Nim code remains on your local machine and is not sent to third-party servers.

How does Atlas ensure I approve changes before they are written to my Nim files?

Atlas operates with explicit user consent. It drafts a plan in a read-only agent, asks for approval before switching to a build agent, and computes a unified diff for every file edit, surfacing it for your approval before writing any changes to your Nim codebase.

Can Atlas help set up testing for a new Nim project?

Yes, you can ask Atlas to add a suite and check block from `std/unittest` under your `tests/` directory, providing a quick start for testing in your Nim project.

Migrate a Deprecated API Across Every Callsite in Nim with Atlas in 2026

Atlas helps Nim developers in 2026 migrate deprecated APIs across an entire codebase by systematically enumerating callsites, applying context-aware patches, and verifying changes with `nimble test` and `nph`. This ensures a complete and safe transition from an old function or module to its replacement without missing a single caller.

How Atlas finds all deprecated Nim API calls

Atlas ensures a complete migration of deprecated Nim APIs by combining two powerful search methods in 2026: the `lsp` tool's `findReferences` for AST-based calls and `grep` for dynamic or string-based usages. This dual approach guarantees that every single callsite, even those within Nim's compile-time macros, is identified and tracked.

To begin a migration in Nim, Atlas first leverages the `lsp` tool's `findReferences` operation. This capability queries the language server to yield a complete set of callers for a deprecated symbol, relying on Atlas's AST declarations indexed by tree-sitter. This method is highly effective for statically linked or directly invoked Nim functions and modules, including those within `nimble` packages. However, Nim's flexibility, especially with compile-time macros or dynamic code generation, means some usages might not be immediately apparent to a language server. For these cases, Atlas cross-checks the initial `lsp` results with a `grep` search for the deprecated symbol. This ensures that any string-based or dynamically constructed calls, which might otherwise be missed, are also identified. Once all potential callsites are enumerated, Atlas uses the `todowrite` tool to create a distinct entry for each one. This provides a clear, visible record of partial progress, ensuring that no callsite is silently skipped and the entire migration effort remains transparent and trackable within your Nim project.

Migrating Nim callsites with Atlas and `apply_patch`

Atlas migrates each deprecated Nim API callsite using the `apply_patch` tool, which performs context-anchored edits to ensure accuracy and prevent misapplication. After each file modification, Atlas immediately runs `nimble test` via the `bash` tool, confirming that the changes maintain the expected behavior of your Nim codebase in 2026.

The core of the migration process for deprecated Nim APIs with Atlas involves the `apply_patch` tool. This tool is designed for precision, performing each migration as a context-anchored patch. Instead of blindly applying changes, `apply_patch` actively seeks the hunk's context and `old_lines` within the target Nim file. If the expected lines are not found, perhaps due to a concurrent modification or a drift in the file, `apply_patch` will explicitly throw a 'Failed to find expected lines' error rather than guessing or misapplying the patch. This robust mechanism is crucial for maintaining the integrity of your Nim project. Following each successful file modification, Atlas immediately invokes the `bash` tool to run the affected tests. Specifically, it executes `nimble test`, the standard test runner for Nim projects. This critical step ensures that the changes introduced by the API migration have not inadvertently broken existing functionality. Only once `nimble test` passes for the modified file is the corresponding `todowrite` entry marked as completed, providing continuous, automated verification throughout the migration of your Nim codebase.

Ensuring Nim code quality and safety during migration

Atlas prioritizes safety and quality throughout the Nim API migration process in 2026, employing several mechanisms to protect your codebase. Every Atlas tool call is permission-gated, and all file edits are presented as unified diffs for approval, ensuring changes are reviewed before being written. Atlas also integrates `nimble test` and `nph` for continuous verification.

Atlas integrates robust safety and quality checks into every step of migrating deprecated Nim APIs. Before any tool call is executed, Atlas consults permission-gated allow, ask, and deny rules, ensuring that operations are only performed with explicit consent. This is particularly important when Atlas interacts with your Nim project's file system or executes commands like `nimble test`. Furthermore, Atlas drafts a comprehensive plan in a read-only plan agent and seeks approval before transitioning to a build agent that can make changes. For every file edit, Atlas computes a unified diff and surfaces it for your approval, allowing you to review the exact changes before they are written to your Nim source files. Atlas also reads git branches, status, and diffs, and can stage and create commits on your behalf, with file changes snapshotted as git patches for easy diffing and rollback. Beyond structural changes, Atlas ensures code quality by having you format touched modules with `nph`, Nim's standard formatter, after modifications. This commitment to review, permissions, and integration with Nim's toolchain provides a secure and controlled environment for large-scale API migrations.

Nim-specific setup for Atlas API migration

Setting up Atlas for a Nim API migration in 2026 is straightforward, requiring Atlas to run within a package containing a `.nimble` file. Atlas then reads your modules, exported symbols, and `requires` lines, integrating direct with your existing `nimble` project structure. It can even add `std/unittest` blocks and run `nimble test` behind a permission prompt.

To effectively migrate deprecated APIs in Nim, Atlas needs to be initialized within the context of your Nim project. This means running Atlas in a directory that contains a `.nimble` file, which serves as the package definition for your project. Atlas is designed to read and understand the structure of your Nim codebase by parsing these `.nimble` files, including your modules, exported symbols marked with an asterisk, and `requires` lines that define dependencies. This deep understanding allows Atlas to accurately index your code by AST declarations using tree-sitter, providing the foundation for precise `lsp` queries. For testing, Atlas can assist in setting up your verification infrastructure; you can ask Atlas to add a suite and check block from `std/unittest` under your `tests/` directory, if not already present. Crucially, when Atlas needs to execute your test suite, it will run `nimble test` behind a permission prompt, ensuring you retain control over command execution. After any modifications, Atlas can also be instructed to format the touched Nim modules using `nph`, Nim's official formatter, maintaining consistent code style across your project. This setup ensures Atlas operates as a native extension of your Nim development environment.

Step by step

01Enumerate every callsite of the deprecated Nim symbol using Atlas's `lsp` tool's `findReferences` operation, then cross-check with `grep` for any dynamic or string-based usages within your Nim project.
02Create one `todowrite` entry per identified Nim callsite using Atlas, ensuring partial progress is visible and no migration task is silently skipped.
03Migrate each Nim callsite with Atlas's `apply_patch` tool, which seeks the hunk's context and `old_lines` and will fail with "Failed to find expected lines" rather than misapplying to a drifted Nim file.
04After each Nim file modification, use Atlas's `bash` tool to run `nimble test` for the affected modules, and mark the `todowrite` entry as completed only once the tests pass.
05Finish the migration by using Atlas's `grep` tool to confirm zero remaining hits for the deprecated Nim symbol, then proceed to delete the old implementation.
06Have Atlas format the touched Nim modules with `nph` to maintain consistent code style across your project.

Frequently asked questions

How does Atlas find *all* deprecated Nim API calls, including dynamic ones?: Atlas combines the `lsp` tool's `findReferences` operation, which uses AST declarations indexed by tree-sitter, with a `grep` search for the deprecated symbol. This dual approach ensures that both static and dynamic or string-based usages in Nim are identified.
Can Atlas handle Nim compile-time macros during API migration?: Yes, Atlas indexes Nim code by AST declarations using tree-sitter, which allows it to understand the structural context of your code, including how compile-time macros might define or use symbols, to accurately identify relevant callsites.
How does Atlas ensure my Nim tests pass after each API change?: After each file modification during the migration, Atlas uses the `bash` tool to execute `nimble test`, the standard Nim test runner. The corresponding `todowrite` entry is only marked complete if `nimble test` passes, ensuring continuous verification of your Nim codebase.
What if a Nim file drifts while Atlas is working on it?: Atlas's `apply_patch` tool is designed for safety. It uses context-anchored patches that will explicitly fail with "Failed to find expected lines" if the target Nim file has changed since the patch was generated, preventing misapplication to a drifted file.
How does Atlas integrate with my existing Nim development workflow?: Atlas runs within your Nim package, reading your `.nimble` file, modules, and exported symbols. It leverages your existing `nimble test` setup for verification and can format touched modules with `nph`, direct fitting into your Nim development environment.
Does Atlas keep my Nim code local?: Yes, Atlas is designed with privacy in mind. It can build its code index with local Ollama embeddings, ensuring that your Nim code remains on your local machine and is not sent to third-party servers.
How does Atlas ensure I approve changes before they are written to my Nim files?: Atlas operates with explicit user consent. It drafts a plan in a read-only agent, asks for approval before switching to a build agent, and computes a unified diff for every file edit, surfacing it for your approval before writing any changes to your Nim codebase.
Can Atlas help set up testing for a new Nim project?: Yes, you can ask Atlas to add a suite and check block from `std/unittest` under your `tests/` directory, providing a quick start for testing in your Nim project.

Try Atlas in your terminal

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

Install Atlas

Related guides

Migrate a Deprecated API Across Every Callsite with Atlas (2026 Workflow)

How to migrate a deprecated API across every callsite with Atlas in 2026: the lsp tool's findReferences enumerates callers, todowrite tracks them, apply_patch migrates each one.

Atlas for Nim: A Terminal-Native AI Coding Agent for Nimble Packages and Macros in 2026

Atlas is a terminal-native AI coding agent for Nim in 2026. It reads .nimble requires and asterisk-exported symbols, adds std/unittest suites, runs nimble test, formats with nph.

Locate where a behavior is implemented in Nim with Atlas in 2026

In 2026, Nim developers use Atlas to pinpoint behavior implementations. Atlas combines semantic search, `grep`, and LSP tools to quickly find exact files and symbols within `nimble` projects, ensuring precise code

Run the test suite and triage the failures in Nim with Atlas in 2026

Efficiently run your Nim test suite and triage failures using Atlas in 2026. Turn a wall of red output into a prioritized list of distinct root causes.

Review a pull request in Nim with Atlas in 2026

Streamline your Nim pull request reviews in 2026 with Atlas. Leverage its AI to fetch branches, analyze diffs, run `nimble test`, and format code with `nph` for comprehensive feedback.

Run Atlas Headless in CI for Nim Projects in 2026

Automate Nim development workflows in 2026 with Atlas running headless in CI pipelines. Get machine-readable output for nimble projects, integrating with nimble test and nph for robust automation.

Write Unit Tests for Untested Nim Code with Atlas in 2026

In 2026, Nim developers use Atlas to write unit tests for untested modules, leveraging `nimble test` and `nph` to match existing repo conventions and ensure code quality. Atlas integrates direct with the Nim

Trace a Nim Runtime Bug from a Stack Trace with Atlas in 2026

Pinpoint and fix Nim runtime bugs from production stack traces using Atlas, the terminal-native AI coding agent. Leverage Nim's toolchain, including nimble and nph, for efficient debugging.

Browse this resource hub