How do I debug a hanging `crystal spec` test with Atlas?

To debug a hanging `crystal spec` test, run it via `atlas bash "crystal spec"`. Atlas will execute the command and, if it times out, provide `shell_metadata` indicating whether the test suite is genuinely slow or silently blocked on interactive input, guiding your next steps.

Can Atlas help when `shards install` seems stuck in Crystal?

Yes, if `shards install` appears stuck, run `atlas bash "shards install"`. Atlas will diagnose if the command is waiting for user input. If so, you can re-run it with non-interactive flags like `--no-input` or `-y` to unblock it.

What does Atlas mean by "blocked on interactive input" for Crystal commands?

For Crystal commands, "blocked on interactive input" means the command, such as `shards install`, is waiting for a user response (like a confirmation prompt) that it is not receiving. This causes it to hang indefinitely until the input is provided or it is terminated.

How do I increase the timeout for a slow Crystal command in Atlas?

If Atlas reports a Crystal command is genuinely slow, you can retry it with a larger timeout. Use `atlas bash --timeout "your_crystal_command"`, replacing ` ` with a value in milliseconds, for example, `60000` for one minute.

Does Atlas modify my Crystal code without explicit permission?

No, Atlas is designed with strong safety measures. Every tool call is permission-gated, and any proposed file edits, such as those from `crystal tool format`, are presented as a unified diff for your explicit approval before Atlas writes changes to your Crystal project.

How does Atlas understand my Crystal project's structure?

Atlas builds its code index using AST declarations via tree-sitter. It reads your `shard.yml` file and the dependencies resolved into `lib/`, allowing it to understand your Crystal classes, union types, and overall project structure for effective assistance.

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

In 2026, Crystal developers can diagnose a hanging or long-running `crystal spec` test or `shards` command by running it through Atlas's `bash` tool. Atlas races every command against a timeout, and if it expires, it explicitly tells you whether the command is genuinely slow or silently blocked on interactive input, allowing you to unblock it with non-interactive flags or adjust the timeout.

How Atlas Diagnoses Hanging Crystal Commands in 2026

In 2026, Atlas helps Crystal developers diagnose hanging commands by running them through its `bash` tool. This tool races every command against a timeout, and upon expiration, provides a clear diagnosis: either the command is genuinely slow or it is silently blocked, often waiting for interactive input.

Atlas's `bash` tool is designed to execute commands and provide detailed `shell_metadata` upon completion or timeout. When a Crystal command, such as `crystal spec` or `shards install`, is executed via `atlas bash "your_command"`, Atlas monitors its execution. If the command exceeds a predefined timeout, Atlas terminates it and analyzes the state. The `shell_metadata` block in Atlas's output will explicitly state whether the command was genuinely slow and simply needed more time, or if it was blocked, most commonly waiting for interactive input. This precise diagnosis is crucial for Crystal developers, as a command blocked on `stdin` will never resolve by simply waiting longer, unlike a genuinely slow but progressing operation. Atlas's ability to distinguish these scenarios prevents wasted debugging time and guides the developer to the correct next step.

Diagnosing `crystal spec` and `shards` with Atlas

Crystal developers in 2026 frequently encounter hanging `crystal spec` tests or `shards install` operations. Atlas's diagnostic workflow applies directly to these commands, helping to determine if a test suite is genuinely slow or if a package installation is waiting for an unexpected prompt.

When a `crystal spec` run appears to hang, or `shards install` seems stuck, Atlas provides a clear path forward. You would initiate the command through Atlas, for example, `atlas bash "crystal spec"` or `atlas bash "shards install"`. Atlas, having indexed your Crystal project's `shard.yml` and `lib/` dependencies, understands the context. If the command times out, Atlas's `shell_metadata` will indicate if it was blocked on interactive input. For `shards install`, this might mean it is waiting for a confirmation prompt. In such cases, the solution is to re-run the command with non-interactive flags, such as `atlas bash "shards install --no-input"` or `atlas bash "shards install -y"`. If Atlas determines the command is genuinely slow, perhaps due to a large test suite or complex compilation, it will instruct you to retry with a larger timeout value, like `atlas bash --timeout 60000 "crystal spec"` for a 60-second timeout.

Atlas's Safety and Review for Crystal Development

