Scroll to navigation

clnkr(1) General Commands Manual clnkr(1)

NAME

clnkr - a minimal coding agent (plain CLI)

SYNOPSIS

clnkr [-p|--prompt task] [-m|--model name] [--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

clnkr is a minimal coding agent that queries LLMs and executes bash commands using an act protocol. The default protocol is auto, which uses provider-native bash tool calls when the resolved provider/API supports them and falls back to provider-portable clnkr act JSON otherwise.

In default mode, clnkr starts an interactive REPL. With -p, it runs a single unattended task and exits. Single-task runs save the project session by default, so later clnkr --continue and clnkr --list-sessions can see them.

At the main idle conversational prompt, /compact summarizes older transcript history while keeping recent context intact for the current working thread.

If a provider rejects a model step because the transcript exceeds the model context window, clnkr automatically compacts older transcript history, reports the compacted message counts on stderr, and retries that failed model step once. The automatic retry uses the same [compact] transcript format as /compact and is saved in ordinary project sessions.

clnkrd is the stdio JSONL adapter for external tools embedding clnkr behavior. It is not a daemon framework, service host, or model delegation mechanism. Inputs such as /delegate task are ordinary prompt text; the host does not intercept them.

clnkr has no external dependencies beyond the Go standard library.

The agent communicates through JSON turns: act (execute one or more bash.commands[] entries with command and nullable workdir), clarify (ask the user), and 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.

By default, clnkr asks for approval before each act turn in conversational mode. One approval accepts the whole command batch. 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.

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

OPTIONS

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.
LLM model identifier. Required unless CLNKR_MODEL is set.
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 adapter semantics: anthropic or openai. Required unless CLNKR_PROVIDER is set.
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.
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.
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.
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.
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.
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.
Execute every act turn immediately. Without this flag, clnkr asks for approval before each command batch in conversational mode. Implied by -p.
Resume the most recent session for the current project directory. Saved JSON state messages restore the last persisted working directory. Mutually exclusive with --trajectory.
List all saved sessions for the current project directory and exit.
Omit the built-in system prompt entirely.
Append text to the built-in system prompt after any loaded AGENTS.md content.
Print the composed system prompt and exit. By default this prints the conversational prompt. Use --dump-system-prompt -p to print the unattended prompt.
Read a JSON message array from file and prepend the messages to the conversation before starting. Host-generated JSON state messages in that transcript restore the current working directory.
Write every agent event as a JSONL line to file. Each line is a JSON object with ts, type, and payload fields. ts is a UTC RFC3339Nano timestamp recorded when clnkr writes the event. Older logs may contain only type and payload. Opens file with O_APPEND, so another process can tail the file while clnkr appends.
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.
Show internal decisions (queries, parsing, working directory).
Print version and exit.

INTERACTIVE COMMANDS

/compact
At the idle conversational prompt, summarize older transcript history while keeping the recent working thread intact.

This command is only available at the top-level conversational prompt. Trailing text after /compact is rejected. In single-task mode, approval replies, and clarification replies, the literal exact command is rejected with an error rather than triggering compaction.

ENVIRONMENT

API key for the LLM provider (required).
Provider adapter semantics.
OpenAI-only API surface override.
Default model identifier when --model is not provided.
Default LLM endpoint when --base-url is not provided.

FILES

If present in the current directory, its contents are appended to the system prompt as project-specific instructions.

EXIT STATUS

0
Success.
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)

User Commands