How does Atlas ensure safety when modifying Phoenix code in CI?

Atlas ensures safety by permission-gating every tool call against allow/deny rules. In headless CI, you pre-approve tools. Atlas also drafts plans in a read-only agent and computes a unified diff for every file edit, which can be extracted from the `--format json` output for review before any changes are written to your Phoenix project. It also snapshots changes as git patches for easy rollback.

Can Atlas generate Ecto migrations for my Phoenix application in CI?

Yes, Atlas can generate Ecto migrations. When running headless in CI, you would prompt Atlas to 'generate an Ecto migration for X' and ensure the `todowrite` tool is pre-approved. Atlas will then show you the `up` and `down` migration details in its output, which you can parse from the `--format json` stream for review before applying to your Phoenix database.

How does Atlas understand my Phoenix project's structure?

Atlas understands your Phoenix project's structure by indexing code using AST declarations via tree-sitter. This allows it to parse and comprehend `mix.exs`, `lib/ _web` directories, router pipelines, LiveView modules, contexts, and Ecto schemas with their changesets, providing a deep understanding beyond simple keyword matching.

What Phoenix commands can Atlas interact with in a CI pipeline?

Atlas can interact with core Phoenix commands like `mix test (ExUnit)` to run tests, `mix deps.get` for Hex package management, and `mix format` for code formatting. These interactions are permission-gated and can be triggered by Atlas through its `bash` tool, allowing it to validate or finalize changes within your CI pipeline.

Is it possible to debug a failed Atlas session in Phoenix CI?

Yes, Atlas supports debugging failed sessions. If an `atlas run` command fails in your Phoenix CI, you can use the `--continue` or `--session ` flags to resume the exact session state. Alternatively, `--fork` allows you to create a new session based on the failed one, enabling you to experiment with fixes without altering the original session's history.

How do I get machine-readable output from Atlas for my Phoenix CI scripts?

To get machine-readable output, invoke `atlas run` with the `--format json` flag. This will stream all Atlas events, including plans, tool calls, and proposed file changes (as unified diffs), as structured JSON to standard output. Your Phoenix CI scripts can then parse this JSON to automate review, validation, or subsequent actions.

Can Atlas help refactor Phoenix LiveView components in CI?

Absolutely. You can prompt Atlas to refactor LiveView components, for example, by asking it to move business logic out of a controller into a context function that returns an `ok` or `error` tuple. With appropriate tool permissions and `--format json` output, your CI can automate this refactoring, review the changes, and then run `mix test` to ensure functionality.

Run Atlas Headless in CI for Phoenix Projects in 2026

To run an Atlas session non-interactively in a Phoenix CI pipeline and retrieve machine-readable output, use the `atlas run` command with the `--format json` flag. This approach allows your pipeline to send a single prompt, stream events to stdout, and exit when the session completes, integrating direct with Phoenix's `mix test` and `mix format` workflows.

How to run Atlas non-interactively in Phoenix CI pipelines

Running Atlas non-interactively in a Phoenix CI pipeline is straightforward using the `atlas run` command, designed for headless operations. This mode sends a single prompt to Atlas, which then streams its events to standard output and exits once the session becomes idle, making it ideal for automated workflows in 2026.

Phoenix CI pipelines often require automated tools that can execute tasks without human intervention. Atlas supports this directly with `atlas run`. When invoked, Atlas processes a given prompt, such as 'refactor this LiveView component,' and streams its progress and results as events. For machine-readable output, crucial for subsequent pipeline steps, the `--format json` flag transforms the event stream into a structured JSON format. This allows other tools in your Phoenix pipeline to parse Atlas's actions, such as file edits or test results from `mix test (ExUnit)`, and react accordingly. For instance, a pipeline step could parse the JSON output to verify that Atlas successfully moved business logic from a controller into a context function, as often required in Phoenix applications.

Configuring Atlas for Phoenix-specific tasks in CI

Configuring Atlas for Phoenix-specific tasks in CI involves setting the model explicitly and pre-approving necessary tools, ensuring a smooth, non-interactive experience. By 2026, Atlas's integration with Phoenix's `mix.exs` and `lib/<app>_web` directories is robust, allowing it to understand your application's structure.

