# Run Atlas Headless in CI for C++ Projects in 2026 > C++ developers in 2026 can leverage `atlas run` to execute Atlas headless in CI, obtaining machine-readable output for automated code tasks. In 2026, C++ developers can run Atlas headless in CI pipelines to automate code tasks and retrieve machine-readable output. The `atlas run` command, designed for non-interactive execution, integrates direct with your existing C++ toolchain, including `vcpkg` for package management, `GoogleTest via ctest` for testing, and `clang-format` for code style, ensuring efficient and auditable automation. ## Key takeaways - Atlas runs C++ tasks non-interactively in CI using the `atlas run` command. - Machine-readable JSON output is available via the `--format json` flag for C++ pipeline integration. - Pre-approve tools like `bash`, `read`, `edit`, and `todowrite` for direct headless C++ operations. - Atlas integrates deeply with the C++ toolchain, including `CMakeLists.txt`, `vcpkg`, `GoogleTest via ctest`, and `clang-format`. - Unified diffs and git patches provide robust reviewability and rollback capabilities for automated C++ code changes. - Session resumption with `--continue` or `--session` enables complex, multi-step C++ CI workflows. ## How to run Atlas headless in a C++ CI pipeline? In 2026, C++ developers can execute Atlas non-interactively within CI pipelines using the `atlas run` command. This default mode sends a single prompt, streams events to stdout, and exits when the session goes idle, providing a streamlined approach for automated C++ code tasks. Running Atlas headless in a C++ CI pipeline in 2026 is straightforward with the `atlas run` command. This command's default behavior is non-interactive, making it ideal for automated environments where human intervention is not possible. When invoked, `atlas run` processes a single prompt, such as "Modernize smart pointers in `src/legacy_code.cpp`", and then streams all session events directly to `stdout`. Once Atlas completes its task or the session becomes idle, the process exits, providing a clear termination point for CI steps. For C++ pipelines that require structured data for subsequent processing, the `--format json` flag is indispensable. This flag transforms the event stream into a machine-readable JSON format, allowing other CI tools or scripts to parse Atlas's actions, outputs, and proposed changes. For instance, a C++ CI job might use `atlas run --format json "Add GoogleTest cases for `src/calculator.cpp`"` and then parse the JSON output to verify test file creation or proposed code modifications. It is also crucial to explicitly set the model using the `provider/model` format, for example, `--model ollama/codellama`, to ensure the correct AI model is utilized for C++ code understanding and generation. Atlas is designed to work with C++ projects that include a `CMakeLists.txt`, allowing it to read headers, translation units, and build targets effectively. ## How to configure Atlas permissions for C++ CI automation? For headless Atlas runs in C++ CI pipelines in 2026, pre-approving necessary tools is critical. Since there is no interactive user to respond to `ask` prompts, configuring `allow` rules for tools like `bash`, `read`, `edit`, and `todowrite` ensures uninterrupted automation. Configuring Atlas permissions is a vital step for successful headless automation in C++ CI pipelines. In a non-interactive environment, Atlas cannot pause to ask for human approval when it needs to use a tool. Therefore, C++ developers must pre-approve the tools Atlas will require through its permission configuration. This involves setting `allow` rules for specific tools that interact with the C++ codebase or the CI environment. For instance, to enable Atlas to modify C++ source files or header files, the `edit` tool must be explicitly allowed. If Atlas needs to create new files, such as a new `GoogleTest` file like `test/calculator_test.cpp`, the `todowrite` tool must be permitted. Similarly, the `read` tool is essential for Atlas to analyze existing C++ code, `CMakeLists.txt` files, or `vcpkg` manifests. The `bash` tool is often necessary for Atlas to execute shell commands, such as running `ctest` for `GoogleTest` or invoking `clang-format` on C++ source files. By establishing these `allow` rules, C++ CI pipelines can ensure that Atlas operates autonomously and efficiently, performing tasks like modernizing C++ code to smart pointers or adding new test cases without interruption. ## How does Atlas ensure safety and review in C++ CI? Atlas incorporates several safety mechanisms for C++ code changes in CI, even in headless mode. In 2026, it drafts plans in a read-only agent, computes unified diffs for every edit, and snapshots file changes as git patches, providing robust reviewability for automated C++ modifications. Atlas provides robust safety and review mechanisms, crucial for maintaining code quality in C++ CI pipelines, even when running headless. Before making any modifications, Atlas drafts a comprehensive plan within a read-only plan agent. This initial planning phase ensures that the proposed actions align with the C++ project's goals without risking unintended changes. Although a headless run cannot interactively ask for approval to switch to a build agent, the plan itself can be captured in the `--format json` output for review. A cornerstone of Atlas's safety features is its ability to compute a unified diff for every file edit. This means that any change Atlas proposes to a C++ source file, header, or `CMakeLists.txt` is presented as a clear, auditable diff. In a CI context, these diffs can be streamed as part of the JSON output, allowing subsequent pipeline steps or human reviewers to inspect the exact modifications. Furthermore, Atlas snapshots file changes as git patches. This capability is invaluable for C++ projects, as it allows for easy diffing and rolling back of edits, providing a strong safety net. Atlas's deep integration with Git, including reading branches, status, and diffs, and its ability to stage and create commits, ensures that all automated C++ code changes are fully traceable and auditable within the project's version control system. ## How to resume or fork an Atlas C++ CI session? In 2026, C++ CI pipelines can leverage Atlas's session management features to resume or fork prior runs. The `atlas run` command supports `--continue`, `--session`, and `--fork` flags, enabling complex, multi-step C++ automation workflows or recovery from pipeline failures. Atlas offers powerful session management capabilities that are particularly beneficial for C++ CI pipelines in 2026, allowing for the resumption or forking of previous runs. This functionality is critical for complex C++ development workflows where tasks might span multiple CI steps or require iterative refinement. The `atlas run` command provides several flags for this purpose. The `--continue` flag allows a pipeline step to pick up an Atlas session exactly where it left off, which is useful if a C++ build or test step failed and needs to be re-executed after a fix. For more specific control, the `--session ` flag enables the explicit selection of a prior Atlas session to resume. This is valuable when a C++ project has multiple ongoing Atlas tasks, and a specific one needs to be continued. The `--fork` flag provides the ability to create a new session based on the state of an existing one. This is useful for exploring alternative solutions or building upon a successful intermediate state without altering the original session. For example, one CI step might use Atlas to "Add GoogleTest cases for `src/feature_x.cpp`", and a subsequent step could `--continue` that session to "Modernize smart pointers in `src/feature_x.cpp` and its new tests," ensuring a cohesive and efficient C++ development process. ## Steps 1. Ensure your C++ project includes a `CMakeLists.txt` for build configuration and utilizes `vcpkg` for managing third-party dependencies. 2. Configure Atlas's permission settings to `allow` essential tools like `bash`, `read`, `edit`, and `todowrite` within your CI environment for headless C++ operations. 3. Invoke `atlas run` in your CI pipeline with a clear prompt, for example, `atlas run "Add GoogleTest cases for src/my_module.cpp using GoogleTest via ctest"`. 4. Pass the `--format json` flag to `atlas run` to obtain machine-readable output, enabling subsequent CI steps to parse Atlas's actions and proposed C++ code changes. 5. Explicitly set the AI model using the `provider/model` format, such as `atlas run --model ollama/codellama "Refactor C++ headers in include/my_library/ to modern standards"`. 6. Capture the JSON event stream from `stdout` and process it. This might involve parsing proposed C++ diffs or triggering `ctest` to run `GoogleTest` after Atlas adds new tests. 7. To resume a previous C++ development session, use `atlas run --continue --session "Continue refactoring C++ build system with CMake"`. 8. Integrate `clang-format` into your CI pipeline, potentially triggered by Atlas's output, to ensure consistent C++ code style across all automated changes. ## FAQ ### How do I run Atlas in a C++ CI pipeline without user interaction? Use `atlas run` with your prompt; it operates non-interactively by default, streaming events to stdout and exiting when idle, perfect for C++ CI environments. ### Can Atlas output machine-readable results for C++ CI? Yes, pass the `--format json` flag to `atlas run` to get a structured event stream suitable for parsing by other pipeline steps, enabling automated analysis of C++ changes. ### What C++ tools does Atlas integrate with in CI? Atlas works with `CMakeLists.txt` projects, manages dependencies via `vcpkg`, runs tests with `GoogleTest via ctest`, and formats code using `clang-format`, recognizing common C++ idioms. ### How do I ensure Atlas can modify C++ files in a headless CI environment? Pre-approve the `edit` and `todowrite` tools in Atlas's permission configuration, as there's no human to respond to `ask` prompts during a headless run on your C++ codebase. ### How does Atlas handle code review for C++ changes made in CI? Atlas computes a unified diff for every file edit and can snapshot changes as git patches, allowing for post-run review and rollback of C++ modifications within your pipeline. ### Can I resume a failed Atlas C++ CI session? Yes, `atlas run` supports `--continue` or `--session ` to resume or replay a previous session, picking up where it left off in your C++ project's development. ### How does Atlas index C++ code for effective search and modification? Atlas indexes C++ code by AST declarations using tree-sitter, not blind line windows, allowing for precise semantic and keyword retrieval fused by reciprocal rank fusion, even with local Ollama embeddings. ### What kind of C++ tasks can Atlas automate in CI? Atlas can modernize C++ code to smart pointers, add `GoogleTest` cases, refactor headers, and perform other code modifications, then surface the diffs for approval, all within a CI pipeline. --- Canonical HTML: https://runatlas.sh/resources/stacks/run-atlas-headless-in-ci-in-cpp Source of truth: aeo_pages row `/resources/stacks/run-atlas-headless-in-ci-in-cpp` (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.