.env.example

# Copy to `.env` to override kickoff.sh defaults. Anything already exported
# in the parent shell wins over this file.
#
# Provider: shell (default) | claude | codex | gemini | pi | ollama | openwebui
CLK_PROVIDER=shell

# Iteration budget.
CLK_MAX_ITERATIONS=10

# Project name embedded in commits and visible via `clk status`.
CLK_PROJECT_NAME=clk-app

# Set to true to run scripts/install_local.sh inside the kickoff dir
# (creates .clk/venv and installs PyYAML). Optional - the harness has a
# minimal YAML fallback so this is rarely needed.
CLK_RUN_INSTALL=false

# Skip the TUI and run the legacy init/idea/plan/run/loop pipeline
# (useful for CI / smoke tests). Requires the idea argument.
CLK_NO_TUI=false

# ---------------------------------------------------------------------------
# Authentication for CLI-driven providers (claude, codex, gemini)
# ---------------------------------------------------------------------------
# cli    = trust the provider CLI's existing auth (e.g. you already ran
#          `claude login`, `codex login`, or signed in to Gemini). This is
#          the default and means the API-key vars below are ignored.
# apikey = pass the API key via the standard env var. Use this if you
#          haven't logged in via the CLI or you want to override.
CLK_AUTH_MODE=cli

# Only used when CLK_AUTH_MODE=apikey AND the matching provider is active.
ANTHROPIC_API_KEY=
OPENAI_API_KEY=
GEMINI_API_KEY=
# Either GEMINI_API_KEY or GOOGLE_API_KEY is accepted for the gemini provider.
GOOGLE_API_KEY=

# ---------------------------------------------------------------------------
# Git identity for kickoff commits
# ---------------------------------------------------------------------------
# Overrides the container's global git config when set. Useful in Docker so
# commits carry a meaningful author rather than "CLK Container". Leave blank
# to keep whatever git config is already set.
CLK_GIT_NAME=
CLK_GIT_EMAIL=

# ---------------------------------------------------------------------------
# HTTP-based providers
# ---------------------------------------------------------------------------
# Ollama: local HTTP API on this host.
CLK_OLLAMA_ENDPOINT=http://localhost:11434
CLK_OLLAMA_MODEL=llama3.1

# OpenWebUI: any OpenAI-compatible HTTP server (chat.example.com etc.).
# On kickoff, if CLK_OPENWEBUI_MODEL is unset and the endpoint is
# reachable, you'll get a numbered pick list of models from /api/models.
# If unreachable / unauth'd, kickoff falls back to free-form entry.
CLK_OPENWEBUI_ENDPOINT=http://localhost:8080
CLK_OPENWEBUI_API_KEY=
CLK_OPENWEBUI_MODEL=

# Pi provider (pi.dev CLI)
# CLK_PI_MODEL: model to pass as `pi --model <value>`. Examples:
#   openrouter/free       — free tier via OpenRouter (no key required for some models)
#   openrouter/auto       — let OpenRouter pick the best available free model
#   anthropic/claude-3-5-sonnet  — specific model via OpenRouter
# Leave blank to use whatever pi's own default / active profile selects.
CLK_PI_MODEL=
# CLK_PI_KEY_TYPE: the provider your key belongs to. The harness derives
# the env var by convention: {KEY_TYPE.upper()}_API_KEY. Examples:
#   openrouter  -> OPENROUTER_API_KEY
#   openai      -> OPENAI_API_KEY
#   anthropic   -> ANTHROPIC_API_KEY
#   mistral     -> MISTRAL_API_KEY   (any future provider works automatically)
# Defaults to openrouter (the most common free-tier path).
CLK_PI_KEY_TYPE=openrouter
# CLK_PI_API_KEY: the actual key for the provider named in CLK_PI_KEY_TYPE.
# Leave blank if you've already run `pi login` and pi has its own stored credentials.
CLK_PI_API_KEY=

# ----------------------------------------------------------------------
# Telegram bot (two-way chat control). Run scripts/telegram_setup_wizard.sh
# to populate these interactively, or fill them in by hand.
# ----------------------------------------------------------------------
# Bot token from @BotFather (123456789:AA...). Required to run clk-telegram-bot.
CLK_TELEGRAM_BOT_TOKEN=
# Comma-separated numeric Telegram user IDs allowed to use the bot. Empty
# means nobody is allowed (fail-closed).
CLK_TELEGRAM_ALLOWED_USERS=
# Set to "true" once configured so kickoff.sh stops prompting.
CLK_TELEGRAM_ENABLED=false
# Set to "true" when you decline Telegram in `kickoff.sh --setup` so the
# wizard records your choice. Set back to "false" (or re-run --setup) to
# enable Telegram later.
CLK_TELEGRAM_SKIP=false
# Default workspace the bot operates on when /workspace has not been set.
CLK_TELEGRAM_WORKSPACE=

