How do I ensure Atlas can run GUT (Godot Unit Test) in CI?

To ensure Atlas can run GUT (Godot Unit Test) in your Godot CI, you must pre-approve the `bash` tool in Atlas's permission configuration. This allows Atlas to execute the command `godot --headless -s addons/gut/gut_cmdln.gd` to run your tests non-interactively.

Can Atlas format my GDScript files with gdformat (gdtoolkit) in a headless CI run?

Yes, Atlas can run `gdformat` from `gdtoolkit` over your GDScript files in a headless CI run. You need to ensure the `bash` tool is pre-approved in Atlas's permissions, allowing it to execute the `gdformat` command on the relevant `.gd` scripts.

What Godot-specific files does Atlas read to understand my project?

Atlas reads your `project.godot` file at the root of your project to understand its structure. It also parses your `.gd` scripts, analyzes node paths accessed via `$` or `get_node`, and identifies autoload singletons defined in your project settings.

How does Atlas handle permissions for modifying Godot files in CI without user interaction?

In a headless Godot CI environment, Atlas requires all necessary tools, such as `read` and `edit`, to be pre-approved in its permission configuration. This bypasses the interactive 'ask' prompt, allowing Atlas to modify `.gd` scripts and other project files without interruption.

How can I review the code changes Atlas proposes for my Godot project in CI?

When running `atlas run --format json`, Atlas computes and streams a unified diff for every file edit it proposes. Your Godot CI pipeline can parse this JSON output to extract these diffs, allowing for automated review, static analysis, or a human approval step before changes are applied.

Can Atlas help refactor get_node paths in Godot scripts to @onready var?

Yes, Atlas is capable of refactoring fragile `get_node` paths in your `.gd` scripts. It can replace them with `@onready var` and an exported `NodePath`, improving code robustness and maintainability within your Godot project.

What happens if an Atlas headless session in Godot CI encounters an error?

If an Atlas headless session encounters an error or requires further input it cannot get (e.g., an unapproved tool call), it will stream error events to stdout (especially with `--format json`) and eventually exit. You can then use `--continue` or `--session` to resume the session for debugging or further iteration.

Run Atlas Headless in CI for Godot Projects in 2026

For Godot developers in 2026, running Atlas headless in CI pipelines allows for automated code analysis and modification, providing machine-readable output for direct integration. Atlas can interact with your GDScript, node tree, and signals, leveraging tools like GUT (Godot Unit Test) for testing and gdformat (gdtoolkit) for code style, all without manual intervention. This enables robust, automated code quality and refactoring directly within your continuous integration environment.

How to Invoke Atlas Headless in Godot CI Pipelines

To run Atlas non-interactively within a Godot CI pipeline in 2026, use the atlas run command, which defaults to a single-prompt execution mode. This command sends one initial prompt, streams events to standard output, and then exits automatically once the session becomes idle, making it ideal for automated environments.

When integrating Atlas into a Godot CI pipeline, the primary command is `atlas run`. This command is specifically designed for non-interactive execution, allowing you to provide a single prompt as an argument. For instance, a pipeline step might invoke `atlas run 'Refactor the fragile get_node path in Player.gd to use an @onready var and an exported NodePath.'`. Atlas will then process this prompt, perform its operations, and stream all session events to stdout. Crucially, the session concludes and Atlas exits once all tasks are complete and the session enters an idle state. This behavior ensures that your CI job does not hang, providing a predictable execution flow for automated Godot development tasks. To ensure Atlas operates on your Godot project correctly, the CI environment must have a `project.godot` file at the root of the working directory, allowing Atlas to index your `.gd` scripts, node paths, and autoload singletons.

How to Get Machine-Readable Output from Atlas for Godot

For subsequent pipeline steps to programmatically parse Atlas's output in a Godot CI environment, specify the `--format json` flag with `atlas run`. This ensures that instead of human-readable prose, Atlas streams raw JSON events to stdout, providing structured data that can be easily consumed by other tools in your 2026 CI workflow.

When your Godot CI pipeline requires structured data from an Atlas session, rather than just human-readable logs, the `--format json` flag is essential. By running `atlas run --format json 'Add GUT tests for the new Player movement logic in Player.gd'`, Atlas will output a continuous stream of JSON objects, each representing a distinct event in the agent's lifecycle. This machine-readable format is critical for automating reactions to Atlas's actions, such as parsing proposed code changes, tool calls, or session status updates. For example, a CI script could parse this JSON stream to extract the unified diffs computed by Atlas for every file edit, allowing for automated review or further processing before changes are committed to your Godot project.