For Atlas to operate effectively in a headless Phoenix CI environment, several configurations are essential. First, explicitly set the model using the `provider/model` format, as required for GitHub paths, preventing any ambiguity. Second, pre-approve the tools Atlas needs to use via its permission configuration. In a headless run, there is no user to answer 'ask' prompts, so tools like `bash`, `read`, `edit`, and `todowrite` must be pre-approved to allow Atlas to interact with your Phoenix codebase. This setup enables Atlas to perform tasks such as reading your router pipelines, LiveView modules, contexts, and Ecto schemas with their changesets, or generating an Ecto migration, all without requiring manual confirmation. Atlas builds its code index using AST declarations via tree-sitter, ensuring it understands the specific structure of your Elixir and Phoenix files, not just blind line windows.

Ensuring safety and review for Atlas edits in Phoenix CI

Safety and review are paramount when Atlas makes edits in a Phoenix CI environment, even in headless mode. Atlas ensures this by permission-gating every tool call and computing a unified diff for every file edit, which can be reviewed before writing, providing a critical safeguard in 2026.

Atlas incorporates several mechanisms to ensure safety and facilitate review, even when running non-interactively in a Phoenix CI pipeline. Every Atlas tool call is permission-gated against allow, ask, and deny rules, preventing unauthorized actions. Before making any changes, Atlas drafts a plan in a read-only plan agent and, in interactive mode, asks for approval before switching to a build agent. In headless mode, pre-approving tools is key, but the safety net extends further: Atlas computes a unified diff for every proposed file edit and surfaces it. This diff can be captured from the `--format json` output, allowing a subsequent CI step to review the changes before they are committed or applied to the codebase. Furthermore, Atlas snapshots file changes as git patches, enabling easy diffing and rolling back of edits if necessary. This is crucial for tasks like having Atlas add LiveViewTest cases or modifying Ecto changesets, where precise control over changes is vital for Phoenix applications.

Resuming and forking Atlas sessions in Phoenix CI

Atlas offers robust capabilities for resuming or forking prior sessions, which is invaluable for iterative development or debugging in Phoenix CI pipelines. By using `--continue`, `--session`, or `--fork`, a pipeline step can build upon an earlier run, saving significant time and resources in 2026.

In complex Phoenix development workflows, it is often necessary to iterate on a task or debug a failed CI step. Atlas supports this through its session management features. The `--continue` flag allows Atlas to pick up where a previous session left off, using the same session ID. Alternatively, `--session <ID>` can be used to explicitly specify a session to resume. For scenarios where you want to branch off an existing session without modifying its history, the `--fork` option creates a new session based on the state of a prior one. This is particularly useful when Atlas is asked to perform a multi-step task, such as moving business logic out of a controller into a context function and then generating an Ecto migration. If an intermediate step fails or requires adjustment, you can resume or fork the session, make the necessary changes, and continue the process without starting from scratch. This flexibility ensures that your Phoenix CI pipeline remains efficient and adaptable.

Step by step

01Ensure your Phoenix application has a `mix.exs` file and a `lib/<app>_web` directory, as Atlas indexes code by AST declarations using tree-sitter to understand your project structure.
02Configure Atlas permissions to pre-approve necessary tools like `bash`, `read`, `edit`, and `todowrite` in your CI environment, as a headless run has no user to answer 'ask' prompts.
03Invoke `atlas run` with your desired prompt, for example, `atlas run 'Refactor this LiveView component to use a new context function.'`.
04Add the `--format json` flag to `atlas run` to stream machine-readable events to stdout, allowing subsequent CI steps to parse Atlas's actions and proposed changes.
05Explicitly set the model using the `provider/model` form, for example, `--model openai/gpt-4o`, to ensure Atlas uses the correct AI model for your Phoenix task.
06Capture the JSON output from `atlas run` and parse it in a subsequent CI step to review the unified diffs for any file edits, such as changes to Ecto schemas or LiveView modules.
07If Atlas proposes changes, such as adding LiveViewTest cases, integrate a step to run `mix test (ExUnit)` to validate the changes, potentially behind a permission prompt if interactive.
08After successful changes and tests, include a final CI step to run `mix format` to ensure all Elixir code adheres to your project's formatting standards.

