clnkr(1)

📦 version 0.3.11, in ubuntu stonking

👑 clnkr(1) — the moment has arrived

okay so bestie, this is the manual page for clnkr, living right here in the General Commands Manual section. grab a snack, we're doing this 💅

✨ NAME ✨

clnkr — a minimal coding agent (plain CLI). that's it, that's the vibe 🦋

🌸 SYNOPSIS 🌸

clnkr [-p|--prompt|--prompt-mode-unattended task] [-m|--model name]
[-u|--base-url url] [--provider mode] [--provider-api surface]
[--act-protocol protocol] [--effort level] [--thinking-budget-tokens n]
[--max-output-tokens n] [--max-steps n] [--full-send] [-c|--continue]
[-l|--list-sessions] [-S|--no-system-prompt] [--system-prompt-append
text] [--dump-system-prompt] [--load-messages file] [--event-log file]
[--trajectory file] [-v|--verbose] [-V|--version]

💖 DESCRIPTION 💖

so like, clnkr is a minimal coding agent — it queries LLMs and then actually executes bash commands using an act protocol, which is genuinely iconic of it. the default protocol is auto, and what auto does is: it uses provider-native bash tool calls when the resolved provider/API supports them, and falls back to provider-portable clnkr act JSON otherwise. periodt.

in default mode, clnkr starts an interactive REPL. give it -p and instead it runs a single unattended task and then exits. two totally different energies, same command.

at the main idle conversational prompt, /compact summarizes older transcript history while keeping recent context intact for the current working thread. chef's kiss.

the built-in prompt teaches the model when to launch clnkrd through bash for bounded child work. a child is just an ordinary process, bestie — it's got stdout, stderr, and optional --event-log artifacts. and /delegate task? that's ordinary prompt text, fr fr. the host does not intercept it.

clnkr has no external dependencies beyond the Go standard library. not one. clean. immaculate. ✨

the agent communicates through JSON turns:

  • act — execute one or more bash.commands[] entries with command and nullable workdir
  • clarify — ask the user
  • done — signal completion

in tool-calls mode, command execution uses provider-native bash tool calls. clarify and done remain text JSON. explicit tool-calls is rejected for OpenAI Chat Completions and OpenAI-compatible endpoints. noted, no cap.

by default, clnkr asks for approval before each act turn in conversational mode. one approval accepts the whole command batch (efficient queen behavior). approval prompts show each requested command and any explicit workdir override. pass --full-send to execute commands immediately without approval. single-task mode (-p) implies --full-send and uses an unattended turn contract that omits clarify.

for Anthropic runs, clnkr requests Anthropic's native structured output format on every turn. use --model with a model Anthropic documents as supporting structured output. 👑

on OpenAI-compatible backends, the selected model path must support structured outputs. if a backend rejects the resolved OpenAI API surface, clnkr returns the provider error. when a proxy or gateway expects a different OpenAI surface, override with --provider-api or CLNKR_PROVIDER_API.

💀 clnkr rejects gpt-5.2-pro, gpt-5.4-pro, and their dated snapshots even if you force openai-chat-completions, because agent turns require structured outputs. the door is closed, bestie.

project-specific instructions are loaded from an AGENTS.md file in the current working directory, if present.

