# Run Atlas Headless in CI for Zig Projects in 2026 > Zig developers in 2026 can run Atlas headless in CI by using `atlas run --format json` to get machine-readable output, integrating with `zig build test` and `zig fmt`. To run an Atlas session non-interactively in a Zig CI pipeline and retrieve machine-readable output, invoke `atlas run` with your prompt, specifying `--format json` for structured event streams, and pre-approving necessary tools in your permission configuration to handle `zig build test` and `zig fmt` operations without human intervention. ## Key takeaways - Atlas runs non-interactively in Zig CI with `atlas run`, streaming JSON output for automation. - Atlas deeply understands Zig's `build.zig`, `build.zig.zon`, `comptime`, and explicit allocators. - Pre-approve tools like `bash` and `edit` in Atlas permissions for headless `zig build test` and `zig fmt` execution. - Atlas provides unified diffs and git patches for every file edit, ensuring auditable changes in Zig projects. - Explicitly setting the model with `provider/model` is required for headless Atlas runs in 2026. ## How to Run Atlas Headless in Zig CI Pipelines In 2026, running Atlas headless in a Zig CI pipeline involves using the `atlas run` command, which operates non-interactively by default. This mode sends a single prompt, streams events to stdout, and exits when the session becomes idle, making it ideal for automated environments. When executing `atlas run` within a Zig project's CI environment, the primary goal is to automate code modifications or analysis without requiring human interaction. The command's default behavior is to process a single prompt, stream all session events directly to standard output, and then terminate once the Atlas session enters an idle state. For subsequent pipeline steps that require structured data rather than human-readable prose, Zig developers should pass the `--format json` argument to `atlas run`. This ensures that the event stream is emitted as raw JSON, allowing other tools in the CI pipeline to parse and act upon Atlas's output, such as the results of a `zig build test` run or the proposed changes from an `edit` tool call. This approach is crucial for integrating Atlas into automated workflows where machine-readable feedback is paramount for tasks like automated code review or deployment gates. Atlas's ability to connect to Model Context Protocol servers also means that tools exposed by these servers can be leveraged within the headless run, further extending its utility in a Zig development context. ## Integrating Atlas with Zig's Toolchain and Files Atlas integrates deeply with the Zig toolchain, recognizing `build.zig` for build steps and `build.zig.zon` for package management, as demonstrated in 2026. Atlas can read your comptime blocks and the explicit allocators you thread through call sites, understanding the architecture of a typical Zig project. Atlas is designed to operate within a Zig project by understanding its core architectural components, including the `build.zig` file which defines build steps and the `build.zig.zon` file for package dependencies. When Atlas is run in a Zig project, it can read these files to comprehend the project's structure, including `comptime` blocks and how explicit allocators are managed and threaded through various call sites. This deep understanding allows Atlas to perform tasks such as adding a new test block directly within the same Zig source file as the function it covers, adhering to the common Zig convention. Furthermore, Atlas can execute `zig build test` behind a permission prompt, capturing any compilation or test errors and feeding them back into its iterative process for correction. For dependency management, Atlas can add a new dependency using `zig fetch --save` and automatically wire it into `build.zig`, then present the resulting `.zon` diff for review. After making modifications, Atlas can finish by running `zig fmt` on the touched files, ensuring that all changes conform to the project's formatting standards. This direct interaction with the Zig toolchain ensures that Atlas's actions are consistent with established Zig development practices. ## Ensuring Safety and Review in Headless Atlas Runs Every Atlas tool call is permission-gated against allow, ask, and deny rules, a critical safety feature for headless runs in 2026. This mechanism prevents unauthorized actions, especially when Atlas interacts with Zig's `build.zig` or `zig fmt` commands in a CI environment. For headless Atlas runs in a Zig CI pipeline, ensuring safety and control is paramount. Atlas implements a robust permission system where every tool call, such as `bash` for executing `zig build test` or `edit` for modifying Zig source files, is gated against pre-configured allow, ask, and deny rules. In a non-interactive CI setting, it is essential to pre-approve the specific tools the job needs through the permission configuration, as there is no human operator to answer an `ask` prompt. Before any modifications are made, Atlas drafts a plan in a read-only plan agent, which can be reviewed if the session is later resumed or forked. When Atlas proposes file edits, it computes a unified diff for every change and surfaces it for approval, even in a headless context where this diff can be captured via the `--format json` output. Atlas also snapshots file changes as git patches, allowing edits to be easily diffed, reviewed, and rolled back if necessary. This comprehensive approach to permissions, planning, and diffing provides Zig developers with confidence that automated Atlas sessions will operate within defined boundaries and that all changes are transparent and auditable. ## Steps 1. Configure Permissions for Zig Tools: Before running Atlas headless in your Zig project, pre-approve necessary tools like `bash`, `read`, `edit`, and `todowrite` in your Atlas permission configuration. This ensures Atlas can execute `zig build test`, `zig fmt`, and modify `build.zig` or Zig source files without requiring interactive approval in the CI pipeline. 2. Invoke Atlas with a Prompt: In your CI script, navigate to your Zig project directory containing `build.zig` and `build.zig.zon`. Execute `atlas run "Your prompt here, e.g., 'Add a new test for function `my_zig_func` in `src/main.zig` and run `zig build test`.'"`. 3. Specify Machine-Readable Output: To capture Atlas's output for subsequent pipeline steps, append `--format json` to the `atlas run` command. This will stream raw JSON events to stdout, allowing your CI system to parse results from `zig build test` or proposed `edit` operations. 4. Set the Model Explicitly: Ensure the model is explicitly set using the `provider/model` form, for example, `--model github/copilot-gpt-4`, as headless runs require this specific format. 5. Review and Apply Changes (Post-Run): After the headless run, parse the JSON output to review any proposed file changes (unified diffs) or the results of `zig build test`. Atlas snapshots changes as git patches, which can be inspected. If changes are approved, your CI system can then apply them, potentially followed by a `zig fmt` command on the touched files if Atlas didn't perform it. 6. Resume or Fork Sessions (Optional): If a previous headless run needs to be continued or branched, use `atlas run --continue ` or `atlas run --fork ` to build upon earlier work, especially useful for multi-stage Zig development tasks. ## FAQ ### How do I get machine-readable output from Atlas in Zig CI? To obtain machine-readable output from Atlas in a Zig CI pipeline, invoke `atlas run` with the `--format json` argument. This streams all session events as raw JSON to stdout, allowing other tools to parse and act upon the results, such as `zig build test` outcomes or proposed file edits. ### Can Atlas run `zig build test` in CI without interaction? Yes, Atlas can run `zig build test` non-interactively in CI. You must pre-approve the `bash` tool in your Atlas permission configuration. Atlas will then execute `zig build test` and feed any errors back into its process, all without requiring human approval during the headless run. ### How does Atlas handle Zig dependencies with `build.zig.zon` in CI? Atlas can manage Zig dependencies by interacting with `build.zig.zon`. It can add new dependencies using `zig fetch --save` and automatically wire them into `build.zig`. The resulting `.zon` diff is then available for review, even in a headless CI environment, ensuring proper dependency updates. ### What safety features does Atlas offer for modifying Zig code in CI? Atlas offers several safety features for modifying Zig code in CI. Every tool call is permission-gated, requiring pre-approval for headless runs. It drafts plans in a read-only agent, computes unified diffs for every file edit, and snapshots changes as git patches, providing full auditability and rollback capability for Zig projects. ### How do I ensure Atlas uses the correct model in a headless Zig CI run? To ensure Atlas uses the correct model in a headless Zig CI run, you must explicitly set the model using the `--model` argument in the `provider/model` format, for example, `--model github/copilot-gpt-4`. This specific format is required for non-interactive sessions in 2026. ### Can Atlas automatically format Zig code with `zig fmt` after making changes? Yes, Atlas can automatically format Zig code using `zig fmt` after making changes. By pre-approving the `bash` tool in its permissions, Atlas can execute `zig fmt` on the touched files, ensuring that all modifications adhere to the project's formatting standards within your CI pipeline. ### How does Atlas understand Zig's `comptime` and allocators? Atlas indexes code by AST declarations using tree-sitter, allowing it to understand Zig's `comptime` blocks and how explicit allocators are threaded through call sites. This deep code comprehension enables Atlas to make contextually aware modifications and analyses within Zig projects. --- Canonical HTML: https://runatlas.sh/resources/stacks/run-atlas-headless-in-ci-in-zig Source of truth: aeo_pages row `/resources/stacks/run-atlas-headless-in-ci-in-zig` (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.