Configuration

Precedence

Kent resolves settings in this order (higher no. = higher priority):

1. Built-in defaults
2. ~/.kent/config.toml
3. <workspace-root>/.kent/config.toml
4. Environment variables
5. kent run CLI flags

Interactive session flows resolve workspace-local config from the session workspace root. kent serve starts without a workspace root and applies workspace config only when a project/session selects a workspace. kent run is the only entrypoint that accepts config override flags.

Locations

Persistence root

Global settings live at:

~/.kent/config.toml

Workspace settings live at:

<workspace-root>/.kent/config.toml

Kent also installs a user-editable ripgrep config at:

~/.kent/rg.conf

Kent creates ~/.kent/rg.conf when missing and exports it to shell tools via RIPGREP_CONFIG_PATH only when you have not already set RIPGREP_CONFIG_PATH yourself.

Changing persistence_root does not move either config file. persistence_root controls where Kent stores its database & auth state. The default is ~/.kent.

Example

model = "gpt-5.5"
thinking_level = "medium" # low, medium, high, xhigh
model_verbosity = "medium" # or "low"
# system_prompt_file = "SYSTEM.md" # relative to this config.toml directory
theme = "auto" # or light / dark
web_search = "native"
compaction_mode = "local" # or "native" (if supported)
cache_warning_mode = "default" # cache invalidation messages; or "verbose" / "off"
server_host = "127.0.0.1" # kent local server config
server_port = 53082

[timeouts]
model_request_seconds = 400

[tools]
shell = true
# Leave both patch/edit commented to use Kent's model-based default.
# patch = true
# edit = false
view_image = true
web_search = true
trigger_handoff = true # proactive compaction by the model

[shell]
postprocessing_mode = "all" # shell output token optimizations by Kent, or "all" | "none" | "user"
# postprocess_hook = "~/.kent/shell_postprocess_hook" # custom postprocess_hook, see docs

[skills]
"skill name" = true

[reviewer] # aka supervisor
frequency = "edits"
# model = "gpt-5.4-mini"
# model_verbosity = "low"
# provider_override = "openai"
# openai_base_url = "http://127.0.0.1:11434/v1"
# auth = "none" # or "inherit"
# model_context_window = 64000
timeout_seconds = 60
verbose_output = false # show in ongoing transcript
# system_prompt_file = "~/.kent/reviewer_system_prompt.md"

# custom subagent roles config, fast is the default one, always provided
[subagents.fast]
# agent_callable = true
# description = ""
# model = "gpt-5.4-mini"
# priority_request_mode = true

CLI Overrides

Flag	Overrides	Notes
kent run --model	model
kent run --provider-override	provider_override
kent run --thinking-level	thinking_level
kent run --theme	theme
kent run --model-timeout-seconds	timeouts.model_request_seconds
kent run --tools	entire tool set	CSV replacement, not a merge
kent run --openai-base-url	openai_base_url	Also affects continuation behavior

kent run also accepts the headless-only selectors --agent <role> and --fast, which choose a subagent role rather than directly overriding one config key.

Reference

Core Settings

