The flags worth knowing: -model, -effort low|medium|high|xhigh|max, -max-turns,
-resume latest, -no-stream, -no-cache, -no-auto-compact, -v, -yolo,
-no-tui, -no-skills, -no-agents, -no-web, -no-hooks,
-no-diagnostics, -no-mcp, -claude-code-auth, -no-claude-code-auth,
-trust-project. And the ones a script written for Claude Code passes, with
Claude Code's meaning — see using it in place of
claude: --output-format text|json|stream-json, -c/--continue, --allowedTools,
--disallowedTools, --permission-mode, --dangerously-skip-permissions,
--append-system-prompt, --system-prompt, --verbose, --print. Every flag
takes one dash or two.
-compact-at (default 0.7) is where the conversation is normally folded into a
summary, keeping the last six messages verbatim. Early and rare is deliberate:
compaction is itself a model call with the history in it, and it is the single
biggest thing that breaks prompt caching.
-compact-floor (default 0.97) is the fraction past which compaction stops
being optional. The normal threshold declines a history it cannot split safely —
a handful of enormous tool results is too few messages to cut six off the end of
— and below the floor that restraint is right. Past it, a verbatim tail is worth
nothing if the next request has no room to be sent, so the floor folds anyway
and settles for a one-message tail. /compact follows the same rule past the
floor, since with auto-compaction off it is the only move left. When even that
finds nothing to fold, Codey says so, rather than letting the next
request fail as a bare API error.
-context-window (default 1,000,000) is what both fractions are measured
against; lower it for a model with less room.
-max-turns caps one prompt, and by default there is no cap: a turn count is a
bad proxy for the thing it was guarding against. A task is not finished at turn
thirty and unfinished at thirty-one, and a run that stops there has thrown away
a job that was going fine. What bounds an interactive session is the context
window, the bill, and a person who can press esc.
An unattended run has none of those, which is what the flag is for: set it in
-p mode and in CI, where nobody is watching and a model stuck repeating one
failing tool call would otherwise repeat it until the money ran out. When a cap
you asked for does trip, the conversation is left intact and the last thing the
model said comes back with the error rather than being thrown away — say what
to do next, or raise it.
-no-auto-compact turns the automatic fold off for one run, the same as
"auto_compact": "off" in the config. The floor then stops the turn instead of
folding: the session stays intact, nothing is summarized behind your back, and
/compact is what makes room. In -p mode the stop is a non-zero exit.
-no-agents leaves out the subagent tools, so the agent works alone. -no-web
takes away web access for one run, whatever the config says; like -yolo in
reverse, it can only subtract.