Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Headless runs

fontaine -p "task" runs one task without a terminal and exits. It is the surface the CI integration tests, the eval runner and any external consumer drive, so its output is a versioned contract: a checked-in JSON Schema describes every object it prints. A Rust program can run the same agent in process and read these objects as typed events; see Embedding in a Rust program.

fontaine -p "explain what main.rs does"
fontaine -p --output-format json "list the FIXME comments" | jq .result
echo "summarize the build" | fontaine -p

Command line

-p / --print is a flag and the prompt is a positional argument, as in Claude Code. Without a prompt argument the prompt is read from stdin; if stdin is a terminal the run fails at once with a usage error (exit 2). With one, text piped on stdin is appended after the prompt on a new line, as in Claude Code; empty piped input leaves the prompt unchanged. If a pipe sends no data within 3 seconds, a warning goes to stderr and the run proceeds with the prompt argument alone; redirect < /dev/null to skip the wait.

InvocationMeaning
fontaineStarts the terminal UI; see The terminal UI.
fontaine -p "task"Runs the task headless and prints the result on stdout.
fontaine auto-mode defaults|config|critique|setup [--format text|json]Shows the rules the guardian judges against, or (setup [--no-model] [--no-composition]) collects the project’s environment facts for it and offers the guardian composition; starts no session. See Inspecting the rules. A prompt that is exactly auto-mode runs this subcommand; write fontaine -p -- auto-mode for a literal prompt.
fontaine models [<account>] [--format=text|json]Prints the models each configured account offers; starts no session. See Model discovery. A prompt that is exactly models runs this subcommand; write fontaine -p -- models for a literal prompt.
fontaine doctor [--format=text|json] [--connect=yes|no] [--all]Checks the settings layers, trust, models, MCP servers, extensions and auto memory, and exits 1 when a check fails; starts no session. See fontaine doctor. A prompt that is exactly doctor runs this subcommand; write fontaine -p -- doctor for a literal prompt.
fontaine mcp add|list|get|removeDeclares, lists, shows and removes MCP servers in the local, project (.mcp.json) or user scope; starts no session, and list and get start only the servers fontaine doctor would. A prompt that is exactly mcp runs this subcommand; write fontaine -p -- mcp for a literal prompt.
fontaine update [--rollback]Replaces the installed binary with the newest build on the channel it was installed from, prints one line and exits; starts no session. Exits 3 for an install that cannot update itself, 4 for a network failure and 5 for a verification failure. See Updating. A prompt that is exactly update runs this subcommand; write fontaine -p -- update for a literal prompt. With --rollback (Linux and macOS only) it restores the version that was installed before the last update, or says there is nothing to restore; it exits 1 on Windows.
--permission-mode <manual|acceptEdits|auto|dontAsk|afk>Session mode, overriding [permissions] default_mode. There is no bypass mode. A headless run starts in manual unless one of the two says otherwise; auto sends calls nothing pre-approved to the guardian.
--in-containerStates that the process runs inside a container; with [guardian] profile = "minimal" it lets the minimal guardian load when a runtime probe agrees. See The guardian.
--afkRuns in AFK mode, which decides as auto does (the init event reports afk) and is shorthand for --permission-mode afk: the same would-prompt denials, with guidance to finish the allowed work or stop and report, the temperature stop, and an afk object in result.
--afk-temperature-ceiling <n>The temperature at which an AFK run stops, a finite number above zero; overrides [afk] temperature_ceiling. A project file can only lower it.
--model <account>/<model>Overrides [model] model. A role name or a comma-separated list is accepted too, and becomes the run’s preference list. See Configuration.
--effort <level>The main agent’s reasoning effort, off, low, medium, high or max, overriding [model] effort. See Configuration.
--output-format text|json|stream-jsontext prints the final answer, json one result object, stream-json one JSON object per line.
--input-format text|stream-jsonstream-json reads user messages as JSON lines on stdin. A prompt argument together with stream-json input is a usage error. A text prompt can pair with the session’s previous answer (for example on --continue or --resume) for the guardian’s agent_message_before_reply; stream-json lines and /goal lines never do.
--include-partial-messagesWith stream-json output, also emits assistant_delta events.
--max-turns <n>Stops each turn after n model calls with error_max_turns (exit code 1). Without it a turn has no call limit.
--max-budget-usd <x>Stops the run once the session’s spend, the main model plus the guardian and subagents, exceeds x with error_max_budget_usd (exit code 1). A model with no known price makes this a usage error (exit code 2); a priced databricks model has one, so the flag works there, against a list-price estimate of the session’s spend.
--on-usage-limit=wait|exitWhat the run does when an account’s usage window is spent: wait (the default) holds the whole run until the window resets, exit ends it at once with exit code 3. Overrides [headless] on_usage_limit.
--max-usage-wait <duration>The longest the run waits for a spent usage window, such as 90m or 6h (a bare number is seconds); default 6 hours. Overrides [headless] max_usage_wait_secs. A zero or unreadable value is a usage error (exit code 2).
--json-schema <schema>An inline JSON Schema the final answer must follow. The parsed answer is returned in result.structured_output. A schema that is not a JSON object is a usage error.
--allowed-tools <rule>Adds an allow rule in Tool(specifier) syntax for this session, such as shell(npm test). Repeatable. Loaded as the CLI scope’s [permissions] allow; an invalid rule is a usage error.
--disallowed-tools <rule>Adds a deny rule for this session, such as read(.env). Repeatable. See Permissions.
--cd <dir>, -C <dir>Starts in this directory instead of the launch directory. It becomes the project directory: project settings, trust, workspace root and session identity come from it. Fontaine changes its own working directory to it, so relative --settings, --add-dir and --debug-file values and spawned processes resolve against it as if launched there. A directory that does not exist is a usage error (exit code 2).
--add-dir <path>Adds a directory to the workspace roots. Repeatable. See Tools.
--session-id <uuid>Uses this UUID as the session id. A value that is not a UUID is a usage error (exit code 2), and so is an id whose session directory already exists. With --continue or --resume it is accepted only together with --fork-session, where it names the copy; otherwise it is a usage error.
--continue, -cReopens the most recently updated session that was started in the project directory (the launch directory, or --cd); starts a fresh session when there is none.
--resume <id-or-name>, -r <id-or-name>Reopens the session with this id, or else the session started in the project directory (the launch directory, or --cd) that has this name (compared without regard to case). A value that matches no session is a usage error (exit code 2), and so is a name carried by several sessions: the error lists their ids. The value is required, so fontaine -p --resume <id> "task" reads task as the prompt.
--name <name>, -n <name>Names the session being started, so --resume can find it by name. With --fork-session it names the copy; with --continue or --resume alone it renames the session reopened. A name is 1 to 80 characters with no control characters; anything else is a usage error. A fork the flag does not name is called the source’s name followed by (branch) when the source has one, so a name finds one session.
--fork-sessionWith --continue or --resume, starts a new session that is a copy of the one that would have been reopened. Alone it is a usage error.
--system-prompt <text>Replaces the base system prompt.
--append-system-prompt <text>Appends to the system prompt after every other layer.
--settings <file>A settings file layered over the others (CLI scope).
--debug-file <path>Writes diagnostics to a local, owner-only file.