Key	Type	Default	Env	CLI	Description
model	string	gpt-5.5	KENT_MODEL	kent run --model	Model name. If provider inference from the model name is not enough, set provider_override too.
thinking_level	string	medium	KENT_THINKING_LEVEL	kent run --thinking-level	Provider-specific reasoning effort string.
model_verbosity	string	medium			Text verbosity hint for supported models. Allowed: "", low, medium, high. Unsupported models ignore it.
system_prompt_file	string	""			Main system prompt file. Relative paths resolve from the containing config.toml directory. Empty files are skipped.
theme	string	auto	KENT_THEME	kent run --theme	TUI theme. Allowed: auto, light, dark. light and dark force Kent’s fixed palettes. auto or an omitted value falls back to terminal background detection.
notification_method	string	auto	KENT_NOTIFICATION_METHOD		Terminal notification backend. Allowed: auto, osc9, bel. auto chooses osc9 on supported terminals and falls back to bel.
tool_preambles	bool	true	KENT_TOOL_PREAMBLES		Includes tool-usage preambles in the main system prompt for interactive runs. Headless kent run still suppresses them.
priority_request_mode	bool	false			Enables fast-mode requests where the provider supports them.
debug	bool	false	KENT_DEBUG		Enables global developer-oriented strictness and logging. Only use for development/debugging
server_host	string	127.0.0.1	KENT_SERVER_HOST		Exact TCP app-server host Kent will dial or listen on. Kent does not use discovery files or silent port rebinding. Same-machine Unix socket optimization, when supported, is derived automatically and does not override an explicit TCP target.
server_port	int	53082	KENT_SERVER_PORT		Exact TCP app-server port Kent will dial or listen on. Must match across clients attached to the same persistence root. Same-machine Unix socket optimization, when supported, is additive only and does not override an explicit TCP target.
web_search	string	native	KENT_WEB_SEARCH		Web search backend. Allowed: off, native. custom (e.g. Brave Search) is not implemented yet, on the roadmap.
provider_override	string	""	KENT_PROVIDER_OVERRIDE	kent run --provider-override	Forces provider family for custom or alias model names. Allowed: openai, anthropic. Requires an explicit model override.
openai_base_url	string	""	KENT_OPENAI_BASE_URL	kent run --openai-base-url	OpenAI-compatible base URL. Must be used with provider_override=openai or with no explicit provider override. Cannot be changed mid-session.
store	bool	false	KENT_STORE		Sets OpenAI Responses store=true for main model requests.
allow_non_cwd_edits	bool	false	KENT_ALLOW_NON_CWD_EDITS		Lets first-class file edit tools edit files outside the workspace root. This is not sandboxing - model can still bypass this easily.
model_context_window	int	272000	KENT_MODEL_CONTEXT_WINDOW		Explicit context-window size used for compaction and token accounting. Must be > 0.
context_compaction_threshold_tokens	int	258400	KENT_CONTEXT_COMPACTION_THRESHOLD_TOKENS		Auto-compaction threshold. Must be > 0, < model_context_window, and at least 50% of model_context_window. The default is derived from the default context window.
pre_submit_compaction_lead_tokens	int	35000	KENT_PRE_SUBMIT_COMPACTION_LEAD_TOKENS		Fixed pre-submit runway reserve before auto-compaction. Kent compacts before sending the next user prompt once (context_compaction_threshold_tokens - this threshold) is reached.
minimum_exec_to_bg_seconds	int	15	KENT_MINIMUM_EXEC_TO_BG_SECONDS		Default floor for exec_command yield time before it moves to background and lets Kent manage it asynchronously. Must be > 0. Use if model frequently expects your commands to complete fast, they background, and force model to poll for them.
compaction_mode	string	local	KENT_COMPACTION_MODE		Allowed: native, local, none. native prefers provider-native compaction and falls back to local compaction. local always uses local summary compaction. none disables auto-compaction and makes manual compaction fail.
cache_warning_mode	string	default	KENT_CACHE_WARNING_MODE		Prompt-cache warning policy. Allowed: off, default, verbose. default catches unwanted invalidations and keeps them in detail mode. verbose includes everything from default, surfaces cache warnings in ongoing mode too, and a broader range of warnings.
shell_output_max_chars	int	16000	KENT_SHELL_OUTPUT_MAX_CHARS		Output budget for shell tools and background-shell notices before they are truncated.
bg_shells_output	string	default	KENT_BG_SHELLS_OUTPUT		Background-shell output mode (injection of shell outputs into model context). Allowed: default, verbose, concise. Verbose dumps all output into the main agent’s model. Concise forces it to read output files. Default outputs truncated previews + gives a file path.
shell.postprocessing_mode	string	builtin	KENT_SHELL_POSTPROCESSING_MODE		Semantic post-processing mode for exec_command. Allowed: none, builtin, user, all. builtin enables Kent processors only. all runs Kent processors first, then your hook.
shell.postprocess_hook	string	""	KENT_SHELL_POSTPROCESS_HOOK		Optional executable/script path for a single local command post-processing hook. Kent sends JSON on stdin and expects JSON on stdout.
prevent_sleep	string	active	KENT_PREVENT_SLEEP		Prevent system sleep while Kent is running. Allowed: always (while the server process is live), active (while any agent is working, plus up to one minute of idle-confirmation grace), never (disabled). Only system sleep is inhibited; screensaver and display sleep are unaffected.
persistence_root	string	~/.kent	KENT_PERSISTENCE_ROOT		Root for auth, session, and workspace index storage. Does not change the location of ~/.kent/config.toml.

Timeouts

Key	Type	Default	Env	CLI	Description
timeouts.model_request_seconds	int	400	KENT_TIMEOUTS_MODEL_REQUEST_SECONDS	kent run --model-timeout-seconds	HTTP timeout for model requests. Must be > 0.

Supervisor

Configure the supervisor agent that oversees model changes.

