clankie-agent/docs/env-reference.md

CLANKIE_* environment variable reference

Generated by pnpm env:reference (scripts/generate-env-reference.ts) from the CLANKIE_* reads in agent/, bin/, scripts/, and packages/. Do not edit by hand — edit the description table in the generator and regenerate.

Values are read from the process environment first, then .env.local at the repo root (process.env wins; see agent/lib/env-store.ts).

Core paths & lifecycle

Variable	Description
`CLANKIE_BRAIN_AGENT`	Herdr agent name for the command-host/brain pane (default `clankie`).
`CLANKIE_HERDR_BIN`	Herdr-compatible stage binary the lifecycle script uses (default `herdr` on PATH; set to `clankie-herdr` for the Clankie-owned fork).
`CLANKIE_HOME`	Clankie data root for durable state (default `~/.clankie`): auth store, transcripts, memory, logs, push registry, media.
`CLANKIE_MAIN_AGENT`	Herdr agent name of the main face pane, for gateway bridge commands (default `clankie`).
`CLANKIE_REPO_DIR`	Repo checkout dir; anchors `.env.local`, the spawn seam's `bin/clankie.ts`, and mirror scripts when a process is not started from the repo root.
`CLANKIE_SESSION`	Herdr session name the lifecycle script targets (default `clankies`).
`CLANKIE_SETUP_SEEN`	First-run setup-offer marker written by the face or `clankie setup`; unset/absent allows the one-time `/setup` offer on an otherwise empty install.
`CLANKIE_UP_SESSION_TIMEOUT_MS`	How long `clankie up` waits for the herdr session to start (default 15000).

Eve server address & supervision