When the main model’s list runs out of quota on an entry, the run continues on the next one and prints a warning on stderr, such as fontaine: warning: main: anthropic/x is out of quota (rate_limit); continuing on kimi/y. If every entry fails, the result is an error_during_execution whose error ends with every model in main failed. With --max-budget-usd, entries with no known price are skipped.

A headless run on a claude-subscription account needs the Claude CLI signed in beforehand (claude auth login --claudeai); it never starts a login. A CLI that is not signed in exits 1 before any turn with account `claude` is not signed in; run `claude auth login --claudeai`, then retry (the command carries the account’s claude_config_dir as CLAUDE_CONFIG_DIR=... when it sets one). If a pinned guardian model is on another account that is signed out, a run in auto or afk mode exits 1 the same way, naming the guardian’s account, before the session starts and before any guardian call; manual and acceptEdits runs are not stopped. The guardian model also backs the scanner, the goal evaluator and prompt hooks in every mode; in manual and acceptEdits those behave as before, pausing or failing with the unavailable reason. A missing or old CLI, a login that is not a Max or Ultra subscription, or a conflicting environment variable exits 1 before any turn, and a credit-billed model at startup exits 2, with the corrective text on stderr; a plan limit is reported without a retry (unless the account sits in a model list with a next entry, which the run continues on), and a stream cut short or a CLI silent for 180 seconds is retried with backoff (see [retry]). Ending the run stops the CLI and its descendants. Usage lines carry token counts and no cost, and --max-budget-usd is a usage error (exit code 2). See Claude subscription.

