# Run Atlas headless in CI in Qwik with Atlas in 2026

> Run Atlas headless in Qwik CI by using `atlas run --format json` to get machine-readable output, integrating with your existing `pnpm` and `vitest` setup.

To run an Atlas session non-interactively in a Qwik CI pipeline and retrieve machine-readable output, invoke `atlas run` with the `--format json` flag, ensuring your `vite.config.ts` loads the `qwikCity` plugin. This approach integrates Atlas directly with your `pnpm` and `vitest` workflows, providing structured event streams for subsequent pipeline steps in 2026.

## Key takeaways

- Atlas integrates with Qwik's `pnpm`, `vitest`, and `prettier` toolchain for CI automation.
- Headless Atlas runs in CI provide machine-readable JSON output via `atlas run --format json`.
- Pre-approve Atlas tools like `bash`, `read`, `edit`, and `todowrite` for non-interactive Qwik workflows.
- Atlas understands Qwik's `$` boundaries, `component$`, `useSignal`, and `routeLoader$` definitions for intelligent code modifications.
- Resume or fork Atlas sessions in CI using `--continue`, `--session`, or `--fork` for iterative Qwik development.
- Atlas can build its code index with local Ollama embeddings, keeping Qwik code off third-party servers.

## How to run Atlas headless in Qwik CI for machine-readable output?

In 2026, to run Atlas headless in your Qwik CI pipeline and obtain machine-readable output, you must use the `atlas run` command with the `--format json` flag. This default non-interactive mode sends a single prompt, streams events to stdout, and exits when the session becomes idle, providing structured data for downstream automation.

Running Atlas non-interactively in a Qwik CI environment is achieved by invoking `atlas run` directly within your pipeline script. The crucial `--format json` flag ensures that Atlas streams raw event data to standard output, rather than human-readable prose. This structured JSON output is essential for subsequent pipeline steps that need to parse and act upon Atlas's actions, such as verifying changes or triggering further automation. For Atlas to effectively understand your Qwik project, ensure your `vite.config.ts` file correctly loads the `qwikCity` plugin, allowing Atlas to index your component definitions and routes. This setup integrates Atlas direct into your existing `pnpm`-driven Qwik development workflow.

## How to configure Atlas permissions for headless Qwik CI runs?

For headless Atlas runs in Qwik CI, you must pre-approve all necessary tools, as there are 0 opportunities for interactive prompts to answer `ask` rules. This ensures Atlas can execute its plan without interruption, using tools like `bash`, `read`, `edit`, and `todowrite` to modify your Qwik codebase in 2026.

When Atlas operates in a headless CI environment for your Qwik project, there is no human operator to respond to permission prompts. Therefore, it is critical to pre-approve all tools that Atlas might need to use through its permission configuration. This involves setting `allow` rules for tools such as `bash` for executing shell commands, `read` for accessing file content, `edit` for modifying Qwik component files or configuration, and `todowrite` for creating new files or updating existing ones. Without explicit pre-approval, any tool call that defaults to an `ask` rule would halt the headless session, causing your CI pipeline to fail. This proactive configuration guarantees that Atlas can autonomously perform its tasks, from adding a `routeAction$` to updating `useSignal` state within your Qwik application.

## How does Atlas understand Qwik code and optimize it in CI?

Atlas understands Qwik's unique architecture by indexing code with `tree-sitter` and AST declarations, recognizing `component$` definitions and `routeLoader$` exports across your `src/routes` in 2026. This deep understanding allows Atlas to suggest optimizations, such as moving eager work behind a `$` boundary for lazy chunking.

Atlas is specifically designed to comprehend the nuances of Qwik's resumability and its `$ boundary` concept. It builds its code index using AST declarations powered by `tree-sitter`, rather than relying on blind line windows. This enables Atlas to precisely identify and understand Qwik-specific constructs like `component$` definitions, `useSignal` and `useStore` state management, and `routeLoader$` exports within your `src/routes` directory. With this contextual awareness, Atlas can intelligently analyze your Qwik codebase and propose changes that align with Qwik's performance paradigms. For instance, it can suggest moving eager work behind a `$` boundary, allowing the Qwik optimizer to lazily chunk components and routes, thereby improving initial load times and overall application performance within your CI pipeline.

## How to integrate Atlas with Qwik's `vitest` and `prettier` in CI?

Integrating Atlas with Qwik's `vitest` and `prettier` in CI ensures code quality and test coverage, allowing Atlas to add a `routeAction$` with `zod$` validation and cover it with 1 or more `vitest` tests. This workflow ensures that any changes Atlas makes to your Qwik project are immediately validated and formatted correctly.