Managing Permissions and Godot Tooling for Headless Atlas Runs

In a headless Atlas session within a Godot CI pipeline, pre-approving necessary tools through the permission configuration is vital, as there is no interactive user to respond to 'ask' prompts. This ensures Atlas can execute tools like `bash`, `read`, `edit`, and `todowrite` without interruption, enabling it to interact with your Godot project files and run GUT (Godot Unit Test) or gdformat (gdtoolkit) effectively in 2026.

Atlas operates with a robust permission-gating system, requiring explicit approval for every tool call. In a headless CI environment for Godot, where no user is present to grant runtime permissions, all required tools must be pre-approved in Atlas's configuration. This includes fundamental tools like `bash` for executing shell commands, `read` for accessing file content, `edit` for modifying scripts, and `todowrite` for creating new files or updating existing ones. Without pre-approval, Atlas would halt, waiting for a response that will never come. For Godot-specific tasks, this means ensuring Atlas has permission to invoke `godot --headless -s addons/gut/gut_cmdln.gd` to run GUT (Godot Unit Test) or `gdformat` from `gdtoolkit` to format `.gd` scripts. This proactive permission management is crucial for uninterrupted and successful automated operations within your Godot CI pipeline.

Resuming and Forking Atlas Sessions for Godot CI Iterations

To build upon previous Atlas work or re-run a specific pipeline step in a Godot CI environment, you can resume or fork prior sessions using the `--continue`, `--session`, or `--fork` flags. This capability is particularly useful for iterative development or debugging in 2026, allowing a CI job to pick up exactly where a previous Atlas run left off, preserving context and progress.

Atlas provides powerful session management capabilities that are highly beneficial for Godot CI pipelines. If a CI job fails or needs further refinement, you can use `--continue` or `--session <session_id>` to resume an existing Atlas session. This allows Atlas to pick up from its last state, retaining its internal context, plan, and any partial changes. Alternatively, the `--fork <session_id>` flag enables you to create a new session based on an existing one, allowing for experimentation or parallel development paths without altering the original session. This is invaluable for Godot projects where a complex refactoring might require multiple iterations or different approaches. For example, if Atlas was tasked with replacing a fragile `get_node` path with an `@onready var` and an exported `NodePath` in a `.gd` script, and the CI job failed during the review step, you could resume the session to re-evaluate the proposed changes or fork it to try an alternative implementation.

Ensuring Code Review and Safety in Headless Godot Workflows

Atlas incorporates several safety mechanisms to ensure code quality and prevent unintended changes in headless Godot CI workflows, even without human interaction. Every Atlas tool call is permission-gated, and it drafts a plan in a read-only agent before executing. Crucially, Atlas computes a unified diff for every file edit, which can be surfaced for approval or automated checks in your 2026 pipeline.

Even in a non-interactive Godot CI setting, Atlas prioritizes safety and review. Before any action, Atlas drafts a comprehensive plan within a read-only plan agent, which can be part of the JSON event stream for review. This plan outlines the intended steps, such as modifying a `.gd` script or adding GUT (Godot Unit Test) cases. Furthermore, every tool call, including `edit` or `bash` commands to run `gdformat (gdtoolkit)`, is permission-gated, requiring pre-approval in the configuration for headless runs. Most importantly, Atlas computes a unified diff for every file edit it proposes. This diff is a critical output in the `--format json` stream, allowing your CI pipeline to programmatically review the changes. You can configure your pipeline to automatically apply changes only if they pass specific static analysis checks or require a human approval step based on the diff, ensuring that Atlas's modifications to your Godot project are always controlled and verifiable.

Step by step

01Set up your Godot project for Atlas: Ensure your CI environment has a `project.godot` file at the root and Atlas can read your `.gd` scripts, node paths, and autoload singletons.
02Configure Atlas permissions for Godot tools: Pre-approve `bash`, `read`, `edit`, and `todowrite` in Atlas's permission configuration, along with permissions to run `godot --headless -s addons/gut/gut_cmdln.gd` for GUT (Godot Unit Test) and `gdformat` from `gdtoolkit`.
03Invoke Atlas headless with a specific prompt: Run `atlas run --format json 'Refactor the fragile get_node path in Player.gd to use an @onready var and an exported NodePath and then run GUT tests.'` to initiate a non-interactive session and get machine-readable output.
04Monitor and parse Atlas's JSON event stream: Capture the stdout from `atlas run --format json` and parse the JSON events to track progress, identify tool calls, and extract unified diffs for proposed changes to your Godot project.
05Review and apply proposed Godot changes: Programmatically analyze the unified diffs generated by Atlas for `.gd` scripts and `project.godot` modifications, then decide whether to automatically apply them or flag for human review.
06Run Godot-specific checks and formatting: After Atlas edits, use `godot --headless -s addons/gut/gut_cmdln.gd` to run GUT (Godot Unit Test) and `gdformat` from `gdtoolkit` over touched scripts, ensuring code quality and style consistency.
07Commit changes or resume/fork session: If changes are approved, let Atlas stage and create commits. If further work is needed, use `atlas run --continue <session_id>` or `--fork <session_id>` to iterate on the Godot project.