A headless run takes its credentials from api_key_env or from a credentials.toml already in the data directory; it never prompts. Store them in the terminal UI with /login, or provision the file in CI. See Credentials.

Enabled plugins load in a headless run exactly as they do in the terminal UI: their hooks, MCP servers and skill ! commands run without the workspace-trust gate, because install approved them.

A headless run loads a repository’s hooks, MCP servers and skill commands without asking, as Claude Code’s -p does, unless [headless] require_trust = true and the workspace was not trusted in the terminal UI: then it skips them all, as the terminal UI does after “Don’t trust”, and prints one line on stderr saying so. The setting is read from your user file or --settings only. The init event’s project_executables reports whether they loaded.

A headless run never asks about skill trust. A plugin skill that is untrusted, or that changed since you trusted it, lends nothing; invoking one that declares allowed-tools warns once on stderr. Trust skills with fontaine plugin trust <name> ahead of time, and re-trust after an update that changed one.

The budget is checked between model calls, and before each goal evaluation and goal turn. A call that pushes the spend over the cap stops the run before its tool calls execute; an answer that was already complete is kept. The spend includes the guardian’s calls, the goal evaluator’s calls and the subagents’ model calls.

Scheduled prompts

A headless run exits after its answer, so a scheduled task could never fire: the scheduling tools (cron_create, cron_jobs, cron_delete, schedule_wakeup) are not registered and /loop does not exist. See Scheduled prompts for the terminal UI.

Goals

-p "/goal <condition>" runs a goal to its end in one invocation. It is the only slash command headless understands, and only as a message that starts with /goal followed by a space or the end of the text. The first turn works on the condition; after each turn the evaluator (the guardian’s model) judges it, and not met runs another turn, until the condition is met or impossible, or the goal pauses on [goal] max_turns, [goal] max_cost_usd, [goal] max_tokens, [goal] max_duration_secs, --max-turns, --max-budget-usd, the no-progress cap, an evaluator that finds the goal is waiting for you (the pause reads it is waiting for you (<reason>)), a failed turn or an evaluator that gave no verdict. The spend of the evaluator counts toward --max-budget-usd and total_cost_usd.

While a goal runs, the run waits for background jobs as well as subagents, and the goal is evaluated once they have ended. After [goal] checkin_minutes of waiting (30 by default) it starts a check-in turn that asks the model to look at the work, and later ones follow after 1 hour and then every 2 hours. Nobody is there to send the next prompt, so after the third check-in the goal pauses when another falls due (background work is still running and the run cannot wait on it) and the run exits 1. With checkin_minutes = 0 the run does not wait for jobs: a goal still waiting on them pauses the same way, at once.

-p "/goal" prints the goal’s status and -p "/goal clear" removes it; neither calls a model, and the result has num_turns 0. A goal restored by --continue or --resume is evaluated after the message’s turn ends, whatever the message was.

With stream-json, each evaluation prints a goal event, and the result gains a goal object (see Output). The exit code is 0 only when the goal ended met; a goal that ended impossible or paused exits 1, with subtype unchanged. With --output-format text, such a run prints fontaine: goal impossible: <reason> or fontaine: goal paused: <why> on stderr instead of the last answer.

Sessions

Each run is a session, named by a UUID: the one given with --session-id, or a fresh one. Its files live in <data dir>/sessions/<session id>/, created readable by the current user only. The conversation, the task list (todos.json) and the goal (goal.json) are kept there between turns, and the conversation is compacted by a summarizing call when it outgrows the model’s context window less a reserve, or earlier when [context] autocompact_window is set (only for a model the catalog lists, a derived or mapped model counting as listed, and, without that setting, only when its window is known; the summarizing call counts toward the spend and the model-call count). A compaction that cannot finish leaves the conversation as it was, prints a warning on stderr and does not stop the run.