Key	Type	Default	Env	Description
reviewer.frequency	string	edits	KENT_REVIEWER_FREQUENCY	Allowed: off, all, edits. all runs the reviewer after every completed assistant turn. edits runs it only after successful first-class file edits.
reviewer.model	string	inherits model	KENT_REVIEWER_MODEL	Separate model for the reviewer pass. If unset, Kent uses main model.
reviewer.thinking_level	string	inherits thinking_level	KENT_REVIEWER_THINKING_LEVEL	Allowed: low, medium, high, xhigh.
reviewer.model_verbosity	string	inherits model_verbosity	KENT_REVIEWER_MODEL_VERBOSITY	Text verbosity hint for supported reviewer models. Allowed: "", low, medium, high.
reviewer.provider_override	string	inherits provider_override	KENT_REVIEWER_PROVIDER_OVERRIDE	Forces provider family for the reviewer model. Allowed: openai, anthropic.
reviewer.openai_base_url	string	inherits openai_base_url for OpenAI-family reviewer providers	KENT_REVIEWER_OPENAI_BASE_URL	OpenAI-compatible base URL for the reviewer model. Non-OpenAI endpoints can run without Kent auth when the server accepts anonymous requests.
reviewer.auth	string	inherit	KENT_REVIEWER_AUTH	Reviewer auth policy. inherit uses Kent’s configured auth. none sends no Authorization header; providers that require auth return their normal runtime error.
reviewer.model_context_window	int	inherits model_context_window	KENT_REVIEWER_MODEL_CONTEXT_WINDOW	Explicit reviewer context-window size sent to the reviewer provider.
reviewer.system_prompt_file	string	""		Path to a custom supervisor system prompt file. Relative paths resolve from the config file directory. Workspace config overrides global config; no CLI or environment override is provided.
reviewer.timeout_seconds	int	60	KENT_REVIEWER_TIMEOUT_SECONDS	Reviewer HTTP timeout. Must be > 0.
reviewer.verbose_output	bool	false	KENT_REVIEWER_VERBOSE_OUTPUT	Controls whether reviewer suggestion text is shown at all. When false, Kent only shows the concise reviewer result/status line. When true, Kent shows the full suggestion list at the moment the reviewer issues it, and the later reviewer status stays concise after the follow-up is applied or ignored.

Supervisor Capability Overrides

Use these for custom reviewer models or reviewer providers when the built-in registry is not enough.

Key	Type	Default	Env	Description
reviewer.model_capabilities.supports_reasoning_effort	bool	inherits model_capabilities.supports_reasoning_effort	KENT_REVIEWER_MODEL_CAPABILITIES_SUPPORTS_REASONING_EFFORT	Override-marks the reviewer model as supporting reasoning effort / thinking levels.
reviewer.model_capabilities.supports_vision_inputs	bool	inherits model_capabilities.supports_vision_inputs	KENT_REVIEWER_MODEL_CAPABILITIES_SUPPORTS_VISION_INPUTS	Marks the reviewer model as supporting multimodal image and PDF inputs.
reviewer.provider_capabilities.provider_id	string	inherits provider_capabilities.provider_id	KENT_REVIEWER_PROVIDER_CAPABILITIES_PROVIDER_ID	Required whenever you set reviewer provider capability overrides.
reviewer.provider_capabilities.supports_responses_api	bool	inherits provider_capabilities.supports_responses_api	KENT_REVIEWER_PROVIDER_CAPABILITIES_SUPPORTS_RESPONSES_API	Marks the reviewer provider as supporting the Responses API.
reviewer.provider_capabilities.supports_responses_compact	bool	inherits provider_capabilities.supports_responses_compact	KENT_REVIEWER_PROVIDER_CAPABILITIES_SUPPORTS_RESPONSES_COMPACT	Marks the reviewer provider as supporting server-side compaction.
reviewer.provider_capabilities.supports_request_input_token_count	bool	inherits provider_capabilities.supports_request_input_token_count	KENT_REVIEWER_PROVIDER_CAPABILITIES_SUPPORTS_REQUEST_INPUT_TOKEN_COUNT	Marks the reviewer provider as supporting exact request input-token counting.
reviewer.provider_capabilities.supports_prompt_cache_key	bool	inherits provider_capabilities.supports_prompt_cache_key	KENT_REVIEWER_PROVIDER_CAPABILITIES_SUPPORTS_PROMPT_CACHE_KEY	Marks the reviewer provider as accepting prompt cache keys.
reviewer.provider_capabilities.supports_native_web_search	bool	inherits provider_capabilities.supports_native_web_search	KENT_REVIEWER_PROVIDER_CAPABILITIES_SUPPORTS_NATIVE_WEB_SEARCH	Marks the reviewer provider as supporting native web search.
reviewer.provider_capabilities.supports_reasoning_encrypted	bool	inherits provider_capabilities.supports_reasoning_encrypted	KENT_REVIEWER_PROVIDER_CAPABILITIES_SUPPORTS_REASONING_ENCRYPTED	Marks the reviewer provider as supporting encrypted reasoning items.
reviewer.provider_capabilities.supports_server_side_context_edit	bool	inherits provider_capabilities.supports_server_side_context_edit	KENT_REVIEWER_PROVIDER_CAPABILITIES_SUPPORTS_SERVER_SIDE_CONTEXT_EDIT	Marks the reviewer provider as supporting server-side context editing.
reviewer.provider_capabilities.is_openai_first_party	bool	inherits provider_capabilities.is_openai_first_party	KENT_REVIEWER_PROVIDER_CAPABILITIES_IS_OPENAI_FIRST_PARTY	Marks the reviewer provider as first-party OpenAI semantics.

