Atlas is a terminal-native AI coding agent that works on Crystal projects in 2026, where Ruby-shaped syntax meets a compiler that will reject a union type you forgot to narrow. Atlas reads your classes, your union types, and the dependencies resolved into lib/ by shards install, then proposes edits as a unified diff. Atlas can run crystal spec behind a permission prompt, iterate on any compiler error, and run crystal tool format before you approve.
Why Crystal developers use Atlas
Crystal developers use Atlas because Crystal reads like Ruby and compiles like a strict static language, and Atlas is grounded in the code rather than in the syntax it resembles. Atlas indexes code by AST declarations using tree-sitter, so a 2026 search returns the real class or method.
The failure mode for AI tooling on Crystal is predictable: the code looks like Ruby, so the model writes Ruby, and the compiler rejects it because a String or Nil union was never narrowed. Atlas fights that with retrieval and with the compiler. Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, so a question about where a value can become Nil returns the method that introduces the union. Because Atlas indexes by AST declarations, the answer is the method definition with its return type, which is what tells you whether narrowing is needed. Atlas is a terminal-native TUI that runs beside crystal and shards.
Working in Crystal day to day with Atlas
Day to day in Crystal in 2026, Atlas reads your classes, union types, and the dependencies resolved into lib/ by shards install. Ask Atlas to narrow a Nil union or to add describe blocks under spec/, and Atlas drafts the plan in a read-only plan agent before it writes anything.
Narrowing a Nil union is the most common Crystal task an agent will be handed, and it is mechanical only until it is not. Atlas drafts a plan in a read-only plan agent and asks before switching to a build agent, so you see whether Atlas intends to guard with a nil check, to use not_nil!, or to change the method signature so the union never forms. Because Atlas has read the shards resolved into lib/, it knows which shard a type came from and does not invent a method that shard does not have. Atlas can fan out work to subagents that run in the foreground or in parallel background sessions when the same union appears across several classes.
Running crystal spec behind a permission prompt
Atlas can run crystal spec, but every Atlas tool call is permission-gated against 3 rules, allow, ask, and deny, before it runs. You allow crystal spec, Atlas runs the suite, and Atlas iterates on any compiler error rather than claiming a change compiles when it does not.
The Crystal compiler is the arbiter, so an agent that never runs it is guessing. When Atlas runs crystal spec behind a permission prompt, a type error about an unnarrowed union, a missing method on Nil, or a failing describe block all come back into the loop as evidence for the next iteration. Permission rules set the boundary: allow crystal spec and crystal build, ask before Atlas edits shard.yml or reruns shards install, and deny everything else. Adding a shard is a dependency decision and it gets its own prompt, so it never rides along inside a refactor you approved for a different reason.
Reviewing the diff and running crystal tool format
Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so in 2026 no Crystal class changes without your review. Atlas runs crystal tool format on the diff before you approve it, and it snapshots file changes as git patches so any edit can be rolled back.
Review is the point where a Crystal change is actually accepted, and formatting first keeps the review honest. Running crystal tool format on the diff means what you read is the semantic change: the guard clause that narrowed the union, the new describe block under spec/, the changed return type. Atlas snapshots file changes as git patches, so a narrowing that satisfied the compiler but changed behavior at runtime can be diffed and rolled back cleanly. Atlas also reads git branches, status, and diffs, and can stage and create commits on your behalf once you approve the change.
Keeping Crystal source local with Ollama embeddings
Atlas can build its code index with local Ollama embeddings, keeping code off third-party servers, so a Crystal team can index its classes and specs without shipping source anywhere. Atlas also connects to Model Context Protocol servers and exposes their tools to the agent in 2026.
Crystal projects are often small teams running production services, and the source is the business. Atlas can build its code index with local Ollama embeddings, so the embedding pass over your .cr files runs on your own machine. Atlas is extensible through plugins that contribute tools and hook into agent lifecycle events, which is how a team adds an internal shard check or a deploy validation to the loop. Atlas connects to Model Context Protocol servers and exposes their tools to the agent, and Atlas lets you switch the active model and provider on the fly with favorites and recents, so a spec-writing pass and a hard type-inference problem can use different models.
Getting started
- 01Run atlas in a project with a shard.yml
- 02Let Atlas read your classes, union types, and the dependencies resolved into lib/ by shards install
- 03Ask Atlas to narrow a Nil union or add describe blocks under spec/
- 04Let Atlas run crystal spec behind a permission prompt and iterate on any compiler error
- 05Have Atlas run crystal tool format on the diff before you approve it
Frequently asked questions
- does atlas work with crystal and shards
- Yes. Atlas runs in a project with a shard.yml and reads the dependencies resolved into lib/ by shards install before it proposes a change.
- can an ai agent fix crystal nil union errors
- Yes. Ask Atlas to narrow a Nil union. Atlas plans the narrowing, shows a unified diff, then runs crystal spec behind a permission prompt to prove the compiler accepts it.
- will an ai coding agent write ruby instead of crystal
- Atlas grounds its edits in your actual classes and union types and iterates on any compiler error from crystal spec, so a Ruby-shaped guess does not survive the loop.
- can atlas write crystal specs
- Yes. Ask Atlas to add describe blocks under spec/, then let Atlas run crystal spec behind a permission prompt to confirm they pass.
- does atlas format crystal code
- Yes. Atlas runs crystal tool format on the diff before you approve it, so the unified diff shows the semantic change and not formatting drift.
- is atlas safe to run on a private crystal codebase
- Atlas can build its code index with local Ollama embeddings, keeping code off third-party servers, and every tool call is permission-gated against allow, ask, and deny rules.
- can atlas commit crystal changes
- Yes. Atlas reads git branches, status, and diffs, and can stage and create commits on your behalf after you approve the diff.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Run Atlas Headless in CI in Crystal with Atlas in 2026
Learn how to integrate Atlas into your Crystal CI pipelines in 2026, running headless to automate code tasks, execute `crystal spec`, and format code with `crystal tool format`.
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
Add a Regression Test for a Crystal Bug Fix with Atlas in 2026
In 2026, Crystal developers use Atlas to add regression tests for bug fixes, ensuring code quality. Learn how Atlas leverages `crystal spec` and `shards` to lock in fixes with red-green testing.
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
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.
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.
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.