A separate, append-only ledger beside it records what the user said, verbatim, what the harness did, and the tail of the agent’s final answer. Compaction never touches it. See Architecture.

Continuing a session

--continue and --resume <id-or-name> reopen a session: the conversation and the ledger come back, and the new messages continue both. The run starts in the permission mode the settings and flags resolve to, as a new session does, not in the mode the session ended in, and none of the earlier session’s “allow session” grants carry over. --fork-session copies both stores under a new id (--session-id chooses it) and leaves the original untouched; the audit log of the copy starts empty. --continue and a --resume by name look only at sessions whose primary workspace root is the project directory; --resume by id takes a session of any directory. A process killed mid-turn (Ctrl-C, a crash) no longer loses that turn: it is kept in the conversation, marked as unfinished, so the resumed run continues from where the stop happened. The same fold marks a turn the AFK temperature ceiling stopped.

Subagents

When the main conversation has given its final answer but subagents are still running, the run waits for them. Their reports reach the main conversation as notifications, each batch in a further turn, until none is running; then the result is emitted. --max-turns and --max-budget-usd count those turns and the subagents’ spend, and a run stopped by either kills the running subagents and drops their reports.

Background jobs are not waited for, except while a goal is active. A notice from a job that ended before the answer is delivered like a subagent’s report, in a further turn; a job still running when the run ends is terminated, so a headless run leaves no process behind. Jobs persist across the messages of one stream-json run and end with it.

Exit codes

CodeMeaning
0The run completed. Denied tool calls do not change this.
1A run error: a provider or model failure, a stop from --max-turns or --max-budget-usd, a goal that ended impossible or paused, or an --afk run that was blocked by repeated denials or stopped by the temperature ceiling (afk.outcome says which).
2A configuration or usage error.
3An account’s usage window stayed spent: the run exited at once under --on-usage-limit=exit, or the wait reached its cap, or was cancelled. result.subtype is error_usage_limit.

Usage windows

A subscription account that has spent its usage window answers every request with a 429 until the window resets. Fontaine tells that apart from a transient rate limit, which keeps its retry with a backoff, by the provider’s own machine code or a Retry-After of more than five minutes. When the main model’s list has no other entry to try, or the guardian’s account is the one that is spent, the whole run stops at its next provider call: the main agent, the guardian and every subagent wait, and a tool call that is waiting for a guardian verdict stays pending. It is neither denied nor run. When the window resets, the run goes on and the guardian checks the pending call again from the start.

A subagent whose own list is spent on a window first moves to the fallback role, when one is defined, and the run pauses only if that list is spent too.

The wait ends at the reset time the provider gave (a Retry-After header, a reset time in the reply, or the account’s own usage figures), plus a margin, with one request let through to check; without a reset time Fontaine checks after 1 minute, doubling to 15 minutes. It never lasts longer than --max-usage-wait. When it ends without the window opening, the run ends with exit code 3 and a result whose subtype is error_usage_limit and whose usage_limit object names the account, its role (main or guardian), the reset_at time (Unix epoch seconds, or null) and how the wait ended. A guardian-side pause that ends this way ends the run too, so the model cannot go on making gated calls that are denied. stream-json output carries usage_paused and usage_resumed events around a wait. Time spent waiting is not counted as a subagent’s run time.

An unattended run needs a limit on the wait, which is why max_usage_wait_secs is user-scope: a project file may set on_usage_limit = "exit" but nothing that makes a run wait longer.

Questions

ask_user_question stays in the tool list, but nobody can answer in a headless run: the call returns “User input is unavailable in this session; proceed with your best judgment and state your assumptions.” and the run continues.

An MCP server’s request for input (elicitation) is answered cancel in a headless run unless an elicitation hook answers it, so the call carries on without it; see MCP servers. A stdio MCP server that exits mid-run is started again the next time the model calls one of its tools (at most three times per server); a remote one that drops is reconnected as in the terminal UI and, after the five attempts fail on a transient error, retried in the background for 30 minutes; see Reconnecting.

Denials

Nothing prompts in a headless run. Every outcome that would ask a human, such as an ask rule, a protected-path call, or a call the mode does not pre-approve, becomes a denial that is returned to the model as the tool result; the run continues and exits 0. A plain -p run has no external approval delegate. A host that wants to answer those prompts uses Agent SDK mode, where canUseTool is a human channel that sits after the same permission rules and never loosens them. See Permissions.