Frequently asked questions

How do I ensure Atlas can run GUT (Godot Unit Test) in CI?: To ensure Atlas can run GUT (Godot Unit Test) in your Godot CI, you must pre-approve the `bash` tool in Atlas's permission configuration. This allows Atlas to execute the command `godot --headless -s addons/gut/gut_cmdln.gd` to run your tests non-interactively.
Can Atlas format my GDScript files with gdformat (gdtoolkit) in a headless CI run?: Yes, Atlas can run `gdformat` from `gdtoolkit` over your GDScript files in a headless CI run. You need to ensure the `bash` tool is pre-approved in Atlas's permissions, allowing it to execute the `gdformat` command on the relevant `.gd` scripts.
What Godot-specific files does Atlas read to understand my project?: Atlas reads your `project.godot` file at the root of your project to understand its structure. It also parses your `.gd` scripts, analyzes node paths accessed via `$` or `get_node`, and identifies autoload singletons defined in your project settings.
How does Atlas handle permissions for modifying Godot files in CI without user interaction?: In a headless Godot CI environment, Atlas requires all necessary tools, such as `read` and `edit`, to be pre-approved in its permission configuration. This bypasses the interactive 'ask' prompt, allowing Atlas to modify `.gd` scripts and other project files without interruption.
How can I review the code changes Atlas proposes for my Godot project in CI?: When running `atlas run --format json`, Atlas computes and streams a unified diff for every file edit it proposes. Your Godot CI pipeline can parse this JSON output to extract these diffs, allowing for automated review, static analysis, or a human approval step before changes are applied.
Can Atlas help refactor get_node paths in Godot scripts to @onready var?: Yes, Atlas is capable of refactoring fragile `get_node` paths in your `.gd` scripts. It can replace them with `@onready var` and an exported `NodePath`, improving code robustness and maintainability within your Godot project.
What happens if an Atlas headless session in Godot CI encounters an error?: If an Atlas headless session encounters an error or requires further input it cannot get (e.g., an unapproved tool call), it will stream error events to stdout (especially with `--format json`) and eventually exit. You can then use `--continue` or `--session` to resume the session for debugging or further iteration.

Try Atlas in your terminal

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

Install Atlas

Related 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 Godot: Terminal-Native AI Coding for GDScript and the Node Tree in 2026

Atlas is a terminal-native AI coding agent for Godot in 2026, working across GDScript, the node tree, and signals, where scene structure is half the program.

Rename a symbol across the repo in Godot with Atlas in 2026

Rename functions, classes, and constants across your Godot project with Atlas in 2026. Use `lsp`, `grep`, and `edit` for precise, safe refactoring, catching all references, even those `grep` alone misses.

Document a module with a README in Godot with Atlas in 2026

In 2026, Atlas helps Godot developers create accurate READMEs for modules by analyzing live GDScript code, node paths, and signals. Ensure your documentation reflects what your Godot project actually does today.

Upgrade a Dependency and Fix Breakage in Godot with Atlas in 2026

In 2026, Godot developers use Atlas to efficiently upgrade dependencies via Godot Asset Library (gd-plug) and resolve compile and test failures with precise, AI-driven fixes.

Research a third-party API before integrating it in Godot with Atlas in 2026

Streamline third-party API integration in Godot with Atlas in 2026. Use Atlas to research API documentation, fetch details, and generate Godot-native code, ensuring compatibility with your `project.godot` and `gdformat`

Extract a Shared Helper from Duplicated Godot Code with Atlas in 2026

Refactor duplicated GDScript logic in Godot projects with Atlas. Find semantic copies, create shared helpers, and replace code with atomic, test-verified patches using GUT and gdformat.

Add a Regression Test for a Godot Bug Fix with Atlas in 2026

Lock in Godot bug fixes with Atlas in 2026. Learn to write failing GUT tests, apply fixes, and confirm passes using Atlas's terminal-native AI agent for GDScript projects.

Browse this resource hub