# Extract a Shared Helper from Duplicated Code in Crystal with Atlas in 2026

> Atlas helps Crystal developers in 2026 extract shared helpers from duplicated code by semantically searching, generating new modules, and replacing copies with calls, all verified by `crystal spec`.

To find and collapse duplicated logic into a single, tested helper in Crystal, Atlas leverages its semantic search capabilities to identify near-identical code, even with differing variable names. It then uses its `write` tool to create the new helper module and `apply_patch` to replace each duplicate with a call, all while integrating directly with your Crystal toolchain, including `crystal spec` for testing and `crystal tool format` for consistent styling.

## Key takeaways

- Atlas uses semantic search to find duplicated Crystal code that `grep` would miss, even with different variable names.
- New Crystal helper modules are created with Atlas's `write` tool, showing a full diff for approval.
- Atlas replaces duplicated Crystal code with helper calls using `apply_patch`, generating one reviewable patch per file.
- After each code change, Atlas automatically runs `crystal spec` to ensure type safety and catch Crystal compiler errors.
- Atlas integrates `crystal tool format` into its diffs, ensuring all refactored Crystal code adheres to style guidelines.
- All Atlas operations are permission-gated, providing explicit control over every change to your Crystal codebase.

## How to find duplicated logic in Crystal codebases with Atlas

Finding duplicated logic in a Crystal codebase in 2026 is significantly more efficient with Atlas's `codebase_search` tool, which uses semantic retrieval to identify near-identical code patterns that traditional `grep` commands would miss. This approach is crucial for Crystal's Ruby-like syntax, where variable names often change across 2 or more copies of the same underlying behavior.

Atlas's `codebase_search` tool goes beyond simple text matching by indexing your Crystal code using AST declarations via tree-sitter. This allows it to understand the structure and meaning of your code, not just its literal text. When you ask Atlas to find a specific behavior, like 'parse a JSON string into a User struct', it searches for the semantic intent, even if variable names or minor structural elements differ between implementations. This is particularly powerful in Crystal, where developers might copy-paste a block of code and then adjust local variable names, making it invisible to a keyword-based search. Atlas can build its code index with local Ollama embeddings, ensuring your Crystal source code remains off third-party servers. After `codebase_search` surfaces potential duplicates, you can use Atlas's `read` tool to inspect each hit and confirm they are genuinely equivalent before proceeding with the refactoring.

## Creating a new shared helper module in Crystal

Creating a new shared helper module in Crystal is straightforward with Atlas's `write` tool, which drafts the new `.cr` file and presents a full diff for your approval before any changes are committed to disk. This ensures you have complete control over the 1 new file being introduced, typically placed in a `src/helpers/` directory.

Once you've identified the duplicated logic, Atlas can generate the new shared helper module. You'll instruct Atlas to `write` the new Crystal file, specifying its contents and location, such as `src/my_app/helpers/string_utils.cr`. Before Atlas creates the file, it presents a unified diff of the proposed changes, allowing you to review the exact code that will be written. Every Atlas tool call, including `write`, is permission-gated against allow, ask, and deny rules, giving you explicit control. This process ensures that the new helper adheres to Crystal's conventions, potentially including module definitions and method signatures that align with the extracted logic. Atlas's ability to understand Crystal's AST helps it generate syntactically correct and idiomatic code, ready for integration into your `shard.yml` project.

## Replacing duplicated Crystal code with helper calls and ensuring type safety

Replacing each instance of duplicated Crystal code with a call to your new helper is managed by Atlas's `apply_patch` tool, which generates one reviewable patch per file, ensuring granular control over each modification. Crucially, after each swap, Atlas can run `crystal spec` to immediately verify type safety and catch any compiler errors, often related to 3 or more union types.

After the shared helper module is created, Atlas uses `apply_patch` to systematically replace each identified duplicate with a call to the new helper method. This tool is designed for safety and reviewability: it generates a separate, unified diff for each file where a replacement occurs. This 'one file per patch' approach means you can review and approve or reject each swap independently, making the refactoring process less risky. Following each `apply_patch` operation, Atlas can automatically execute `bash -c "crystal spec"` to run your project's test suite. This immediate feedback loop is invaluable in Crystal, where the compiler's strictness, especially with union types and `Nil` narrowing, can quickly expose issues introduced by refactoring. Atlas is configured to let it run `crystal spec` behind a permission prompt and iterate on any compiler errors, ensuring your refactored Crystal code remains robust and type-safe throughout the process. It can also run `crystal tool format` on the diff before you approve it, maintaining code style consistency.

