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. The agent asks for its step, does it, and waits where a person must decide.

run startsschedule or dispatch

ask for the stepover MCP

do it, advance

needs a personapproval

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 is easy. 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. A step needing a person leaves the task blocked until someone acts.

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 is easy. Running it well is not. 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?

How do you run Claude Code headless?

Use print mode, claude -p with the prompt, add --output-format json for scripts, set a permission mode or an allowed tools list because nobody can answer prompts, and cap the run 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. Unattended execution describes the whole setup around it: what starts the run, what it works on, where it waits for people and what it records.

How does a headless agent ask a person for approval?

It cannot ask in a chat. In ConvOps it reaches a gated step or marks its task blocked, and the work waits there until a person answers from any client.

What does a headless agent connect to?

Unattended executionNobody at the keyboard. People join only at gates.Agent executorWhich agent runs the work, and where.Agent instruction file (CLAUDE.md, AGENTS.md)CLAUDE.md or AGENTS.md: what every session reads first.

Unattended execution Agent executor Runs in ConvOps Run Claude Code unattended on Kubernetes

your next step

Teach it once. Then let it run.

on your ownStart freeConnect your AI tool in one line. Nothing to install.with your teamBook a demoWe show ConvOps on your team's real work.keep readingAgent instruction file (CLAUDE.md, AGENTS.md)CLAUDE.md or AGENTS.md: what every session reads first.