glossary · Running it

Headless agent

definition

A headless agent is an AI coding or work agent run without its interactive interface, started by a script, a schedule or another system with a prompt and permissions set in advance, so it completes work with nobody at the keyboard.

in one line: An AI agent run with no interface and nobody watching.

in context

Where does a headless agent fit?

No keyboard. Still a process. In ConvOps, the agent asks for its step, does it, and waits at a gate until an explicit approval is given.

run startsschedule or dispatch
ask for the stepover MCP
do it, advance
approval gateapproval
receipttokens, cost
two ways to say it

What is a headless agent, in plain words?

Same idea at two depths: the plain version, then what the engine actually does.

Starting an agent without its interface takes one flag. Giving it a process, a place to stop, and a record is the hard part.

The workflow carries the process, not a longer prompt.

for engineers

Claude Code runs non-interactively with claude -p. In ConvOps, isolated runs use Claude Code or OpenCode.

The run reads its step over MCP. An approval gate holds the step until an explicit approval is given.

the longer answer

Why does a headless agent matter?

Most agent tools have an interactive mode, where a person types and approves, and a non-interactive mode for automation. Claude Code, for example, runs non-interactively with `claude -p "<prompt>"`, can return JSON or a stream of JSON events, and takes flags that pre-approve tools or set a permission mode, because nobody is there to answer a prompt. Other agent CLIs offer equivalent commands for scripts and CI.

Running an agent headless takes one flag. Running it well takes more. Three gaps appear as soon as the human leaves. Direction: a one-shot prompt has to carry the whole process, so long jobs drift or stop early. Judgment: anything that would have been a question to a person is either denied or decided by the model alone. Evidence: the result is whatever the run printed, unless something else kept a record.

Teams close those gaps with structure around the agent rather than longer prompts. The agent gets the process from a system it can ask, step by step. Decisions that need a person are routed to a checkpoint that waits. The record of what happened is kept outside the run, so it survives when the run ends.

in convops

How does a headless agent work in ConvOps?

In ConvOps, a headless agent is what runs inside an unattended execution. A schedule or a dispatch hands a task to an executor, for example an isolated Kubernetes run with Claude Code or OpenCode. The agent connects to ConvOps over MCP, asks for its current step, does it, and advances; the workflow, not the prompt, carries the process. When the run reaches a step that needs a person, the agent marks the task blocked and the work waits there. Each run records its session, retries, tokens and cost, and every change lands in the audit with the agent and the accountable user kept apart.

questions

What do people ask about a headless agent?

What is a headless agent in ConvOps?

A headless agent is an AI agent run without its interactive interface, started by a script, a schedule or another system with its prompt and permissions set in advance. In ConvOps it is what runs inside an unattended execution: the agent connects over MCP, asks for its current step, does it and advances, so the workflow carries the process instead of the prompt.

How do you run Claude Code headless?

Use print mode: claude -p with the prompt, --output-format json for scripts, and a permission mode or an allowed tools list, because nobody can answer prompts. ConvOps can start that run for you as an isolated Kubernetes run, with the workflow supplying each step. Cap a run you start yourself with --max-turns or --max-budget-usd.

What is the difference between a headless agent and unattended execution?

Headless describes how the agent runs, with no interactive interface, while unattended execution describes the whole setup around it. In ConvOps that setup is what starts the run, which task it works on, where it waits for people and what it records. The headless agent is the part inside; the executor, the workflow and the audit are the rest.

How does a headless agent ask a person for approval?

It cannot ask in a chat, so the process has to hold the question. In ConvOps the agent reaches a gated step or marks its task blocked, and the work waits there until a person answers from any client. Other work keeps moving while that task waits, and the run continues from the same step.

Who runs headless agents?

Teams that want work done on a schedule or after a trigger, with nobody watching: nightly maintenance, queued bug fixes, recurring reports. In ConvOps a headless agent runs inside an unattended execution and still follows the workflow step by step, so its owner reviews the gates and the record rather than every turn.