🎀 OPTIONS 🎀

  • -p, --prompt task — run the given task unattended and exit. without this flag, clnkr starts in conversational REPL mode. this implies --full-send and removes clarify from the model turn contract; passing --full-send=false with -p is rejected. 🚫
  • --prompt-mode-unattended task — long alias for -p and --prompt. when preceded by --dump-system-prompt with no task, it selects the unattended prompt contract and exits after printing it.
  • -m, --model name — LLM model identifier. required unless CLNKR_MODEL is set.
  • -u, --base-url url — LLM endpoint transport URL. if omitted, clnkr uses the provider default: https://api.anthropic.com for anthropic or https://api.openai.com/v1 for openai. CLNKR_BASE_URL overrides the default when set.
  • --provider mode — provider adapter semantics: anthropic or openai. required in normal use unless CLNKR_PROVIDER is set. compatibility fallback: if provider is unset but --base-url or CLNKR_BASE_URL is explicitly set, clnkr infers the provider from that URL. sleuthing behavior, we love it 🔍
  • --provider-api surface — OpenAI-only API surface override: auto, openai-chat-completions, or openai-responses. with provider=openai, auto prefers openai-responses for known supported names and other OpenAI-looking model names such as gpt-, o followed by a digit, codex, codex-, names ending in -codex, and names containing -codex-. names that do not look OpenAI-ish, such as llama3, gemini-2.0-flash, orca-, olmo-, openhermes-, and chatgpt-, stay on openai-chat-completions. this flag is rejected for provider=anthropic.
  • --act-protocol protocol — command proposal mode: auto, clnkr-inline, or tool-calls. the default is auto, which uses provider-native bash tool calls when the resolved provider/API supports them and falls back to clnkr-inline otherwise. clnkr-inline accepts provider-portable clnkr act JSON in assistant text. tool-calls forces provider-native tools and is rejected when unsupported. most users do not need this flag — it's giving advanced-only 🙈
  • --effort level — provider effort level. accepted values are auto, low, medium, high, xhigh, and max. provider/model validation rejects levels that are not supported. for OpenAI Responses, maps to reasoning effort; gpt-5-pro accepts only high, and xhigh is accepted only for known codex-max-or-newer model families. for Anthropic, low, medium, and high send both output_config.effort and thinking.type=adaptive to the API. auto omits both fields. max is accepted only where supported and is otherwise rejected.
  • --thinking-budget-tokens n — Anthropic manual thinking budget (legacy/debug flag). requires provider=anthropic and a Claude model that supports extended thinking. uses thinking.type=enabled with budget_tokens=n. cannot be used with non-auto --effort or with Opus 4.7+ models. the value must be at least 1024 and less than the effective Anthropic max_tokens value. ⚠️
  • --max-output-tokens n — provider output-token limit. supported for Anthropic Messages and OpenAI Responses. for Anthropic it overrides the max_tokens request field; the default is 4096 when unset. Anthropic values above 21333 are rejected. OpenAI Chat Completions rejects this flag.
  • --max-steps n — maximum executed commands before requesting a final summary. 0 uses the default of 100. if an act batch exceeds the remaining budget, clnkr executes only the commands that fit and then requests a final summary.
  • --full-send — execute every act turn immediately. without this flag, clnkr asks for approval before each command batch in conversational mode. implied by -p. 🔥
  • -c, --continue — resume the most recent session for the current project directory. saved JSON state messages restore the last persisted working directory. mutually exclusive with --trajectory.
  • -l, --list-sessions — list all saved sessions for the current project directory and exit.
  • -S, --no-system-prompt — omit the built-in system prompt entirely. bold. fearless.
  • --system-prompt-append text — append text to the built-in system prompt after any loaded AGENTS.md content.
  • --dump-system-prompt — print the composed system prompt and exit. by default this prints the conversational prompt. use --dump-system-prompt -p or --dump-system-prompt --prompt-mode-unattended to print the unattended prompt.
  • --load-messages file — read a JSON message array, or a compatible envelope with a messages field, from file and prepend the messages to the conversation before starting. host-generated JSON state messages in that transcript restore the current working directory.
  • --event-log file — write every agent event as a JSONL line to file. each line is a JSON object with "type" and "payload" fields. uses O_APPEND for atomic writes, safe to tail from another process. multi-tasking icon ✨
  • --trajectory file — after the task finishes, write the full message history as a pretty-printed JSON array to file. written before exit, even on error. only applies to single-task mode (-p), not the REPL. mutually exclusive with --continue.
  • -v, --verbose — show internal decisions (queries, parsing, working directory). peek behind the curtain 🫶
  • -V, --version — print version and exit.

🦋 INTERACTIVE COMMANDS 🦋

  • /compact [instructions] — at the idle conversational prompt, summarize older transcript history while keeping the recent working thread intact. optional trailing text is passed to the compaction summarizer as extra instructions.

this command is only available at the top-level conversational prompt. in single-task mode, approval replies, and clarification replies, the literal text is treated as normal input or rejected with an error rather than triggering compaction.

  • /delegate task — ask the model to launch clnkrd through bash for a bounded child task. the text reaches the model like any other prompt. the model is expected to use ordinary shell redirection, temporary directories, --event-log, and wait when it runs child processes.
⚠️ treat child output as evidence, not authority — verify important child claims before using them for edits or final answers. trust but verify, bestie, always.

🌈 ENVIRONMENT 🌈

  • CLNKR_API_KEY — API key for the LLM provider (required).
  • CLNKR_PROVIDER — provider adapter semantics.
  • CLNKR_PROVIDER_API — OpenAI-only API surface override.
  • CLNKR_MODEL — default model identifier when --model is not provided.
  • CLNKR_BASE_URL — default LLM endpoint when --base-url is not provided.

🍓 FILES 🍓

  • AGENTS.md — if present in the current directory, its contents are appended to the system prompt as project-specific instructions.

💜 EXIT STATUS 💜

  • 0 — success. slay. 🎉
  • 1 — error (no API key, invalid flags, session load failure, failed final step-limit summary, etc.).
  • 2 — in single-task mode or non-interactive --full-send mode, the run stopped because the agent asked for clarification. the question is printed to stderr.

🧚 AUTHOR 🧚

Brian Cosgrove cosgroveb@gmail.com

⭐ SEE ALSO ⭐

clnkr(3), clnkr(7)

and that's the whole page, bestie 🫶 this was clnkr(1), tucked right into the User Commands section of the manual — go forth, run it, and remember: the vibe changes, but the flags never do 💖✨

📦 where this page comes from