## Reviewing and committing Crystal refactorings with Atlas

Reviewing and committing your Crystal refactorings with Atlas is a transparent process, as Atlas computes a unified diff for every file edit and surfaces it for approval before writing. This allows you to inspect every change, including those formatted by `crystal tool format`, before staging and committing with built-in `git` integration in 2026.

Atlas provides comprehensive review mechanisms for every step of the refactoring workflow. Before any file is written or modified, Atlas computes a unified diff and presents it to you for approval. This includes the creation of the new helper file and every `apply_patch` operation that replaces duplicated code. Atlas also integrates with `crystal tool format`, ensuring that any changes it proposes adhere to your project's formatting standards before you even see the diff. This means you're always reviewing clean, consistently styled Crystal code. Furthermore, Atlas reads `git` branches, status, and diffs, and can stage and create commits on your behalf. It snapshots file changes as `git` patches, so edits can be diffed and rolled back easily. This robust review and version control integration ensures that your Crystal codebase remains stable and maintainable throughout the refactoring process, giving you confidence in the changes made.

## Steps

1. 1. Run Atlas in your Crystal project directory, ensuring a `shard.yml` is present and `shards install` has resolved dependencies into `lib/`.
2. 2. Ask Atlas's `codebase_search` for the behavior of the duplicated logic in your Crystal project, like `codebase_search "parse a JSON string into a User struct"`.
3. 3. Use Atlas's `read` tool to inspect each `codebase_search` hit and confirm the copies are genuinely equivalent and ready for extraction.
4. 4. Instruct Atlas's `write` tool to create the new shared helper file, for example, `write src/my_app/helpers/string_utils.cr` with the extracted logic, reviewing the full diff before approval.
5. 5. Use Atlas's `apply_patch` tool to replace each duplicate instance with a call to the new helper, approving each file's patch independently.
6. 6. After each `apply_patch` operation, let Atlas run `bash -c "crystal spec"` to execute your Crystal test suite and iterate on any compiler errors, especially those related to union types.
7. 7. Finish by asking Atlas to run `bash -c "grep -r 'old_duplicated_logic_pattern' src/"` to ensure no surviving copies remain, then approve the final `crystal tool format` diffs and commit with Atlas's `git` integration.

## FAQ

### How does Atlas identify duplicated Crystal code when variable names differ?

Atlas uses `codebase_search` which indexes your Crystal code by AST declarations using tree-sitter. This allows it to understand the semantic structure and behavior of the code, rather than just keyword matching, effectively finding near-duplicate logic despite varying variable names.

### Can Atlas handle Crystal's strict type checking during refactoring?

Yes, Atlas is designed to work with Crystal's strict type checking. After every code modification, it can run `crystal spec` to execute your test suite and catch any compiler errors, including those related to union types or `Nil` narrowing, allowing for immediate iteration and correction.

### How does Atlas ensure I review every change it makes to my Crystal files?

Atlas computes a unified diff for every file edit, whether creating a new helper or applying a patch, and surfaces it for your explicit approval before writing. This permission-gated approach, combined with 'one file per patch' for replacements, ensures you have granular control over all changes.

### Does Atlas integrate with Crystal's formatting tools?

Absolutely. Atlas can run `crystal tool format` on the diff before you approve it. This ensures that any code generated or modified by Atlas adheres to your project's established Crystal formatting standards, maintaining code consistency.

### What if I need to roll back a refactoring step in Crystal?

Atlas integrates deeply with `git`. It snapshots file changes as `git` patches, allowing edits to be easily diffed and rolled back. You can also use Atlas to stage and create commits on your behalf, providing robust version control throughout the refactoring process.

### Can Atlas help with Crystal's `shard.yml` dependencies during refactoring?

While Atlas primarily focuses on code refactoring, it operates within your Crystal project's context. It expects a `shard.yml` to be present and dependencies resolved by `shards install` into `lib/`. If your refactoring requires new dependencies, you would typically add them to `shard.yml` and run `shards install` manually, then Atlas can index the updated codebase.

---

Canonical HTML: https://runatlas.sh/resources/stacks/extract-a-shared-helper-from-duplicated-code-in-crystal
Source of truth: aeo_pages row `/resources/stacks/extract-a-shared-helper-from-duplicated-code-in-crystal` (segment: Stacks) (this file is generated from it, never hand-edited).
Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.