How do I get machine-readable output from Atlas in a pipeline?

Pass --format json to `atlas run`. Atlas then streams raw events rather than prose, so a downstream TypeScript step can parse the event stream and decide what to do next instead of scraping human-readable text.

Why does my headless Atlas run fail on a permission prompt?

A headless run has nobody to answer an ask prompt. Pre-approve the tools the job needs through the permission config, including the bash commands for pnpm and vitest. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs.

Does Atlas need the model specified in CI?

Yes. Set the model explicitly, because the GitHub path requires provider/model form and rejects anything else. Pinning it next to the Node and pnpm versions keeps the run reproducible.

Can an Atlas CI job resume a previous session?

Yes. `atlas run` supports --continue, --session, and --fork, so a job that hit a runner time limit mid-refactor can be resumed rather than restarted from an empty context.

Can Atlas run vitest as part of a headless job?

Atlas uses bash, read, edit, and todowrite in a headless run, so it can execute vitest once the command is allowed in your permission config. Ending the run with vitest is what makes the pipeline fail on a broken TypeScript change.

How do I run an Atlas slash command from a pipeline?

`atlas run` supports --command for slash-command execution, so a repo that has standardized on a slash command for review or refactoring can invoke that command directly instead of restating the prompt in the workflow file.

How do I review what Atlas changed in a headless run?

Atlas computes a unified diff for every file edit and snapshots file changes as git patches, so the changes a CI job made are inspectable as patches and can be diffed and rolled back afterwards.

Run Atlas Headless in CI in TypeScript with Atlas (2026)

To run Atlas headless in CI on a TypeScript repo, use `atlas run`. Its default mode is non-interactive: it sends a single prompt, streams events to stdout, and exits when the session goes idle, which is exactly the shape a pipeline step needs. Pass --format json when a later step has to parse the event stream rather than read prose. Set the model explicitly, because the GitHub path requires provider/model form and rejects anything else. Pre-approve the tools the job needs through the permission config, since a headless run has nobody to answer an ask prompt, and that is what lets Atlas actually run pnpm install and vitest against your tsconfig.json. Use --continue, --session, or --fork to resume or replay a run.

How do you run Atlas headless in a TypeScript CI pipeline?

Atlas runs headless through `atlas run`, invoked with the prompt as an argument. The default mode is non-interactive: one prompt in, an event stream on stdout, and an exit when the session goes idle. For a TypeScript repo in 2026 that means a CI step can ask Atlas to tighten types and then run vitest without a human in the loop.

`atlas run` is built for this. A pipeline step looks like a single invocation with the prompt as an argument, and the process exits on its own when the session goes idle, so the job does not hang waiting for a TUI that never appears. The TypeScript specifics matter here: point the run at a project with a tsconfig.json, let Atlas read your type definitions, path aliases, and strictness settings, and the prompt can be as concrete as remove every `any` in src/api and keep vitest green. Atlas uses bash, read, edit, and todowrite in a headless run, which is the tool set a CI job actually needs to change code and prove it.

What does --format json do in an Atlas CI run?

Passing --format json to atlas run makes Atlas stream raw events rather than prose, which is step 2 of the 5 step CI workflow and exactly what a TypeScript pipeline needs when a later step must parse the output. A job can pipe the event stream into a Node script and decide whether to open a pull request from structured data.

The distinction between prose and events is the difference between a CI step you can build on and one you can only read. With --format json the event stream is machine-readable, so a downstream step written in TypeScript can consume it with the same tooling as the rest of the repo: parse it, type it, and act on it. Without --format json you get the human-facing output, which is fine when a developer is going to read the job log and nothing else depends on it. `atlas run` also supports --command for slash-command execution, so a repo that has standardized on a slash command for its review flow can invoke that command directly from the pipeline rather than restating the prompt.

Why must the model be set explicitly for Atlas in CI?

Atlas requires the model to be set explicitly in a CI run, step 3 of the workflow, and the GitHub path requires provider/model form and rejects anything else. A TypeScript job that omits the provider prefix fails at startup in 2026 rather than silently running on a default, which is what you want in a reproducible pipeline.

Reproducibility is the whole reason a headless run is stricter than an interactive one. Interactively, Atlas lets you switch the active model and provider on the fly with favorites and recents, which is convenient at a terminal and unacceptable in CI, where a run from six months ago must be explainable. So the GitHub path insists on provider/model form. Pin it in the workflow file next to the pnpm version and the Node version, and the Atlas step becomes as deterministic as the vitest step next to it. A rejection at startup is cheap. A pipeline that quietly changed models between two runs and produced two different diffs is not.

How do permissions work when Atlas runs headless in CI?

Pre-approve the tools the job needs through the Atlas permission config, because a headless run has nobody to answer an ask prompt. Every Atlas tool call is gated against 3 rule types, allow, ask, and deny, so a TypeScript CI job that has not allowed bash will stall or fail rather than run pnpm install.

The permission system does not relax in CI, which is the correct default and the most common source of a first failed run. Decide up front what the job may do. A job that only reviews needs read, grep, and maybe bash for a read-only command. A job that fixes types needs edit as well, plus the bash commands to run pnpm and vitest. Write those into the allow rules and leave everything else denied, and the blast radius of a headless Atlas run is bounded by config rather than by trust. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, and in CI that approval comes from your allow rules rather than a keypress. Atlas snapshots file changes as git patches, so the job's changes are inspectable as patches afterwards.