Variable	Description
`CLANKIE_BRAIN_STDOUT_LOG_MAX_BYTES`	Maximum bytes per durable owned dev brain stdout log file at `<CLANKIE_HOME>/logs/brain.stdout.log` before rotation (default 8 MiB).
`CLANKIE_BRAIN_STDOUT_LOG_MAX_FILES`	Maximum number of durable owned dev brain stdout log files to retain, including the current file (default 5).
`CLANKIE_EVE_BASE_URL`	Base URL other processes use to reach the eve server (default `http://127.0.0.1:<port>`); always a URL.
`CLANKIE_EVE_BIND_HOST`	Interface the owned eve dev server binds to (e.g. `127.0.0.1`, `0.0.0.0`); never a URL. See agent/lib/eve-address.ts.
`CLANKIE_EVE_CALLBACK_PROXY`	Set `0` to disable the localhost OAuth callback proxy the face runs for connection auth flows.
`CLANKIE_EVE_CALLBACK_PROXY_PORT`	Port for the OAuth callback proxy (default 3000).
`CLANKIE_EVE_HEALTH_POLL_MS`	Face brain-health poll interval (default 5000).
`CLANKIE_EVE_HEALTH_TIMEOUT_MS`	How long the face/CLI/lifecycle wait for a starting brain to become healthy (default 180000).
`CLANKIE_EVE_HOST`	Legacy combined var: an http(s) URL is treated as CLANKIE_EVE_BASE_URL, a bare host as CLANKIE_EVE_BIND_HOST. Prefer the split vars.
`CLANKIE_EVE_KILL_TIMEOUT_MS`	Wait after SIGKILL when stopping the owned eve server (default 2000).
`CLANKIE_EVE_PORT`	eve/relay port (default 2000).
`CLANKIE_EVE_PROBE_TIMEOUT_MS`	Per-probe fetch timeout for /eve/v1/info health checks (default 2000).
`CLANKIE_EVE_RESTART_STOP_TIMEOUT_MS`	Shorter SIGTERM grace used for intentional config-change restarts (default 1000).
`CLANKIE_EVE_STOP_TIMEOUT_MS`	SIGTERM grace before SIGKILL when stopping the owned eve server (default 5000).
`CLANKIE_LIFECYCLE_TOKEN`	Bearer token the launchd supervisor requires on its lifecycle endpoints (/lifecycle/up
`CLANKIE_RESTART_ATTACHED_EVE`	Set `1` to let the face restart an attached (non-owned) eve dev server after config writes, even when it is not an ancestor process.
`CLANKIE_SUPERVISOR_HOST`	Bind host override for the lifecycle supervisor; defaults to the tailnet interface and is never 0.0.0.0 unless set (agent/lib/supervisor.ts).
`CLANKIE_SUPERVISOR_PORT`	Port the lifecycle supervisor daemon binds (default 2001).

Brain model selection

Variable	Description
`CLANKIE_CLAUDE_MODEL`	Claude brain model id (default from config-defaults.ts).
`CLANKIE_CODEX_EFFORT`	Codex reasoning effort: minimal
`CLANKIE_CODEX_MODEL`	Codex brain model id (default from agent/lib/config-defaults.ts).
`CLANKIE_GEMINI_CONTEXT_TOKENS`	Context window override for the Gemini brain (off-catalog).
`CLANKIE_GEMINI_MODEL`	Gemini brain model id (default from config-defaults.ts).
`CLANKIE_LOCAL_BASE_URL`	Local OpenAI-compatible endpoint (default `http://127.0.0.1:11434/v1`).
`CLANKIE_LOCAL_CONTEXT_TOKENS`	Context window for the local brain (eve cannot resolve off-catalog models); the face auto-injects it from Ollama metadata.
`CLANKIE_LOCAL_EFFORT`	reasoning_effort forwarded to thinking local models: low
`CLANKIE_LOCAL_MODEL`	Local brain model id served by the OpenAI-compatible endpoint.
`CLANKIE_LOCAL_MODEL_SUPPORTS_VISION`	Set `1` when the local brain accepts image input, so media_inspect can use it directly.
`CLANKIE_LOCAL_PROVIDER_NAME`	Provider name label for the local model endpoint (obscure).
`CLANKIE_MODEL_PROVIDER`	Conductor brain route: `openai` (default), `codex`, `claude`, `local`, `xai`, or `gemini`.
`CLANKIE_OPENAI_MODEL`	OpenAI API brain model id (default from agent/lib/config-defaults.ts).
`CLANKIE_STARTUP_MODEL_FALLBACK_ENV_NAMES`	Internal: the missing API-key env names for the startup-fallback notice.
`CLANKIE_STARTUP_MODEL_FALLBACK_PROVIDER`	Internal: set by the launcher when a keyless xai/gemini selection fell back to OpenAI at startup, so the face can show the notice.
`CLANKIE_XAI_CONTEXT_TOKENS`	Context window override for the xAI brain (off-catalog).
`CLANKIE_XAI_MODEL`	xAI brain model id (default from config-defaults.ts).

API keys & credential stores

Variable	Description
`CLANKIE_ALLOW_SUBSCRIPTION_AUTH`	Set `1` to opt in to ToS-gray Codex/Claude subscription OAuth brain providers. Off by default; use the OpenAI/xAI/Gemini API-key providers for the default OSS path.
`CLANKIE_CLAUDE_AUTH`	Override path to the Claude subscription OAuth store (default `<CLANKIE_HOME>/profiles/default/auth.json`).
`CLANKIE_CODEX_AUTH`	Override path to the Codex subscription OAuth store (default `<CLANKIE_HOME>/profiles/default/auth.json`).
`CLANKIE_ELEVENLABS_API_KEY`	ElevenLabs API key (fallback: ELEVENLABS_API_KEY) for external TTS.
`CLANKIE_GEMINI_API_KEY`	Gemini API key (fallbacks: GEMINI_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY).
`CLANKIE_OPENAI_API_KEY`	OpenAI API key (fallback: OPENAI_API_KEY). Default brain, images, vision fallback, realtime voice.
`CLANKIE_OPENAI_BASE_URL`	OpenAI-compatible base URL override for keyed OpenAI calls (obscure).
`CLANKIE_XAI_API_KEY`	xAI API key (fallback: XAI_API_KEY). Brain, Grok media, and realtime voice.
`CLANKIE_XAI_BASE_URL`	xAI base URL override (obscure).

Relay & iOS

Variable	Description
`CLANKIE_CHAT_TOKEN`	Continuation token passed to a `clankie attach` face so an iOS chat pane binds to its eve session; set by the chat-attach spawn seam (agent/lib/ios/chat-attach-spawn.ts, ADR-0009).
`CLANKIE_FOLLOWUP_RETENTION_DAYS`	Retention window for completed one-time follow-up rows before pruning (default 14 days).
`CLANKIE_FOLLOWUPS`	Set `1` to enable the brain-owned time-based follow-up dispatcher; `/followups` writes this flag and restarts the brain.
`CLANKIE_IOS_WORKSPACE_ID`	Herdr workspace id override for the dedicated iOS chat face workspace (ADR-0009).
`CLANKIE_IOS_WORKSPACE_LABEL`	Label for the iOS chat face workspace (default `Clankie`).
`CLANKIE_LEAD_PHASE_TICK_MS`	Cadence of the orchestration lead-phase debounce probe in ms; run-status settle latency is roughly this times the required quiet probes (default 1500, min 250).
`CLANKIE_LOCAL_USER_ID`	Principal id minted for socket-verified loopback requests (default $USER; frontdoor-auth).
`CLANKIE_ORCHESTRATION`	Set `0` to disable the agent-owned orchestration registry and relay graph stream (on by default).
`CLANKIE_ORCHESTRATION_COMPACT_BYTES`	Orchestration event log size that triggers compaction (default 5 MiB).
`CLANKIE_ORCHESTRATION_GONE_EDGE_RETENTION_MS`	How long an orchestration edge can remain when both endpoint panes are gone before pruning (default 24 hours).
`CLANKIE_ORCHESTRATION_RETENTION_MS`	JSONL event retention window for orchestration log compaction (default 7 days).
`CLANKIE_PANE_SUMMARIES`	Pane summary mode for the orchestration registry: `off` (default), `auto`, or `always`.
`CLANKIE_RELAY_INVOCABLE_SKILLS`	Allowlist gating the garden `skills.invoke` write op: comma/space-separated skill names permitted to run from iOS. Empty/unset disables invocation entirely (`skills.list` still enumerates); a single `*` allows every enumerated skill.
`CLANKIE_RELAY_TOKEN`	Bearer token for the relay WS channel; the relay is fail-closed without it. Encoded into the `clankie pair` QR.
`CLANKIE_RELAY_TRACE`	Set `1` to write relay latency trace logs (write/keys t0 echo).
`CLANKIE_STEER_EDGE_TTL_MS`	How long steered edges stay active since last use before the orchestration graph expires them (default 1800000).
`CLANKIE_SUMMARY_CODEX_EFFORT`	Codex reasoning effort for pane summaries: minimal
`CLANKIE_SUMMARY_COOLDOWN_MS`	Per-pane cooldown after a summary attempt (default 5 minutes).
`CLANKIE_SUMMARY_FAILURE_BACKOFF_TICKS`	Summarizer ticks skipped after the failure threshold is reached (default 3).
`CLANKIE_SUMMARY_FAILURE_THRESHOLD`	Consecutive model failures before the summarizer enters global backoff (default 3).
`CLANKIE_SUMMARY_LOCAL_BASE_URL`	OpenAI-compatible local endpoint for pane summaries; defaults to the local brain endpoint.
`CLANKIE_SUMMARY_LOCAL_EFFORT`	reasoning_effort forwarded to local pane-summary models.
`CLANKIE_SUMMARY_LOCAL_PROVIDER_NAME`	Provider label for the local pane-summary endpoint.
`CLANKIE_SUMMARY_MAX_CONCURRENT`	Maximum concurrent pane summary model generations (default 2).
`CLANKIE_SUMMARY_MAX_INPUT_CHARS`	Tail character budget sent to the pane summary model (default 6000).
`CLANKIE_SUMMARY_MAX_OUTPUT_TOKENS`	Maximum output tokens for a pane summary generation (default 2048).
`CLANKIE_SUMMARY_MAX_PER_TICK`	Maximum pane summaries scheduled per summarizer tick (default 3).
`CLANKIE_SUMMARY_MIN_CONTENT_CHARS`	Minimum sampled pane text before a summary is generated (default 400).
`CLANKIE_SUMMARY_MODEL`	Pane summary model id override; defaults to the selected provider's brain model/default.
`CLANKIE_SUMMARY_PROVIDER`	Pane summary model provider override (`openai`, `codex`, `claude`, `local`, `xai`, or `gemini`); defaults to the active brain provider.
`CLANKIE_SUMMARY_REFRESH_MS`	Minimum age before refreshing an existing changed pane summary (default 7 minutes).
`CLANKIE_SUMMARY_TEMPERATURE`	Sampling temperature for pane summaries (default 0.2).
`CLANKIE_SUMMARY_TICK_MS`	Pane summarizer polling interval (default 60000).

Push notifications (APNs / FCM)

Variable	Description
`CLANKIE_APNS_BUNDLE_ID`	APNs topic / iOS bundle id (default `io.clankie.ios`).
`CLANKIE_APNS_ENV`	APNs environment: `sandbox` (default) or `production`.
`CLANKIE_APNS_KEY`	Legacy alias for CLANKIE_APNS_KEY_PATH.
`CLANKIE_APNS_KEY_ID`	Apple APNs key id (10 chars).
`CLANKIE_APNS_KEY_PATH`	Path to the Apple APNs AuthKey_XXXX.p8 file (token-based auth).
`CLANKIE_APNS_TEAM_ID`	Apple developer team id (10 chars).
`CLANKIE_FCM_CLIENT_EMAIL`	FCM service-account client email (env-only trio).
`CLANKIE_FCM_PRIVATE_KEY`	FCM service-account private key (env-only trio).
`CLANKIE_FCM_PROJECT_ID`	FCM project id (with the env-only credential trio, or overriding the service-account file).
`CLANKIE_FCM_SERVICE_ACCOUNT_PATH`	Path to the FCM service-account JSON (fallback: GOOGLE_APPLICATION_CREDENTIALS).
`CLANKIE_FCM_TOKEN_URI`	OAuth token URI override for FCM (obscure).

Discord presence (text)

Variable	Description
`CLANKIE_DISCORD_ALLOW_DMS`	Set `0` to block DM replies (allowed by default).
`CLANKIE_DISCORD_ALLOWED_CHANNEL_IDS`	Comma/space channel/thread allowlist; empty = any.
`CLANKIE_DISCORD_ALLOWED_GUILD_IDS`	Comma/space server allowlist; empty = any.
`CLANKIE_DISCORD_CREDENTIAL_KIND`	`bot-token` (default) or `user-token` (private calls + Go Live; ToS-gray, opt-in).
`CLANKIE_DISCORD_ENGAGEMENT_WINDOW_MINUTES`	Minutes an active exchange keeps accepting follow-ups without re-tagging.
`CLANKIE_DISCORD_PRESENCE`	Set `1` to start the always-on Discord gateway presence (set by the runtime, not build).
`CLANKIE_DISCORD_TOKEN`	Discord credential (fallback: DISCORD_BOT_TOKEN); bot or user/self token per CLANKIE_DISCORD_CREDENTIAL_KIND.
`CLANKIE_DISCORD_WAKE_NAMES`	Extra wake-name aliases for chat addressing (comma/space list).

Discord voice & ClankVox

Variable	Description
`CLANKIE_CLANKVOX_BIN`	Prebuilt ClankVox binary override; skips source resolution.
`CLANKIE_CLANKVOX_DIR`	ClankVox source checkout override (default sibling `../clankvox`).
`CLANKIE_DISCORD_VOICE`	Set `1` to enable the Discord voice runtime and voice intents.
`CLANKIE_DISCORD_VOICE_CATCH_UP_WINDOW_MS`	Startup replay window for recent voice intents after a restart.
`CLANKIE_DISCORD_VOICE_FAIL_ON_REALTIME_ERROR`	Smoke/test gate: fail instead of degrading on realtime errors (obscure).
`CLANKIE_DISCORD_VOICE_REQUIRE_ALL`	Live-voice acceptance gate: require all checks (test harness, obscure).
`CLANKIE_DISCORD_VOICE_REQUIRE_ASK_PI`	Live-voice acceptance gate (test harness, obscure).
`CLANKIE_DISCORD_VOICE_REQUIRE_GROUP_AUDIO`	Live-voice acceptance gate (test harness, obscure).
`CLANKIE_DISCORD_VOICE_REQUIRE_INPUT_AUDIO`	Live-voice acceptance gate (test harness, obscure).
`CLANKIE_DISCORD_VOICE_REQUIRE_OUTPUT_AUDIO`	Live-voice acceptance gate (test harness, obscure).
`CLANKIE_DISCORD_VOICE_REQUIRE_REALTIME_SESSION`	Live-voice acceptance gate (test harness, obscure).
`CLANKIE_DISCORD_VOICE_REQUIRE_SCREEN_FRAME`	Live-voice acceptance gate (test harness, obscure).
`CLANKIE_DISCORD_VOICE_REQUIRE_STREAM_WATCH`	Live-voice acceptance gate (test harness, obscure).
`CLANKIE_DISCORD_VOICE_REQUIRE_TOOL_CALL`	Live-voice acceptance gate (test harness, obscure).
`CLANKIE_DISCORD_VOICE_WAKE_NAMES`	Wake-name aliases for voice barge-in (defaults to chat wake names).

Voice runtime

Variable	Description
`CLANKIE_ELEVENLABS_BASE_URL`	ElevenLabs API base URL override (obscure).
`CLANKIE_ELEVENLABS_OUTPUT_FORMAT`	ElevenLabs PCM output format override (obscure).
`CLANKIE_ELEVENLABS_SPEED`	ElevenLabs speech speed override (obscure).
`CLANKIE_ELEVENLABS_TTS_MODEL`	ElevenLabs TTS model id.
`CLANKIE_ELEVENLABS_VOICE_ID`	ElevenLabs voice id; presence also infers the TTS provider.
`CLANKIE_VOICE_ASR_COMMAND`	ASR command for the local stack (default whisper-cli).
`CLANKIE_VOICE_ASR_LANGUAGE`	ASR language hint for the local stack (obscure).
`CLANKIE_VOICE_ASR_MODEL`	whisper.cpp ggml model path for the local voice stack.
`CLANKIE_VOICE_AUDIO_SAMPLE_RATE`	Inbound audio sample rate override (obscure).
`CLANKIE_VOICE_EVE_SESSION`	Set `0` to disable the durability eve session behind voice (on by default).
`CLANKIE_VOICE_INSTRUCTIONS`	Override the realtime voice persona instructions.
`CLANKIE_VOICE_LOCAL_API_KEY`	API key for the local voice LLM endpoint, when it requires one.
`CLANKIE_VOICE_LOCAL_BASE_URL`	Local voice LLM endpoint (separate from the conductor's, so voice stays low-latency).
`CLANKIE_VOICE_LOCAL_TTS_COMMAND`	Custom local TTS command (reads text, emits PCM).
`CLANKIE_VOICE_LOCAL_TTS_ENGINE`	Local TTS engine: `say` (macOS) or `command`.
`CLANKIE_VOICE_MEMORY_CONTEXT_LIMIT`	Memory facts injected into voice turns, 0-50 (falls back to CLANKIE_MEMORY_CONTEXT_LIMIT).
`CLANKIE_VOICE_REALTIME_MODEL`	Realtime model id (gpt-realtime / grok-voice-2 / local LLM).
`CLANKIE_VOICE_REALTIME_PROVIDER`	Realtime voice provider: `openai` (default), `xai`, or `local`.
`CLANKIE_VOICE_REALTIME_VOICE`	Provider-native voice name (default `marin`; local default `Samantha`).
`CLANKIE_VOICE_TTS_PROVIDER`	Outbound TTS: `realtime` (provider-native audio) or `elevenlabs`.
`CLANKIE_VOICE_TTS_SAMPLE_RATE`	Outbound TTS sample rate override (obscure).

Media (image / video / vision)

Variable	Description
`CLANKIE_GEMINI_IMAGE_MODEL`	Gemini image model.
`CLANKIE_IMAGE_PROVIDER`	Default image-generation provider: openai
`CLANKIE_OPENAI_IMAGE_MODEL`	OpenAI image model (default gpt-image-2).
`CLANKIE_OPENAI_VISION_MODEL`	Keyed OpenAI fallback vision model for media_inspect (default from config-defaults.ts).
`CLANKIE_VIDEO_PROVIDER`	Video-generation provider (currently xai).
`CLANKIE_VISION_BASE_URL`	Base URL for a local/OpenAI-compatible vision endpoint.
`CLANKIE_VISION_ENABLED`	Set `1` to route media_inspect to a dedicated vision model instead of the brain.
`CLANKIE_VISION_MODEL`	Dedicated vision model id (any provider, e.g. a local Ollama model).
`CLANKIE_VISION_PROVIDER`	Provider for the dedicated vision model.
`CLANKIE_VISION_PROVIDER_NAME`	Provider name label for a local vision endpoint (obscure).
`CLANKIE_XAI_IMAGE_MODEL`	Grok Imagine image model.
`CLANKIE_XAI_VIDEO_MODEL`	Grok Imagine video model.

Workers & coding harnesses

Variable	Description
`CLANKIE_CODEX_OLLAMA_HOME`	Isolated CODEX_HOME for Ollama-launched codex workers so they cannot clobber the subscription worker's ~/.codex.
`CLANKIE_CODING_HARNESS`	Default coding harness profile id (clankie
`CLANKIE_CODING_HARNESS_CLAUDE_LAUNCHER`	claude worker launcher: `default` or `ollama` (family: CLANKIE_CODING_HARNESS__LAUNCHER).
`CLANKIE_CODING_HARNESS_CLAUDE_MODEL`	Model id for the claude worker launcher (family: CLANKIE_CODING_HARNESS__MODEL).
`CLANKIE_CODING_HARNESS_CODEX_LAUNCHER`	codex worker launcher: `default` or `ollama`.
`CLANKIE_CODING_HARNESS_CODEX_MODEL`	Model id for the codex worker launcher.
`CLANKIE_CODING_HARNESS_COMMAND`	Command line for the custom harness profile.
`CLANKIE_CODING_HARNESS_OPENCODE_LAUNCHER`	opencode worker launcher: `default` or `ollama`.
`CLANKIE_CODING_HARNESS_OPENCODE_MODEL`	Model id for the opencode worker launcher.
`CLANKIE_CODING_HARNESS_RUNTIME`	Runtime instruction mode for the custom harness: clankie
`CLANKIE_CODING_HARNESSES`	Allowlist of harnesses Clankie may spawn (`/harness allow` writes it).
`CLANKIE_CONSULTANT_EFFORT`	Consultant binding override: optional reasoning effort for the consult (claude/codex only).
`CLANKIE_CONSULTANT_HARNESS`	Consultant binding override (VUH-605): coding harness/CLI that runs a consult (claude
`CLANKIE_CONSULTANT_MODEL`	Consultant binding override: model id passed to the consultant CLI's --model. Requires CLANKIE_CONSULTANT_HARNESS; unbound leaves the consultant feature inert.
`CLANKIE_DELEGATION_DESIGNER`	Delegation-profile override for the designer role: lead
`CLANKIE_DELEGATION_IMPLEMENTER`	Delegation-profile override for the implementer role: lead
`CLANKIE_DELEGATION_INVESTIGATOR`	Delegation-profile override for the investigator role: lead
`CLANKIE_DELEGATION_SCRIBE`	Delegation-profile override for the scribe role: lead
`CLANKIE_DELEGATION_TESTER`	Delegation-profile override for the tester role: lead
`CLANKIE_HERDR_RUN_ROOT`	Root directory for lead run manifests consumed by the orchestration registry (default `<CLANKIE_HOME>/herdr-runs`).
`CLANKIE_PANE_RECORDER`	Set `1` to run the session-wide pane recorder in the brain (the face sets it for the owned brain inside herdr; `0` opts out). Manual Herdr sessions can also run `clankie recorder start` for their own session.
`CLANKIE_PANE_RECORDER_RECORD_ALL`	Set `1` to byte-record wrapper-covered worker panes too (default: lifecycle-only; the worker transcript owns their bytes).
`CLANKIE_WORKER_GOAL`	Worker goal-mode default, off by default (`/harness goal on
`CLANKIE_WORKER_TRANSCRIPTS`	Worker transcript capture default, on by default (`/harness transcripts on

Face / TUI

Variable	Description
`CLANKIE_FACE_HERDR_PANE_ID`	Internal: herdr pane id of the face, forwarded to the owned brain for placement.
`CLANKIE_FACE_HERDR_TAB_ID`	Internal: herdr tab id of the face, forwarded to the owned brain.
`CLANKIE_FACE_HERDR_WORKSPACE_ID`	Internal: herdr workspace id of the face, forwarded to the owned brain.
`CLANKIE_HEADER`	Show/hide the sticky header (`/layout header` writes it).
`CLANKIE_TUI_INPUT_PLACEMENT`	Chat input placement: top
`CLANKIE_TUI_SPINNER`	Thinking-spinner selection (expo-agent-spinners name, preset, or custom cycle).
`CLANKIE_TUI_SPINNER_RATE_MS`	Spinner cycle dwell in ms (fast
`CLANKIE_TUI_STATUS_PLACEMENT`	Status bar placement: above-input
`CLANKIE_TUI_UNICODE`	Force unicode capability detection for the banner (obscure).
`CLANKIE_TURN_TRACE`	Compact turn trace mode: off

Memory, instructions & approvals

Variable	Description
`CLANKIE_AGENT_MD`	Set `1` to ingest AGENTS.md/agent.md files into instructions (opt-in trusted prompt material).
`CLANKIE_AGENT_MD_ROOT`	Scan start directory for agent instruction files (default: brain cwd).
`CLANKIE_APPROVAL_MODE`	host_command approval mode: `read-only` (default), `auto`, or `yolo` (ADR-0003).
`CLANKIE_AUTO_APPROVE`	Set `1` to run tool calls without approval prompts (`/approvals` writes it).
`CLANKIE_HOST_COMMAND_ROOT`	Default cwd for host_command runs (default `~/dev`).
`CLANKIE_MEMORY_CONTEXT_LIMIT`	Memory facts injected per turn (default 16).
`CLANKIE_PET`	Enable the Petdex pet integration (on/off).
`CLANKIE_PET_PORT`	Petdex runtime port (obscure).
`CLANKIE_PET_TOKEN_PATH`	Petdex update-token path (obscure).
`CLANKIE_POLICY_AUTO_VALIDATION`	Behavior-policy override for automated validation: on/off. When on, workers exhaust automated checks before completion and only block on explicit owner-only gates.
`CLANKIE_POLICY_DESIGN_GATE`	Behavior-policy override for the advisory design gate: on/off. When on, design work routes through the bound design tool where meaningful.
`CLANKIE_POLICY_MERGE_AUTHORITY`	Behavior-policy override for PR merge authority: `auto` or `human`. Human blocks `gh pr merge` and `merge_pull_request`.
`CLANKIE_POLICY_PR_GRANULARITY`	Behavior-policy override for advisory issue-to-PR mapping: unset, per_issue, per_batch, or per_epic.
`CLANKIE_POLICY_PR_ONLY`	Behavior-policy override for PR-only mode: on/off. When on, default-branch pushes are blocked and work routes through PRs.
`CLANKIE_POLICY_PR_REVIEW_ESCALATION`	Behavior-policy override for advisory PR review escalation: on/off. When on, large work stacks into size-capped PRs and PRs wait for external review before lead-spawned review fallback.
`CLANKIE_POLICY_WORKER_SUBAGENTS`	Behavior-policy override for native worker-subagent posture: `encourage`, `allow`, or `linear`.
`CLANKIE_SANDBOX`	Set to `seatbelt` in host_command child processes so scripts can detect the sandbox; never set it yourself.
`CLANKIE_SANDBOX_NETWORK_DISABLED`	Set to `1` in host_command children when network egress is denied; never set it yourself.
`CLANKIE_SKILL_ROOTS`	Additional colon-separated installed skill roots for context-source discovery; symlinks are resolved with realpath.
`CLANKIE_YOLO`	Transient yolo arm for host_command; injected by `/approvals yolo`, never saved here.

Integrations & MCP

Variable	Description
`CLANKIE_BROWSER_BRIDGE_PORT`	Browser-extension bridge daemon port.
`CLANKIE_DESIGN_TOOL`	Role-binding override: connection name bound to the design_tool role.
`CLANKIE_FIGMA_MCP_CLIENT_METADATA_URL`	Figma MCP OAuth client-metadata URL override (obscure).
`CLANKIE_FIGMA_MCP_URL`	Figma hosted MCP URL override (obscure).
`CLANKIE_GITHUB_MCP_URL`	GitHub hosted MCP URL override (obscure).
`CLANKIE_GITHUB_TOKEN`	GitHub personal access token for the curated GitHub MCP connection (paste via /mcp auth github, or set here for headless runs). GITHUB_TOKEN is also accepted.
`CLANKIE_LINEAR_AGENT_ACCESS_TOKEN`	Linear OAuth app token (actor=app) the native Linear Agent channel uses to post Agent Activities and open proactive sessions (agent/channels/linear.ts, ADR-0015).
`CLANKIE_LINEAR_BOT_EMAIL`	Linear email for Clankie's mirror author; optional echo-suppression identity fallback. Without any CLANKIE_LINEAR_BOT_* identity, generic Linear imports fail closed instead of guessing.
`CLANKIE_LINEAR_BOT_NAME`	Linear display name for Clankie's mirror author; optional echo-suppression identity fallback. Without any CLANKIE_LINEAR_BOT_* identity, generic Linear imports fail closed instead of guessing.
`CLANKIE_LINEAR_BOT_USER_ID`	Linear user/app id for Clankie's mirror author; inbound reconciliation treats matching webhook authors as echo reflections. Without any CLANKIE_LINEAR_BOT_* identity, generic Linear imports fail closed instead of guessing.
`CLANKIE_LINEAR_MCP_CLIENT_METADATA_URL`	Linear MCP OAuth client-metadata URL override (obscure).
`CLANKIE_LINEAR_MCP_URL`	Linear hosted MCP URL override (obscure).
`CLANKIE_LINEAR_OWNER_HANDLE`	Linear owner mention handle (without @) used by the Linear connection guidance for first-touch owner notifications.
`CLANKIE_LINEAR_PROJECT`	Optional Linear project (name or id) the outbound mirror engine files projected issues into.
`CLANKIE_LINEAR_TEAM`	Linear team (name or id) the outbound mirror engine creates projected issues under; required to mirror to Linear. Absent = create projections degrade to `mirror_sync_skipped`.
`CLANKIE_LINEAR_WEBHOOK_SECRET`	Signing secret that verifies inbound Linear AgentSessionEvent webhooks (Linear-Signature HMAC) at /eve/v1/linear.
`CLANKIE_MCP_SERVERS`	JSON of runtime-added no-auth/static-token MCP servers, merged with ~/.clankie/mcp-servers.json.
`CLANKIE_PR_LINE_LIMIT`	Preferred maximum changed lines per pull request; `/integrations version-control pr-line-limit` writes it (default 5,000).
`CLANKIE_VERSION_CONTROL`	Role-binding override: connection name bound to the version_control role.
`CLANKIE_WORK_TRACKER`	Work-tracker mirror override: comma/space-separated external connections the fixed native store projects to (e.g. `linear`). `native` is never a mirror; the list is deduped; empty/`none` means native-only (ADR-0013 / VUH-440).
`CLANKIE_WORKTRACKER_ARCHIVE_AFTER_DAYS`	Native work-tracker retention policy: terminal issues (`done`/`canceled`) older than this many days are marked archived on store open and hidden from active list/search by default. Default 180; <=0 disables archival.
`CLANKIE_WORKTRACKER_MIRROR`	Set `1` to run the outbound mirror projection engine: native-store events write through to each bound work-tracker mirror (agent/lib/worktracker/mirror.ts, ADR-0013 / VUH-483). Off = the native store is authoritative but nothing is projected.
`CLANKIE_WORKTRACKER_PRESENCE`	Set `1` to run the native work-tracker conversational loop in the brain: a human comment on a native issue gets a Clankie reply in-thread (agent/channels/worktracker.ts, ADR-0013 / SPEC §5.7). Off = notes are recorded but Clankie does not reply.

Usage ledger

Variable	Description
`CLANKIE_USAGE_COMPACT_BYTES`	Byte size at which the usage-ledger log is compacted/rewritten (default 32 MiB).
`CLANKIE_USAGE_RETENTION_MS`	Usage-ledger retention window in ms; events older than this are dropped on compaction (default 45 days).

Dev & test

Variable	Description
`CLANKIE_SMOKE_TIMEOUT_MS`	Per-test timeout for the `pnpm smoke` aggregate (default 120000).
`CLANKIE_WORKFLOW_RETENTION_HOURS`	Retention window for eve dev local workflow data pruning before Clankie starts an owned brain (default 48; <=0 disables).