How does Atlas run a specific `crystal spec` test?

Atlas uses its `bash` tool to execute `crystal spec` with specific filtering flags. For example, it might run `crystal spec spec/my_file_spec.cr --name 'MyClass should handle X'` to target a single test or a specific group of tests within a Crystal project.

Can Atlas understand Crystal's union types and `shard.yml` dependencies?

Yes, Atlas builds its code index by AST declarations using tree-sitter, allowing it to understand Crystal's classes, union types, and the dependencies resolved into `lib/` by `shards install` from your `shard.yml` file. This deep understanding is crucial for accurate navigation and suggestions.

How does Atlas ensure my Crystal code changes are formatted correctly?

Before you approve a proposed change, Atlas can run `crystal tool format` on the generated diff. This ensures that any modifications Atlas makes to your Crystal files adhere to your project's established formatting standards, maintaining code consistency.

What safety features does Atlas offer when modifying Crystal code?

Atlas offers several safety features: every tool call is permission-gated, it drafts a plan in a read-only agent for approval, and it computes a unified diff for every file edit for your review. Atlas also snapshots file changes as git patches, allowing for easy rollback of any Crystal code modifications.

Does Atlas use external servers for indexing my Crystal codebase?

No, Atlas can build its code index with local Ollama embeddings, keeping your Crystal code off third-party servers. This ensures that your proprietary Crystal codebase remains secure and private during the debugging process.

Can Atlas help me add logging to my Crystal application for debugging?

Absolutely. Atlas can use its `edit` tool to insert temporary logging statements, such as `puts` or `Log.info` calls, into your Crystal source files. You can then re-run `crystal spec` via Atlas's `bash` tool to observe the output and gather more information about the test failure.

How does Atlas handle complex Crystal code changes that span multiple files?

For complex or multi-hunk changes in Crystal, Atlas can utilize its `apply_patch` tool. This is more robust than chaining multiple `edit` commands and ensures that all related modifications are applied cohesively, still presenting a unified diff for your approval.

Debug a Single Failing Test in Crystal with Atlas in 2026

Atlas empowers Crystal developers in 2026 to debug a single failing test by directly interacting with the `crystal spec` test runner, navigating code with its LSP tool, and proposing fixes that respect `crystal tool format` standards. This terminal-native AI agent integrates deeply with the Crystal toolchain to streamline the debugging workflow.

How does Atlas debug a single failing Crystal test?

Atlas debugs a single failing Crystal test by first running the specific test in isolation using the `bash` tool, then analyzing the assertion and the exercised code. In 2026, this process leverages Crystal's `crystal spec` runner with precise filtering to minimize output and focus on the problem.

When a Crystal developer needs to debug a specific failing test, Atlas initiates the process by executing the `crystal spec` command through its `bash` tool. This allows Atlas to pass specific flags, such as a test filter, to run only the relevant test file or a single `it` block. For instance, Atlas might run `crystal spec spec/my_feature_spec.cr --name 'should handle edge cases'` to isolate the failure. After observing the output, Atlas uses its `read` tool to examine the test's assertion and the Crystal code it exercises. This initial step ensures that Atlas has a clear understanding of the expected behavior and the actual failure, setting the stage for deeper investigation within the Crystal codebase.

What Crystal commands does Atlas use to run tests?

Atlas uses the standard `crystal spec` command to run tests in Crystal projects, often with specific flags to isolate a single failing test. This approach, common in 2026, ensures that Atlas interacts with the test suite exactly as a human developer would, leveraging Crystal's built-in capabilities.

To run tests in a Crystal project, Atlas consistently employs the `crystal spec` command. This is the official test runner for Crystal, and Atlas integrates with it directly via its `bash` tool. For debugging a single failing test, Atlas will append filtering arguments to `crystal spec`. For example, to run tests within a specific file, it might execute `crystal spec spec/models/user_spec.cr`. To target an even more granular test, it could use `crystal spec spec/services/payment_processor_spec.cr --name 'PaymentProcessor should process valid transactions'`. This precise control over the `crystal spec` command allows Atlas to focus its debugging efforts, reducing noise and speeding up the identification of the root cause of a failure within the Crystal application.