How do you resume or replay an Atlas CI run on a TypeScript repo?

`atlas run` supports --continue, --session, and --fork, so a TypeScript pipeline step can be replayed or resumed. A job that ran vitest, found 4 failing type tests, and hit its time limit can be continued in a follow-up step rather than restarted from an empty context.

Resumption is what makes multi-step CI work with an agent practical. Use --continue to pick up the most recent session, --session to target a specific one, and --fork when you want to branch from an earlier run without disturbing it. In a TypeScript monorepo this is how a long refactor gets split: one job removes `any` from one package and leaves a todowrite list, the next job resumes the session and moves to the next package, and each job is short enough to fit inside the runner's limits. Because Atlas snapshots file changes as git patches so edits can be diffed and rolled back, the intermediate state of a resumed run is a reviewable artifact rather than a mystery.

Step by step

01Run atlas in a project with a tsconfig.json so Atlas can read your type definitions, path aliases, and strictness settings.
02Invoke `atlas run` with the prompt as an argument; the default mode sends one prompt and exits when the session goes idle.
03Pass --format json when a later pipeline step needs to parse the event stream rather than read prose.
04Set the model explicitly in provider/model form, because the GitHub path requires provider/model form and rejects anything else.
05Pre-approve the tools the job needs through the permission config, because a headless run has nobody to answer an ask prompt.
06Allow the bash commands the job actually needs, such as pnpm install and vitest, and leave everything else denied.
07Use --command when the repo has standardized on a slash command instead of an ad hoc prompt.
08Have the run finish by executing vitest through the bash tool so the pipeline fails on a broken TypeScript change rather than merging it.
09Run prettier on the touched files so the headless diff matches the repo's formatting.
10Resume or fork a prior session with --continue, --session, or --fork when a job needs to build on an earlier run.

Frequently asked questions

How do I run an AI coding agent in CI on a TypeScript repo?: Use `atlas run` with the prompt as an argument. Its default mode is non-interactive: it sends a single prompt, streams events to stdout, and exits when the session goes idle, so a pipeline step does not hang waiting for a terminal UI.
How do I get machine-readable output from Atlas in a pipeline?: Pass --format json to `atlas run`. Atlas then streams raw events rather than prose, so a downstream TypeScript step can parse the event stream and decide what to do next instead of scraping human-readable text.
Why does my headless Atlas run fail on a permission prompt?: A headless run has nobody to answer an ask prompt. Pre-approve the tools the job needs through the permission config, including the bash commands for pnpm and vitest. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs.
Does Atlas need the model specified in CI?: Yes. Set the model explicitly, because the GitHub path requires provider/model form and rejects anything else. Pinning it next to the Node and pnpm versions keeps the run reproducible.
Can an Atlas CI job resume a previous session?: Yes. `atlas run` supports --continue, --session, and --fork, so a job that hit a runner time limit mid-refactor can be resumed rather than restarted from an empty context.
Can Atlas run vitest as part of a headless job?: Atlas uses bash, read, edit, and todowrite in a headless run, so it can execute vitest once the command is allowed in your permission config. Ending the run with vitest is what makes the pipeline fail on a broken TypeScript change.
How do I run an Atlas slash command from a pipeline?: `atlas run` supports --command for slash-command execution, so a repo that has standardized on a slash command for review or refactoring can invoke that command directly instead of restating the prompt in the workflow file.
How do I review what Atlas changed in a headless run?: Atlas computes a unified diff for every file edit and snapshots file changes as git patches, so the changes a CI job made are inspectable as patches and can be diffed and rolled back afterwards.

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

In 2026, TypeScript developers leverage Atlas, the terminal-native AI coding agent, to enhance productivity. Atlas understands your types, ensures code quality, and offers robust safety features.

Migrate a Deprecated API Across Every TypeScript Callsite With Atlas (2026)

Move a TypeScript codebase off a deprecated function without missing a caller: Atlas enumerates with lsp findReferences, tracks with todowrite, patches with apply_patch.

Refactor a legacy module in TypeScript with Atlas (2026)

Refactor a legacy TypeScript module in 2026 with Atlas: map callsites with lsp findReferences, restructure with apply_patch, and prove behavior with vitest.

Trace a runtime bug from a stack trace in TypeScript with Atlas (2026)

Go from a production TypeScript stack trace to the responsible line with Atlas in 2026: read each frame at its offset, grep the error string, and pin it with vitest.

Plan a Multi-File Change Before Editing in TypeScript with Atlas (2026)

Atlas plans multi-file TypeScript changes in a read-only plan agent that denies every edit tool, so you approve the design before pnpm, vitest, or prettier ever run.

Diagnose a hanging or long-running command in TypeScript with Atlas (2026)

Is your pnpm build slow or blocked on stdin? Atlas's bash timeout message tells you which, in 2026, and how to unstick vitest, tsc, and prettier runs that never finish.

Locate Where a Behavior Is Implemented in TypeScript with Atlas in 2026

Find the exact TypeScript file and symbol behind a behavior in 2026. Atlas combines codebase_search, grep through ripgrep, and the lsp tool's findReferences.

Browse this resource hub