# ----------------------------------------------------------------------
# Robustness loops (see README "Robustness loops" section)
# ----------------------------------------------------------------------
# Every layer below has an off-switch so you can dial cost.  All values
# are forwarded into .clk/config/clk.config.json by kickoff.sh; you can
# also edit that file directly to override per project.

# Auto-consensus fan-out: every "careful" dispatch fans into N parallel
# stochastic samples + chief coalescing, instead of a single dispatch.
#   off          — only PROPOSE_CONSENSUS triggers fan-out (legacy)
#   on_careful   — fan out stages marked careful=true (default)
#   always       — fan out every non-chief dispatch (×N cost)
# Cost: ~×consensus.max_samples per affected dispatch.
CLK_ROBUSTNESS_AUTO_CONSENSUS=on_careful

# Critic-judge refinement: draft -> critic -> revise inner loop.
#   off            — only explicit refine: blocks in workflow YAML
#   careful_only   — careful=true stages get one critic pass (default)
#   all            — every non-chief, non-qa stage gets one critic pass
# Cost: +1 critic dispatch + up to refine_max_rounds-1 worker revisions
# per affected stage.
CLK_ROBUSTNESS_AUTO_REFINE=careful_only

# After every dispatch the response is scored for emptiness, malformed
# ACTION/POST blocks, missing declared outputs, and low confidence;
# recoverable failures re-dispatch with a repair preamble, escalating
# to consensus on the final retry. Set to 0 to disable.
CLK_ROBUSTNESS_MAX_QUALITY_RETRIES=2

# Responses shorter than this many characters are treated as suspect-empty.
CLK_ROBUSTNESS_MIN_RESPONSE_CHARS=40

# Critic-judge inner loop bounds.
CLK_ROBUSTNESS_REFINE_MAX_ROUNDS=3
CLK_ROBUSTNESS_REFINE_ACCEPT_THRESHOLD=0.8

# Inter-agent Q&A protocol: POST: question TO: <peer> URGENCY: blocking.
# qa_parallel_judges optionally dispatches multiple peers in parallel.
# max_qa_depth caps the chain length (peer A asks B asks C ...).
CLK_ROBUSTNESS_QA_PARALLEL_JUDGES=1
CLK_ROBUSTNESS_MAX_QA_DEPTH=3

# Context-isolated DELEGATE sub-agents (DELEGATE: TO: <agent> TASK: ...).
# max_delegate_depth caps nesting; 1 = a worker may delegate but the child
# cannot itself delegate (one level deep).
CLK_ROBUSTNESS_MAX_DELEGATE_DEPTH=1

# Ralph / autoresearch plateau detection. After plateau_window
# consecutive iterations without improvement, the loop escalates +
# reframes; failing that, it terminates gracefully with done.md.
#   off                     — never auto-terminate (legacy behavior)
#   escalate_only           — force consensus on next iterations only
#   reframe_only            — only ask chief to re-cast
#   escalate_then_reframe   — both, then terminate (default)
CLK_ROBUSTNESS_PLATEAU_WINDOW=3
CLK_ROBUSTNESS_PLATEAU_ACTION=escalate_then_reframe

# Adversarial debate panel: instead of a single critic, spawn N critics
# with distinct lenses that try to break the work and debate each other
# across rounds before the worker revises.
#   off | careful_only (default) | all
CLK_ROBUSTNESS_DEBATE=careful_only
# Comma-separated adversarial lenses (one critic per lens, run in parallel).
CLK_ROBUSTNESS_DEBATE_LENSES=correctness,security,simplicity
# Cap on debate rounds (each round = panel critique + worker revision).
CLK_ROBUSTNESS_DEBATE_MAX_ROUNDS=2

