To run an Atlas session non-interactively in a Crystal CI pipeline and obtain machine-readable output, you invoke `atlas run` with the `--format json` flag, ensuring your Atlas configuration pre-approves necessary tools like `bash` and `edit` for direct execution of Crystal's `crystal spec` and `crystal tool format` commands. This approach allows Atlas to automate tasks, iterate on code, and provide structured feedback directly within your continuous integration workflow, leveraging its deep understanding of Crystal's AST declarations and `shard.yml` dependencies.
How to Run Atlas Headless in Crystal CI Pipelines
Running Atlas headless in a Crystal CI pipeline in 2026 is achieved by using the `atlas run` command, which operates non-interactively. This mode sends a single prompt, streams events to standard output, and exits once the session becomes idle, making it ideal for automated environments.
The `atlas run` command is specifically designed for non-interactive execution within CI/CD pipelines. When integrated into a Crystal project, Atlas can be prompted to perform tasks such as adding `describe` blocks under `spec/` or narrowing a `Nil` union type. The default behavior of `atlas run` is to process a single prompt and then terminate, ensuring that your pipeline step completes without requiring human intervention. This allows for automated code generation, refactoring, or testing within your Crystal codebase, leveraging Atlas's ability to read `shard.yml` and the dependencies resolved into `lib/` by `shards install`.
Configuring Atlas Permissions for Crystal Toolchain Automation
For Atlas to operate effectively in a headless Crystal CI environment, all necessary tool calls must be pre-approved in the permission configuration. This is critical because a headless run has no interactive prompt to answer 'ask' rules, ensuring that Atlas can execute commands like `crystal spec` or `crystal tool format` without interruption in 2026.
Atlas's robust permission system requires explicit approval for every tool call, which is managed through 'allow', 'ask', and 'deny' rules. In a headless CI context, where no user is present to respond to 'ask' prompts, all tools required for the job must be pre-approved with 'allow' rules. For Crystal development, this typically includes `bash` for executing shell commands (like `crystal spec` or `shards install`), `read` for accessing files, `edit` for modifying code, and `todowrite` for creating temporary notes. By pre-configuring these permissions, Atlas can direct interact with your Crystal project, running tests, applying formatting, and making code changes as directed by the initial prompt, all while maintaining a secure and controlled environment.
Obtaining Machine-Readable Output from Atlas in Crystal CI
To enable subsequent pipeline steps to programmatically parse Atlas's output in a Crystal CI workflow, you must invoke `atlas run` with the `--format json` flag. This ensures that Atlas streams raw event data rather than human-readable prose, providing structured information for automated processing in 2026.
When `atlas run` is executed with `--format json`, Atlas streams a continuous sequence of JSON objects to standard output, each representing a distinct event in the agent's lifecycle. This machine-readable format is invaluable for CI pipelines where automated tools need to consume and react to Atlas's actions, such as detecting when a file has been edited, a test has been run, or a plan has been drafted. For Crystal projects, this means a CI job can, for example, parse the JSON stream to identify when Atlas has run `crystal spec` and reported test failures, or when it has applied `crystal tool format` and generated a unified diff. This structured output allows for sophisticated automation, enabling pipelines to trigger further actions based on Atlas's progress and outcomes.
Iterating and Resuming Atlas Sessions for Crystal Development
Atlas supports resuming or forking prior sessions in a Crystal CI pipeline using `--continue`, `--session`, or `--fork`, allowing for iterative development and debugging. This capability is crucial for complex tasks that might span multiple CI runs or require building upon previous Atlas actions, a common scenario in 2026's advanced development workflows.
The ability to resume or fork an Atlas session is a powerful feature for managing complex or multi-stage Crystal development tasks within CI. If an initial `atlas run` session completes but further refinement is needed, or if a pipeline step fails and needs to be replayed, `--continue` allows Atlas to pick up exactly where it left off. Alternatively, `--session` can be used to specify a particular session ID to resume, while `--fork` creates a new session based on an existing one, preserving its context. This means Atlas can, for instance, run `crystal spec`, identify a compiler error, and then in a subsequent CI run, resume the session to iterate on the fix, or even run `crystal tool format` on the diff before it's approved, ensuring code quality throughout the iterative process.
Step by step
- 01Initialize your Crystal project with `shards init` if you haven't already, ensuring a `shard.yml` file is present for Atlas to index.
- 02Add Atlas to your CI pipeline configuration, ensuring the `atlas` executable is available in the environment.
- 03Configure Atlas permissions by creating or updating your Atlas configuration to pre-approve tools like `bash`, `read`, `edit`, and `todowrite` with 'allow' rules for headless execution.
- 04Invoke `atlas run` in your CI script, passing your prompt as an argument and including `--format json` for machine-readable output. For example: `atlas run 'Add a new method to MyClass that returns 42' --format json`.
- 05Explicitly set the model using the `provider/model` form, e.g., `--model openai/gpt-4o`, as required for headless runs.
- 06Parse the JSON event stream from `stdout` in a subsequent CI step to process Atlas's actions, such as identifying when `crystal spec` was run or a file was modified.
- 07Optionally, use `atlas run --continue` or `atlas run --session <session_id>` in a later pipeline step to resume a previous Atlas session and build upon its context, for example, to iterate on a fix identified by `crystal spec`.
Frequently asked questions
- How do I run `crystal spec` with Atlas in CI?
- You can run `crystal spec` with Atlas in CI by pre-approving the `bash` tool in your Atlas configuration and then prompting Atlas to execute the `crystal spec` command within your `atlas run` session.
- Can Atlas format Crystal code in a CI pipeline?
- Yes, Atlas can run `crystal tool format` on proposed changes within a CI pipeline. It computes a unified diff for every file edit and surfaces it for approval, even in headless mode if pre-approved.
- How does Atlas handle permissions for Crystal tools in headless mode?
- In headless mode, all tools Atlas needs to use, such as `bash` for `crystal spec` or `edit` for code changes, must be pre-approved with 'allow' rules in the Atlas configuration, as there's no interactive prompt for 'ask' rules.
- What kind of output does `atlas run` provide for Crystal CI?
- `atlas run --format json` provides a raw event stream in JSON format, which is machine-readable and ideal for automated parsing by subsequent steps in your Crystal CI pipeline, unlike the default prose output.
- How does Atlas understand my Crystal codebase structure?
- Atlas indexes Crystal code by AST declarations using tree-sitter, allowing it to understand classes, union types, and dependencies resolved into `lib/` by `shards install` from your `shard.yml`.
- Can I resume an Atlas session in a Crystal CI pipeline?
- Yes, you can resume a prior Atlas session in a Crystal CI pipeline using `atlas run --continue` or `atlas run --session <session_id>`, enabling iterative development and building upon previous agent actions.
- Does Atlas support local embeddings for Crystal code indexing?
- Yes, Atlas can build its code index with local Ollama embeddings, ensuring your Crystal code remains off third-party servers while still benefiting from semantic search capabilities.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Run Atlas Headless in CI with Atlas (2026 Workflow)
How to run Atlas headless in CI in 2026: atlas run sends one prompt and exits when the session goes idle, with --format json, --command, and --continue for pipeline steps.
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.
Review a Pull Request in Crystal with Atlas in 2026
In 2026, review Crystal pull requests with Atlas, the terminal-native AI coding agent. Leverage `crystal spec`, `shards`, and `crystal tool format` for deep, context-aware code analysis.
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.
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.
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.
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.