Headless mode (coding agent in scripts and CI)
Running a coding agent without an interactive session, from a script or pipeline, with the prompt, allowed tools and output format given as arguments.
In Claude Code headless mode is claude -p “prompt”, documented as running Claude Code programmatically; the same agent is available as an SDK. The output can be text or JSON, and the run ends when the task does. That makes a coding agent a building block for CI, pre-commit checks, batch migrations and self-healing CI.
With no one to approve prompts, everything has to be decided up front: which tools are allowed, which permission mode, which directory, and how much it may spend (cost cap). Headless runs are the steps inside a blueprint and the engine of background agents.
Sources
- Claude Code Docs: Run Claude Code programmatically code.claude.com
Related terms
- Self-healing CI (automated remediation): A pipeline where a coding agent reacts to a failed build, a flaky test or an alert by proposing a fix as a pull request that a person approves.
- Blueprint (deterministic and agentic steps): A workflow defined in code that mixes fixed steps, such as lint, build and git, with steps where an agent decides what to do.
- Background coding agent: A coding agent that runs in the cloud on its own, takes an issue or a task and comes back later with a pull request for review.
- CI/CD: Continuous integration and continuous delivery: every change is built and tested automatically and can be released at any time.
- Cost cap: A hard spending limit enforced by your code, per user, per day or per month.