How does Atlas navigate Crystal code to find test failures?

Atlas navigates Crystal code to pinpoint test failures by leveraging its `lsp` tool, which provides `goToDefinition` and `findReferences` operations. This capability, powered by AST declarations and local Ollama embeddings, allows Atlas to trace the call graph of a failing test within a Crystal project in 2026.

Once a failing test is identified, Atlas uses its `lsp` tool to understand the flow of execution within the Crystal codebase. The `lsp` tool, which indexes code by AST declarations using tree-sitter, allows Atlas to perform operations like `goToDefinition` to jump from a method call in a test to its implementation in a Crystal class or module. Similarly, `findReferences` helps Atlas locate all usages of a particular Crystal method or variable, which is crucial for understanding its impact. This deep code navigation, combined with Atlas's ability to build its code index with local Ollama embeddings, ensures that Atlas can accurately walk the call graph of the failing test, identifying the exact lines of Crystal code responsible for the incorrect behavior without sending code to third-party servers.

How does Atlas propose and apply fixes in Crystal?

Atlas proposes and applies fixes in Crystal by first forming a hypothesis, then using its `edit` tool to add temporary logging or modify production code. For more extensive changes, Atlas employs `apply_patch`, ensuring that all modifications are presented as a unified diff for developer approval in 2026.

After navigating the Crystal code and forming a hypothesis about the cause of the test failure, Atlas uses its `edit` tool to implement changes. This might involve adding temporary `puts` statements or `Log.info` calls to a Crystal file to gather more runtime information, which can then be observed by re-running `crystal spec`. Once the root cause is confirmed, Atlas uses `edit` to fix the production Crystal code. If the required change spans multiple hunks or is complex, Atlas can use the `apply_patch` tool, which is more robust for larger modifications. Before any changes are written to disk, Atlas computes a unified diff for every file edit and surfaces it for approval, ensuring the Crystal developer maintains full control. Atlas can also run `crystal tool format` on the diff before approval, adhering to Crystal's formatting standards.

How does Atlas ensure safety and review for Crystal code changes?

Atlas ensures safety and review for Crystal code changes through a multi-layered approach, including permission-gated tool calls and a read-only plan agent. In 2026, every proposed modification to a Crystal project, from a simple `edit` to a complex `apply_patch`, requires explicit developer approval before being written.

Safety and developer control are paramount when Atlas proposes changes to a Crystal codebase. Every Atlas tool call, including `bash` for running `crystal spec` or `edit` for modifying a `.cr` file, is permission-gated against allow, ask, and deny rules. Before making any modifications, Atlas drafts a plan in a read-only plan agent and asks for approval. This allows the Crystal developer to review the proposed strategy. When Atlas suggests code changes, it computes a unified diff for every file edit and surfaces it for approval. This diff clearly shows what will be added or removed from Crystal files. Furthermore, Atlas can read git branches, status, and diffs, and can stage and create commits on your behalf, ensuring that all changes are tracked and reversible. Atlas also snapshots file changes as git patches, so edits can be diffed and rolled back if needed, providing a robust safety net for Crystal development.

Step by step

01Run just the failing Crystal test with Atlas's `bash` tool, using `crystal spec` with a filter flag like `--name 'MyClass should do something'` to isolate output.
02Read the failing Crystal test and the module it exercises using Atlas's `read` tool to understand the assertion and code path.
03Use Atlas's `lsp` tool with `goToDefinition` and `findReferences` to walk the call graph of the Crystal code exercised by the failing test.
04Form a hypothesis about the Crystal code failure and check it: add temporary `puts` or `Log.info` statements with Atlas's `edit` tool, then re-run `crystal spec` via `bash`.
05Fix the production Crystal code with Atlas's `edit` tool; if the change spans several hunks, use `apply_patch` instead of chaining brittle edits.
06Approve the unified diff presented by Atlas, ensuring `crystal tool format` has been applied to the changes.
07Re-run the single Crystal test with `crystal spec` via `bash` to confirm the fix, then run the full `crystal spec` suite.
08Remove any temporary logging added to Crystal files using Atlas's `edit` tool and approve the final diff.