Frequently asked questions

How does Atlas ensure safety when modifying Phoenix code in CI?: Atlas ensures safety by permission-gating every tool call against allow/deny rules. In headless CI, you pre-approve tools. Atlas also drafts plans in a read-only agent and computes a unified diff for every file edit, which can be extracted from the `--format json` output for review before any changes are written to your Phoenix project. It also snapshots changes as git patches for easy rollback.
Can Atlas generate Ecto migrations for my Phoenix application in CI?: Yes, Atlas can generate Ecto migrations. When running headless in CI, you would prompt Atlas to 'generate an Ecto migration for X' and ensure the `todowrite` tool is pre-approved. Atlas will then show you the `up` and `down` migration details in its output, which you can parse from the `--format json` stream for review before applying to your Phoenix database.
How does Atlas understand my Phoenix project's structure?: Atlas understands your Phoenix project's structure by indexing code using AST declarations via tree-sitter. This allows it to parse and comprehend `mix.exs`, `lib/<app>_web` directories, router pipelines, LiveView modules, contexts, and Ecto schemas with their changesets, providing a deep understanding beyond simple keyword matching.
What Phoenix commands can Atlas interact with in a CI pipeline?: Atlas can interact with core Phoenix commands like `mix test (ExUnit)` to run tests, `mix deps.get` for Hex package management, and `mix format` for code formatting. These interactions are permission-gated and can be triggered by Atlas through its `bash` tool, allowing it to validate or finalize changes within your CI pipeline.
Is it possible to debug a failed Atlas session in Phoenix CI?: Yes, Atlas supports debugging failed sessions. If an `atlas run` command fails in your Phoenix CI, you can use the `--continue` or `--session <ID>` flags to resume the exact session state. Alternatively, `--fork` allows you to create a new session based on the failed one, enabling you to experiment with fixes without altering the original session's history.
How do I get machine-readable output from Atlas for my Phoenix CI scripts?: To get machine-readable output, invoke `atlas run` with the `--format json` flag. This will stream all Atlas events, including plans, tool calls, and proposed file changes (as unified diffs), as structured JSON to standard output. Your Phoenix CI scripts can then parse this JSON to automate review, validation, or subsequent actions.
Can Atlas help refactor Phoenix LiveView components in CI?: Absolutely. You can prompt Atlas to refactor LiveView components, for example, by asking it to move business logic out of a controller into a context function that returns an `ok` or `error` tuple. With appropriate tool permissions and `--format json` output, your CI can automate this refactoring, review the changes, and then run `mix test` to ensure functionality.

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 Phoenix in 2026

Atlas is a terminal-native AI coding agent for Phoenix in 2026. It reads contexts, LiveView modules, and Ecto changesets, then runs mix test behind a prompt.

Rename a symbol across your Phoenix repo in 2026 with Atlas

Rename functions, classes, or constants across your Phoenix codebase with Atlas in 2026. Leverage mix test (ExUnit) and mix format for safe, precise refactoring.

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

Phoenix developers in 2026 use Atlas to direct upgrade dependencies and resolve compile and test failures. Atlas drives Hex, ExUnit, and mix format, ensuring a smooth transition for your Phoenix applications.

Write Unit Tests for Untested Phoenix Code with Atlas in 2026

Learn how Atlas helps Phoenix developers in 2026 add robust unit tests to untested modules, adhering to existing repo conventions and using `mix test (ExUnit)` for verification. Streamline your Phoenix testing workflow.

Run the Phoenix Test Suite and Triage Failures with Atlas in 2026

Efficiently triage Phoenix test failures in 2026 with Atlas. Turn a wall of `mix test` output into a prioritized list of distinct root causes, leveraging Atlas's AI for faster debugging and resolution.

Review a pull request in Phoenix with Atlas in 2026

In 2026, Atlas helps Phoenix developers review pull requests by providing deep context, checking Ecto changesets, LiveView modules, and running mix test (ExUnit) with precision.

Locate Phoenix Behavior with Atlas in 2026

Phoenix developers in 2026 can use Atlas to pinpoint exact file and symbol implementations for behaviors, leveraging semantic search, grep, and LSP tools across their Elixir and Phoenix codebase.

Browse this resource hub