Headless & Daemon

In addition to the interactive TUI, AtomCode offers two non-interactive modes: -p headless on the CLI for scripts and CI, and atomcode-daemon — an HTTP + SSE API service that any client can drive.

Headless CLI mode

Add -p / --prompt to atomcode to execute a single task and write the reply straight to stdout (like Claude Code's -p mode):

atomcode -p "give me a brief overview of this repo"

By default only the AI's final reply text goes to stdout — handy for piping. Tool calls and token usage are kept out of stdout.

Common headless flags

Flag	Description
`-p, --prompt TEXT`	Task description to run
`--prompt-file PATH`	Read the prompt from a file (good for long input; mutually exclusive with `-p`)
`-v, --verbose`	Send tool-call logs, token usage, and turn summaries to stderr; stdout is untouched
`--max-turns N`	Hard cap of N LLM calls — keeps the agent from running away. No cap by default
`--disable-tools LIST`	Disable specific tools, e.g. `bash,web_fetch`. Disabled tools are absent from the schema list so the model won't try to call them
`-C, --dir PATH`	Working directory; defaults to the current directory
`--provider / --model`	Temporarily override provider or model
`--no-telemetry`	Disable telemetry for this invocation

Examples

# Generate a project summary and write it to a README draft
atomcode -p "summarise the project structure and produce a README draft" > README.draft.md

# Auto-fix lint errors in CI
atomcode -p "run pnpm lint and fix every error; don't modify test files" \
         --max-turns 30 --disable-tools web_search,web_fetch

# Read the prompt from a file
atomcode --prompt-file task.md -v 2> run.log

# Local Ollama, completely offline
atomcode -p "explain this code" --provider local --model qwen2.5:14b

Exit codes

0 — normal completion
Non-zero — an error occurred. The error message goes to stderr; details are in the -v log

Note: permission model

Headless mode has no interactive permission dialog. In the current implementation, bash calls that would prompt are auto-approved, and the reason is written to stderr:

[headless] auto-approved bash: <reason>

Other tools that would prompt for confirmation (edit, write, high-risk paths for web_fetch, …) are auto-denied:

[approval-denied] tool=<name> reason=<reason>

When [approval-denied] fires, the process exits with a non-zero code. If you don't want shell execution in CI, add --disable-tools bash explicitly to remove it from the tool list entirely.

atomcode-daemon

atomcode-daemon is a standalone binary that re-uses atomcode-core. It exposes an HTTP + Server-Sent Events API for web frontends, IDE plugins, and editor extensions. The official AtomCode VS Code extension and the AtomCode Air desktop app both connect through it.

Launching

# Recommended: launch via the CLI subcommand — it invokes the sibling atomcode-daemon binary
atomcode daemon

# Pick a port and client identity (drives telemetry segmentation)
atomcode daemon --port 13456 --client vscode

# You can also invoke the daemon binary directly (more options)
atomcode-daemon --host 127.0.0.1 --port 13456 \
                --client atomcode-air --idle-timeout 1800

The daemon reads the same ~/.atomcode/config.toml as the CLI — login state, provider config, and session history are all shared.

Launch flags

Flag	Description
`--host HOST`	Listen address; default `127.0.0.1`. Non-loopback addresses trigger a warning (the daemon has no auth and must not be exposed publicly)
`--port PORT`	Listen port; default `13456`
`--client NAME`	Client identity; currently `vscode` / `atomcode-air` are recognised, anything else is treated as a generic IDE. Affects telemetry tagging and some behaviour
`--idle-timeout SECS`	Idle timeout in seconds. Default 1800 (30 min); `0` disables it; non-zero values are clamped to a minimum of 60. Also accepts the env var `ATOMCODE_DAEMON_IDLE_TIMEOUT`
`--no-telemetry`	Disable telemetry for this process

Security

The daemon has no built-in auth and binds 127.0.0.1 by default. Never expose it to the public internet or to your LAN directly — callers gain full execution rights for every tool on your machine (including bash, write, edit). For remote access, terminate at a reverse proxy that handles auth / TLS / origin restrictions.

Endpoint overview

All endpoints are registered in crates/atomcode-daemon/src/main.rs, grouped below.

Health & lifecycle

Method + Path	Description
`GET /health`	Health check
`POST /shutdown`	Shut the daemon down gracefully (used when the client exits)

Sessions / projects

Method + Path	Description
`GET /sessions`	List all sessions
`POST /sessions`	Create a new session
`GET /sessions/search`	Search history by keyword
`GET /project`	Project state for the current working directory
`POST /cd`	Switch working directory
`GET /projects`	List every project that has had sessions
`GET /projects/:hash/sessions`	Sessions under a specific project
`GET /projects/:hash/sessions/:id`	Session details
`DELETE /projects/:hash/sessions/:id`	Delete a session
`PATCH /projects/:hash/sessions/:id/rename`	Rename a session

Chat & models

Method + Path	Description
`GET /models`	List available providers / models
`POST /chat`	Send a prompt; returns an SSE stream
`POST /chat/stop`	Stop an in-progress `/chat`

Config / providers

Method + Path	Description
`GET /config`	Read the current `config.toml`
`POST /config/reload`	Reload `config.toml`
`GET /providers`	List all providers
`POST /providers`	Add a provider
`PATCH /providers/:name`	Update a provider
`DELETE /providers/:name`	Delete a provider
`POST /providers/:name/default`	Set this provider as the default
`PATCH /providers/:name/thinking`	Toggle / adjust the provider's thinking mode

MCP

Method + Path	Description
`GET /mcp/status`	MCP server connection status
`POST /mcp/reload`	Reload `.mcp.json`

Auth / CodingPlan

Method + Path	Description
`GET /auth/status`	Current login status
`POST /auth/login/start`	Kick off AtomGit OAuth login
`POST /auth/login/:login_id/poll`	Poll for the login result
`DELETE /auth/login/:login_id`	Cancel an in-flight login
`POST /auth/logout`	Log out
`POST /codingplan/setup`	Claim CodingPlan and write the provider config (equivalent to the CLI `atomcode login`; `atomcode codingplan` is kept as a hidden alias)

SSE streaming chat

The SSE stream returned by POST /chat includes events for AI text deltas, reasoning deltas, tool-call batches (start / end), token stats, errors, and more. The full event schema is the TurnEvent definition in crates/atomcode-core/src/turn/event.rs.

Frontends can consume the stream with the native EventSource or any SSE client library.

CORS

The daemon configures CORS to allow only loopback origins: the host must be localhost, 127.0.0.1, or ::1 (any port, any protocol). Other origins are rejected. This is defence in depth alongside the default --host 127.0.0.1 bind — even if someone tries DNS rebinding to forge a request, the CORS layer still blocks it.

Typical uses

Editor plugins / IDE extensions (VS Code, JetBrains)
Desktop GUIs (e.g. the official AtomCode Air)
Self-hosted local web UIs (move the terminal agent into the browser)
Local script orchestration: dispatch multiple tasks over HTTP, share session history

Next steps

Skills — codify workflows into commands; particularly useful with headless
FAQ — common headless / daemon pitfalls