With --afk the denial also tells the model that the user is not available and to complete the allowed work or stop and report; see AFK mode.

In auto the guardian answers instead, and a deny comes back to the model as Denied by guardian: [Rule] explanation. An escalate verdict is a denial, and so is every adjudication after three denials in a row or twenty in the session (the pause that a person would resolve by approving a prompt). When the guardian model cannot be used at all, every adjudication is a denial with the rule GuardianUnavailable (GuardianNotSignedIn when its account’s CLI is not signed in, which stops a guarded run before it starts; see Claude subscription); the init event reports guardian_available: false and a line on stderr names the model and the reason, so the run does not look like a guardian that judged everything unsafe.

Warnings about the configuration that do not stop the run, such as an additional directory that was skipped, go to stderr as fontaine: warning: ... before the model is resolved, so a run that then exits early (a usage error, for instance) still shows them. In auto a guardian running on the main model prints its notice as one line, headline and advice joined by a dash.

A headless auto run whose project has no stored environment facts prints one warning on stderr telling you to run fontaine auto-mode setup; the run goes on unchanged. A run in another mode, or with the facts stored, prints nothing. Fresh checkouts on CI can silence it with [auto_mode] setup_reminder = false in the user file or --settings; a shared project file cannot set it.

Every adjudicated call emits a gate_decision event, and the result event’s denials lists each denied call as {tool, tier, rule, explanation}, where rule names the rule and the scope it came from when a rule decided and explanation is what the model was told.

Output

Every JSON object carries schema_version (currently 1) and session_id. Additive fields keep the version; a rename or a removal bumps it. Consumers must ignore fields they do not know.

With --output-format json, the output is a single result object. With stream-json, each of these is one line, in the order the run produces them. The table lists the kinds in the order they first appear:

typeWhenMain fields
initOnce, firstmodel, guardian_model and guardian_profile (the guardian and profile in force, which may differ from the configured ones: a default pick, the main model, or full after a failed containment check), guardian_available, permission_mode, workspace_roots (the session’s scratch directory is the last entry when it could be created), config_sources (scope, path, whether loaded), workspace_trust, project_executables (whether project hooks, MCP servers and skill commands loaded), suspended_allow_rules (the broad allow rules auto sets aside; empty outside auto), tools
assistantA complete assistant messagetext
assistant_deltaWith --include-partial-messages, for each text fragmenttext
model_callA model call finished: after its assistant text and before its tool_call events. Main-conversation calls in call order; subagent usage is in result.usage.subagents and guardian calls are not eventsinput_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens, calls_tool (whether the call asked for a tool)
tool_callThe model called a tooltool_use_id, tool, args
gate_decisionA tool call was adjudicatedtool_use_id, agent_id (root for the main conversation, agent-N for a subagent), agent_name (the subagent’s name, null for the main conversation), tier, decision, rule; for guardian decisions also explanation, confidence, guardian_model and, when the guardian failed closed, fail_closed_reason (error, timeout, unparseable, low_confidence, unavailable, not_signed_in or usage_pause_ended, the wait for a spent usage window ended without it reopening); when a [guardian.composition] scored the call also screen_risk, screen_allow_risk and screen_steering (the reads named stop, allow and steering, when they ran), screen_scores (every other read, by name) and screen_outcome (stop, allow, deny, pass or unavailable)
tool_resultA tool answeredtool_use_id, tool, success, text (what the model received)
goalThe evaluator judged a goalverdict (met, not_met, impossible, or failed when no verdict arrived), reason, evaluations (verdicts so far)
usage_pausedAn account’s usage window is spent and the run is heldaccount, role (main or guardian), reset_at (Unix epoch seconds, or null when the provider gave none)
usage_resumedThe hold endedaccount, role, end (reset, probed, resumed, cancelled or cap_reached), waited_secs
afk_reportWith --afk, once after the last result, when the input ended at EOF and no earlier result carried the assessed reportafk (the object described under result)
resultAt the end of every turnsee below

tier is the stage of the permission pipeline that decided: deny_rule, ask_rule, protected_path, hook, read_only_fast_path, tracked_edit, scratch_write, shell_edit, tier05, spawn, coordination, allow_rule, mode, screen, guardian, dont_ask, human, guardian_off, afk, bug_draft or bug_report. The audit log records the same values.