Atlas provides robust safety features for Crystal developers in 2026, ensuring every action is permission-gated. Before any tool call, Atlas asks for approval, and for file edits, it computes a unified diff, which is surfaced for explicit approval before writing changes to your Crystal project.

Working with Atlas in a Crystal project offers a secure and controlled environment. Every Atlas tool call, including `bash` commands, is permission-gated, requiring explicit allow, ask, or deny rules before execution. Atlas first drafts a plan in a read-only plan agent, seeking your approval before switching to a build agent that can make changes. When Atlas proposes modifications to your Crystal codebase, such as adding `describe` blocks under `spec/` or narrowing a `Nil` union type, it computes a unified diff for every file edit. This diff is then surfaced for your review and approval, ensuring you have full control over what changes are written. Atlas also reads `git` branches, status, and diffs, and can stage and create commits on your behalf, further integrating into your Crystal development workflow while maintaining transparency and safety. File changes are snapshotted as `git` patches, allowing edits to be easily diffed and rolled back.

Step by step

01Run `atlas` in your Crystal project, ensuring it has read your `shard.yml` and dependencies in `lib/`.
02Execute the potentially hanging Crystal command, such as `crystal spec` or `shards install`, through Atlas's `bash` tool: `atlas bash "crystal spec"`.
03Examine the `shell_metadata` block in Atlas's output when the command times out to determine if it was genuinely slow or blocked on interactive input.
04If Atlas indicates the command was blocked, re-run it with appropriate non-interactive flags, for example: `atlas bash "shards install --no-input"`.
05If Atlas reports the command was genuinely slow, retry it with a larger timeout value in milliseconds: `atlas bash --timeout 60000 "crystal spec"`.
06If you manually aborted the command, confirm the `shell_metadata` states "User aborted the command" to distinguish it from a timeout.

Frequently asked questions

How do I debug a hanging `crystal spec` test with Atlas?: To debug a hanging `crystal spec` test, run it via `atlas bash "crystal spec"`. Atlas will execute the command and, if it times out, provide `shell_metadata` indicating whether the test suite is genuinely slow or silently blocked on interactive input, guiding your next steps.
Can Atlas help when `shards install` seems stuck in Crystal?: Yes, if `shards install` appears stuck, run `atlas bash "shards install"`. Atlas will diagnose if the command is waiting for user input. If so, you can re-run it with non-interactive flags like `--no-input` or `-y` to unblock it.
What does Atlas mean by "blocked on interactive input" for Crystal commands?: For Crystal commands, "blocked on interactive input" means the command, such as `shards install`, is waiting for a user response (like a confirmation prompt) that it is not receiving. This causes it to hang indefinitely until the input is provided or it is terminated.
How do I increase the timeout for a slow Crystal command in Atlas?: If Atlas reports a Crystal command is genuinely slow, you can retry it with a larger timeout. Use `atlas bash --timeout <milliseconds> "your_crystal_command"`, replacing `<milliseconds>` with a value in milliseconds, for example, `60000` for one minute.
Does Atlas modify my Crystal code without explicit permission?: No, Atlas is designed with strong safety measures. Every tool call is permission-gated, and any proposed file edits, such as those from `crystal tool format`, are presented as a unified diff for your explicit approval before Atlas writes changes to your Crystal project.
How does Atlas understand my Crystal project's structure?: Atlas builds its code index using AST declarations via tree-sitter. It reads your `shard.yml` file and the dependencies resolved into `lib/`, allowing it to understand your Crystal classes, union types, and overall project structure for effective assistance.

Try Atlas in your terminal

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

Install Atlas

Related guides

Diagnose a Hanging or Long-Running Command with Atlas in 2026

How to diagnose a hanging command with Atlas in 2026: the bash tool races every command against a timeout and tells you whether it is slow or blocked on input.

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.

Rename a Symbol Across the Repo in Crystal with Atlas in 2026

In 2026, Crystal developers use Atlas to accurately rename functions, classes, and constants across their entire codebase, leveraging `crystal spec` and `shards` for verification.

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

Debug a Single Failing Test in Crystal with Atlas in 2026

In 2026, Crystal developers use Atlas to efficiently debug single failing tests. Atlas leverages `crystal spec`, `shards`, and `crystal tool format` to pinpoint and fix issues.

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

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.

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.

Browse this resource hub