Frequently asked questions

How does Atlas run a specific `crystal spec` test?: Atlas uses its `bash` tool to execute `crystal spec` with specific filtering flags. For example, it might run `crystal spec spec/my_file_spec.cr --name 'MyClass should handle X'` to target a single test or a specific group of tests within a Crystal project.
Can Atlas understand Crystal's union types and `shard.yml` dependencies?: Yes, Atlas builds its code index by AST declarations using tree-sitter, allowing it to understand Crystal's classes, union types, and the dependencies resolved into `lib/` by `shards install` from your `shard.yml` file. This deep understanding is crucial for accurate navigation and suggestions.
How does Atlas ensure my Crystal code changes are formatted correctly?: Before you approve a proposed change, Atlas can run `crystal tool format` on the generated diff. This ensures that any modifications Atlas makes to your Crystal files adhere to your project's established formatting standards, maintaining code consistency.
What safety features does Atlas offer when modifying Crystal code?: Atlas offers several safety features: every tool call is permission-gated, it drafts a plan in a read-only agent for approval, and it computes a unified diff for every file edit for your review. Atlas also snapshots file changes as git patches, allowing for easy rollback of any Crystal code modifications.
Does Atlas use external servers for indexing my Crystal codebase?: No, Atlas can build its code index with local Ollama embeddings, keeping your Crystal code off third-party servers. This ensures that your proprietary Crystal codebase remains secure and private during the debugging process.
Can Atlas help me add logging to my Crystal application for debugging?: Absolutely. Atlas can use its `edit` tool to insert temporary logging statements, such as `puts` or `Log.info` calls, into your Crystal source files. You can then re-run `crystal spec` via Atlas's `bash` tool to observe the output and gather more information about the test failure.
How does Atlas handle complex Crystal code changes that span multiple files?: For complex or multi-hunk changes in Crystal, Atlas can utilize its `apply_patch` tool. This is more robust than chaining multiple `edit` commands and ensures that all related modifications are applied cohesively, still presenting a unified diff for your approval.

Try Atlas in your terminal

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

Install Atlas

Related guides

Debug a Single Failing Test with Atlas in 2026

How to debug one failing test with Atlas in 2026: run it in isolation with bash, walk the call graph with the lsp tool, and fix the code, not the assertion.

Atlas for Crystal: A Terminal-Native AI Coding Agent for shard.yml Projects in 2026

Atlas is a terminal-native AI coding agent for Crystal in 2026. It reads shard.yml and union types, narrows Nil unions, runs crystal spec behind a prompt, and formats the diff.

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

In 2026, Crystal developers use Atlas to efficiently run `crystal spec`, analyze extensive test output, and prioritize distinct root causes for failures, streamlining the debugging workflow.

Diagnose a hanging or long-running command in Crystal with Atlas in 2026

In 2026, Crystal developers use Atlas to diagnose hanging or slow `crystal spec` tests or `shards` commands. Learn how Atlas identifies blocked input and helps you get unstuck.

Self-review your working diff before committing in Crystal with Atlas in 2026

Catch your own mistakes in uncommitted Crystal code with Atlas in 2026. Use Atlas to review diffs, run `crystal spec`, `crystal tool format`, and manage changes before committing.

Migrate a deprecated API across every callsite in Crystal with Atlas in 2026

In 2026, use Atlas to systematically migrate deprecated Crystal APIs across your entire codebase. Leverage `crystal spec`, `shards`, and `crystal tool format` for a safe, verified transition, ensuring no callsite is

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

Refactor your Crystal codebase in 2026 by extracting duplicated logic into a shared helper using Atlas. Leverage semantic search, automated code generation, and `crystal spec` integration for safe, type-checked

Trace a runtime bug from a stack trace in Crystal with Atlas in 2026

Pinpoint Crystal runtime bugs from production stack traces in 2026 using Atlas, the terminal-native AI agent. Leverage `crystal spec` and `shards` for rapid, debugger-free fixes.

Browse this resource hub