Every gate_decision also carries afk (whether AFK mode was on) and converted, which names the prompt that was turned into a denial because nobody could answer it (ask_rule, floor, mode, hook, escalate, screen_escalate, breaker_paused or guardian_unavailable, which also covers a guardian whose account is not signed in), or is null.

The result object:

FieldMeaning
subtypesuccess, error_max_turns, error_max_budget_usd, error_during_execution or error_usage_limit
usage_limitOnly with error_usage_limit: account, role, reset_at and end (cancelled or cap_reached)
is_errorfalse only for success
resultThe final answer text; empty for an error
errorA message for an error, otherwise null
structured_outputWith --json-schema, the answer parsed as JSON
num_turnsModel calls made so far in the session
duration_msWall time of the turn
total_cost_usdSpend so far, main model plus guardian plus goal evaluator plus subagents, or null when none is priced. For a run priced by estimate — a databricks account, whose workspace bills in DBUs — it is a list-price estimate of what the tokens would have cost on the served vendor’s own API
usagemain, guardian, subagents and goal, each with input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens and cost_usd; the cache fields are the parts of the input read from and written to the provider’s prompt cache (0 when the provider reports none); guardian totals every adjudication that reached the model, subagents’ included (cached verdicts cost nothing); subagents is their model calls; goal is the goal evaluator’s calls, including attempts that gave no verdict. Each cost_usd carries the same qualifier as total_cost_usd: a list-price estimate for an estimate-priced run
account_usageOnly when the main or the guardian account has a quota source (a quota key, or a kimi or claude-subscription account, which needs none), fetched when the line is emitted (10 second timeout): one entry per such account, {role, account, label, windows}. role is main or guardian, account the configured account name, label the provider (kimi, claude) and windows the usage windows, {label, used_percentage, resets_at}, with used_percentage the used share rounded to a whole number from 0 to 100 and resets_at Unix epoch seconds (left out when the provider gives none), as in Claude Code’s status line rate_limits. An entry without windows means no data yet (a claude-subscription account before its first reply) or a failed fetch (the latter also warns on stderr, once per account). A guardian on the main account has no entry of its own.
denialsOne entry per denied call: tool, tier, rule, explanation
afkOnly with --afk, or when the session is stopped: outcome (ended, blocked or stopped), counts (allowed, denied, converted, and how the allowed calls ended), temperature (current, peak, ceiling, contributing), review (links and the assessment status) and timeline (every call of every agent). A stopped run has subtype = "error_during_execution". See AFK mode. With --input-format stream-json the assessment runs once, after the input ends, so a mid-run result shows assessment.status = "pending" when the stretch has denials; the assessed object follows in an afk_report event.
goalOnly when a goal was set, continued, queried or cleared: condition, status (active, met, impossible, paused or cleared), evaluations and reason (the evaluator’s last reason, or why it paused)

Usage and cost accumulate over the session, so each turn’s result reports the totals so far.

A stream-json run prints the result of every turn. A json or text run prints only the last one. With text, an error goes to stderr and nothing goes to stdout.

Multi-turn input

With --input-format stream-json, each line on stdin is one user message, in Claude Code’s shape:

{"type":"user","message":{"role":"user","content":"first question"}}
{"type":"user","message":{"role":"user","content":[{"type":"text","text":"a follow-up"}]}}

Every message is one turn of the same conversation. The run ends at the end of stdin, or at the first turn that fails. A line that is not a user message is a usage error (exit code 2). The input line is part of the same schema.

printf '%s\n' '{"type":"user","message":{"role":"user","content":"hi"}}' \
  | fontaine -p --input-format stream-json --output-format stream-json

Using it as a driver

A TypeScript or Python Agent SDK application drives fontaine through a different surface, described in Claude Agent SDK compatibility; it is selected by the SDK’s own command line and does not change this page’s contract.

The eval runner and the integration tests run fontaine -p against a scripted model endpoint, so the output contract is what they assert on. To script a run, point an openai-compatible account at a local server and pass --output-format stream-json; read the init line to confirm which configuration files and workspace roots the run used, and the result line for the outcome.