# ----------------------------------------------------------------------
# Autonomous missions, done-gate, no-op guard, deliberation
# (clk run drives a full mission to a code-gated done; see README
#  "Autonomous missions"). Every check has a kill switch here.
# ----------------------------------------------------------------------
# Mission loop bounds + behavior.
CLK_MISSION_MAX_PHASES=12
CLK_MISSION_MAX_ITERATIONS_PER_PHASE=3
CLK_MISSION_MAX_TOTAL_CYCLES=60
CLK_MISSION_PHASE_GATE=true
CLK_MISSION_REFINE_REQUIRED=true
CLK_MISSION_AUTO_CONSENSUS_ON_STALL=true
CLK_MISSION_CHARTER_FIRST=true
CLK_MISSION_COMMIT_TRACE=true
CLK_MISSION_COMMIT_GRANULARITY=batch
CLK_MISSION_MIN_CYCLES_BEFORE_DONE=1
CLK_MISSION_TELEMETRY_STDOUT=true
CLK_MISSION_ON_BUDGET_EXHAUSTED=advance
# Comma-separated default lifecycle phases (used when planning can't parse).
CLK_MISSION_DEFAULT_PHASES=discovery,product,engineering,validation,deployment
# Machine-checkable done-gate: ACTION:done is only granted when these pass.
CLK_DONE_GATE_ENABLED=true
CLK_DONE_GATE_REQUIRE_TESTS_GREEN=true
CLK_DONE_GATE_REQUIRE_DELIVERABLES=true
CLK_DONE_GATE_MIN_DELIVERABLE_FILES=1
CLK_DONE_GATE_REQUIRE_QA_PASS=true
CLK_DONE_GATE_REQUIRE_RALPH_PASS=true
CLK_DONE_GATE_FORBID_TODO_MARKERS=false
CLK_DONE_GATE_MAX_FINISH_ATTEMPTS=5
# No-op guard: re-dispatch a producing stage that changed no files.
CLK_NOOP_GUARD_ENABLED=true
CLK_NOOP_GUARD_MAX_REDISPATCH=2
CLK_NOOP_GUARD_PRODUCING_AGENTS=engineer,ralph
CLK_NOOP_GUARD_TREAT_OUTPUTS_STAGE_AS_PRODUCING=true
# Deliberation: self-reflection + blocking peer Q&A before a phase passes.
CLK_DELIBERATION_ENABLED=true
CLK_DELIBERATION_ENCOURAGE_QUESTIONS=true
CLK_DELIBERATION_REQUIRE_OPEN_QUESTIONS_RESOLVED=true
CLK_DELIBERATION_SELF_REFLECT_PREAMBLE=true
CLK_DELIBERATION_MIN_DEBATE_ROUNDS=1
# Auto-derive a real validation command when a producing stage has none.
CLK_VALIDATION_AUTO_DERIVE=true

# ----------------------------------------------------------------------
# Prior-knob reference (already supported; documented here for parity)
# ----------------------------------------------------------------------
# Provider invocation timeout, seconds. 0 = use harness default (300s).
CLK_PROVIDER_TIMEOUT_S=0
# Per-provider-invocation no-output watchdog (kill if no stdout for N s).
CLK_PROVIDER_NO_OUTPUT_TIMEOUT_S=0
# Provider-level retry policy (transient errors: rate limits, timeouts, ...).
CLK_PROVIDER_RETRY_MAX_RETRIES=10
CLK_PROVIDER_RETRY_BACKOFF_S=5
# Stage-level retry policy (whole stage repeats with a larger backoff).
CLK_PROVIDER_RETRY_STAGE_MAX_RETRIES=10
CLK_PROVIDER_RETRY_STAGE_BACKOFF_S=30
# Chief supervise loop: cap on cycles before warning and stopping.
CLK_SUPERVISE_MAX_CYCLES=20
# Stochastic consensus caps (same scope as the auto-consensus knob).
CLK_CONSENSUS_MAX_SAMPLES=6
CLK_CONSENSUS_MAX_PARALLEL=4
# Dynamic-roles cap (chief cannot mint more than this many dynamic agents).
CLK_CASTING_MAX_DYNAMIC_ROLES=12
# Auto-commit per agent-run after successful ACTION application.
CLK_AUTO_COMMIT=true
# File-action batch caps (per agent response).
CLK_VALIDATION_MAX_FILES_PER_BATCH=25
CLK_VALIDATION_WARN_FILES_PER_BATCH=5
# Meta-prompt drafting (chief tightens worker prompts before dispatch).
#   off | careful_only (default) | always
CLK_META_PROMPT_DISPATCH=careful_only
CLK_META_PROMPT_ROLE=careful_only
# Per-stage checkpoint (chief CONTINUE/REDIRECT/ABORT after every stage).
CLK_REVIEW_PER_STAGE=false
# Recovery on unmet deps: chief recovery passes per stage.
CLK_RECOVERY_MAX_PER_STAGE=3