Model Capability Overrides

Use these only for custom or alias models when the built-in model registry is not enough.

Key	Type	Default	Env	Description
model_capabilities.supports_reasoning_effort	bool	false	KENT_MODEL_CAPABILITIES_SUPPORTS_REASONING_EFFORT	Override-marks the configured model as supporting reasoning effort / thinking levels.
model_capabilities.supports_vision_inputs	bool	false	KENT_MODEL_CAPABILITIES_SUPPORTS_VISION_INPUTS	Marks the configured model as supporting multimodal image and PDF inputs.

If both values stay false, Kent falls back to the built-in model capability registry.

Provider Capability Overrides

Use these only for custom providers or models.

Key	Type	Default	Env	Description
provider_capabilities.provider_id	string	""	KENT_PROVIDER_CAPABILITIES_PROVIDER_ID	Required whenever you set provider capability overrides.
provider_capabilities.supports_responses_api	bool	false	KENT_PROVIDER_CAPABILITIES_SUPPORTS_RESPONSES_API	Marks the provider as supporting the Responses API.
provider_capabilities.supports_responses_compact	bool	false	KENT_PROVIDER_CAPABILITIES_SUPPORTS_RESPONSES_COMPACT	Marks the provider as supporting server-side compaction.
provider_capabilities.supports_native_web_search	bool	false	KENT_PROVIDER_CAPABILITIES_SUPPORTS_NATIVE_WEB_SEARCH	Marks the provider as supporting native web search.
provider_capabilities.supports_reasoning_encrypted	bool	false	KENT_PROVIDER_CAPABILITIES_SUPPORTS_REASONING_ENCRYPTED	Marks the provider as supporting encrypted reasoning items.
provider_capabilities.supports_server_side_context_edit	bool	false	KENT_PROVIDER_CAPABILITIES_SUPPORTS_SERVER_SIDE_CONTEXT_EDIT	Marks the provider as supporting server-side context editing.
provider_capabilities.is_openai_first_party	bool	false	KENT_PROVIDER_CAPABILITIES_IS_OPENAI_FIRST_PARTY	Marks the provider as first-party OpenAI semantics, which gates some Responses-specific behavior such as fast mode and phase protocol features.

Tools

[tools] is a per-tool boolean table in config.toml. File-based tool toggles merge with defaults. KENT_TOOLS and kent run --tools behave differently: they replace the entire tool set with the CSV you provide.

Key	Default	What enabling it exposes
tools.ask_question	true	Tool to ask interactive questions
tools.shell	true	The primary shell tool. Internally this maps to exec_command.
tools.patch	dynamic	Freeform patch grammar edit tool
tools.edit	dynamic	JSON text replacement/create/delete edit tool
tools.trigger_handoff	false	Experimental tool the agents can use to proactively compact their own context.
tools.view_image	true	Ability to view PNG, JPEG, still GIF, and PDF files (if supported)
tools.web_search	true	Tool to search the web
tools.write_stdin	true	Interaction with background shells.

Notes:

• tools.web_search = true does not force web search on. Native search still depends on web_search = "native" and provider support.
• tools.patch and tools.edit are mutually exclusive. If both are left at their defaults, Kent chooses patch for first-party OpenAI providers or gpt-* model names, and edit otherwise.
• To force edit, set edit = true and patch = false.

Subagents

[subagents.<role>] is a file-only table for named headless subagent roles. Fast is always-present, but you can add custom agents here.

Subagent roles inherit the main config and then override only the keys set in that role table. Set system_prompt_file inside a subagent role to use a role-specific main system prompt for kent run --agent <role>. Set description to describe a behaviorally distinct role to other agents. Set agent_callable = false for roles that humans may run explicitly but agents should not call from Kent sessions.

More info on the Subagents page.

Skills

[skills] is a file-only per-skill boolean table in config.toml to disable unneeded skills. Keys are matched case-insensitively.

[skills]
"<skill name>" = true # | false

Notes:

• Skill toggles are only applied when Kent creates a new conversation/session.
• Use "quoted names" to refer to skill keys containing spaces.
• Preinstalled skills are seeded into ~/.kent/.generated/skills; disable them here instead of editing generated files.