After Atlas proposes modifications to your Qwik codebase, such as adding a new `routeAction$` with `zod$` validation, the CI pipeline should incorporate steps to maintain code quality and correctness. Once the unified diff generated by Atlas is conceptually approved (or automatically approved based on pipeline rules), the next logical step is to run `pnpm prettier --write .` over the touched Qwik components. This ensures that all new or modified files adhere to your project's formatting standards. Subsequently, executing `pnpm vitest` is crucial to validate that Atlas's changes have not introduced regressions and that any new functionality, like the `routeAction$`, is adequately covered by tests. This integration ensures that Atlas's contributions are not only functional but also maintain the high standards of your Qwik project's `prettier` and `vitest` ecosystem.

## How to resume or fork Atlas Qwik CI sessions?

To manage complex Qwik development workflows in CI, Atlas allows you to resume or fork prior sessions using `--continue`, `--session`, or `--fork`, providing flexibility for iterative changes across multiple pipeline steps in 2026. This capability is vital for debugging or extending previous Atlas runs without starting from scratch.

In a continuous integration environment for Qwik projects, it's often necessary to build upon or re-evaluate previous Atlas sessions. Atlas provides specific flags for this purpose: `--continue`, `--session <session_id>`, and `--fork <session_id>`. The `--continue` flag allows a pipeline step to pick up exactly where a previous Atlas run left off, preserving context and progress. If you need to reference a specific prior session, perhaps from a different branch or an earlier CI job, you can use `--session` with its unique identifier. The `--fork` option is particularly useful when you want to start a new, independent Atlas session based on the state of a previous one, allowing for parallel exploration or alternative solutions without altering the original session's history. These features enable robust, iterative development within your Qwik CI pipelines, ensuring that Atlas can adapt to evolving project requirements and complex problem-solving scenarios.

## Steps

1. Ensure your Qwik project's `vite.config.ts` loads the `qwikCity` plugin for Atlas to correctly index your `src/routes` and component definitions.
2. Configure Atlas permissions to `allow` necessary tools like `bash`, `read`, `edit`, and `todowrite` in your headless CI environment, as there are no interactive prompts.
3. Invoke `atlas run` within your CI script, passing your prompt as an argument and including `--format json` to receive machine-readable event streams.
4. Explicitly set the model using the `provider/model` form, for example, `atlas run --model github/copilot-gpt-4 --format json 'Add a new routeAction$ to src/routes/index.tsx'`.
5. In a subsequent CI pipeline step, parse the JSON event stream from `atlas run`'s stdout to process Atlas's actions and outputs programmatically.
6. Review and approve the unified diff generated by Atlas (either manually or via automated checks) before writing changes to your Qwik codebase.
7. After changes are applied, run `pnpm prettier --write .` across your Qwik project to ensure all touched components adhere to formatting standards.
8. Execute `pnpm vitest` to run your Qwik project's tests, verifying that Atlas's modifications maintain functionality and test coverage.

## FAQ

### How do I run Atlas non-interactively in a Qwik CI pipeline?

Invoke `atlas run` with your prompt and the `--format json` flag. This ensures machine-readable output for subsequent pipeline steps, integrating with your Qwik project's `pnpm` setup.

### What Qwik-specific files does Atlas understand for code indexing?

Atlas indexes Qwik code by AST declarations using `tree-sitter`, understanding `component$` definitions, `useSignal` and `useStore` state, and `routeLoader$` exports under `src/routes`.

### How do I handle tool permissions for Atlas in a headless Qwik CI environment?

Pre-approve necessary tools like `bash`, `read`, `edit`, and `todowrite` in Atlas's permission configuration. Headless runs have no interactive prompt to answer `ask` rules.

### Can Atlas help optimize Qwik's lazy loading in CI?

Yes, Atlas can identify eager work and suggest moving it behind a `$` boundary, allowing the Qwik optimizer to lazily chunk components and routes for better performance.

### How can I ensure code quality after Atlas edits Qwik components in CI?

After Atlas proposes edits and you approve the diff, integrate `pnpm prettier --write .` into your CI pipeline to format touched Qwik components, and run `pnpm vitest` to validate functionality.

### What if an Atlas session needs to continue from a previous CI run in Qwik?

Use `atlas run --continue`, `--session <session_id>`, or `--fork <session_id>` to resume or build upon a prior Atlas session, enabling iterative development within your Qwik CI pipeline.

### Does Atlas support local embedding models for Qwik code?

Yes, Atlas can build its code index with local Ollama embeddings, ensuring your Qwik project's code remains off third-party servers while still benefiting from semantic retrieval.

---

Canonical HTML: https://runatlas.sh/resources/stacks/run-atlas-headless-in-ci-in-qwik
Source of truth: aeo_pages row `/resources/stacks/run-atlas-headless-in-ci-in-qwik` (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.