Configuration

Precedence

Kent resolves settings in this order (ascending priority):

1. Built-in defaults
2. ~/.kent/config.toml
3. <workspace-root>/.kent/config.toml
4. <main-workspace-root>/.kent/config.local.toml
5. Environment variables
6. CLI overrides

Each explicitly supplied property overrides the same property from earlier layers. Omitted properties inherit, including within named roles and nested tables. An explicit false overrides true.

The private config.local.toml is read from the main workspace when using worktrees. Shared config.toml, on the other hand, follows the operation’s workspace or working-directory context.

Connection discovery is an exception - for provider connection declarations, Kent reads global configuration to keep provider access private to that installation. See Authentication and connections.

See Grok support for subscription routes and sign-in diagnostics.

The default and session-producing roles accept a connection name or an array of equivalent connection names. See connection sets for assignment, saved-session behavior, and the supervisor’s single-name override.

Some cache-affecting settings like prompts, tools, and model IDs, are snapshot at session start and re-loaded at compaction. This is done to preserve the prompt cache.

Locations

Persistence root

• Workspace settings live at: <workspace-root>/.kent/config.toml. Note that workspace root is not necessarily the same as where you might have started the TUI - it’s where the agent will actually do the work.
• Private settings live at <main-workspace-root>/.kent/config.local.toml. The file is optional and accepts workspace-allowed settings. Keep personal overrides uncommitted using your own Git ignore configuration; Kent does not change Git rules or copy this file into worktrees.
• Global settings live at: ~/.kent/config.toml, and this location (along with all other data storage) is overridable via --persistence-root. The flag also relocates the root’s model-visible global context — global AGENTS.md, the global system-prompt file, global skills, and generated assets. kent service is also root-aware. Each --persistence-root install bakes the root into the registration. The OS still holds a single service, so install with the root you want managed.

Example

model = "gpt-6-astra"
connection = "codex-1"
provider_identifier = "kent"
thinking_level = "medium" # low, medium, high, xhigh, max, ultra
model_verbosity = "low" # or "medium" / "high"
max_subagent_depth = 2 # 0 through 30; 0 blocks subagent creation completely
# 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 warning visibility; or "verbose" / "off"
server_host = "127.0.0.1"
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: none | builtin | user | all
# postprocess_hook = "~/.kent/shell_postprocess_hook" # custom processor, see docs

[hooks.client]
# see respective docs page
# lifecycle = ["python3", "/absolute/path/lifecycle_hook.py"]

[workflow]
completion_mode = "auto"
concurrency = 5 # max agents to run concurrently for workflows; Script Nodes / Chats do not use it
max_invalid_completion_attempts = 5
pre_compaction_tokens = 247380 # defaults to 70% of context_compaction_threshold_tokens
use_required_tool_calls = true # whether to force models to never stop until workflow is complete on the API level
subagents = false # disables all workflow-agent delegation

[skills]
"skill name" = true

# Headless default role; new interactive TUI and Desktop Sessions use the top-level settings.
[subagents.default]
model = "gpt-6-astra"
thinking_level = "low"
description = "Low-cost role for headless runs."
max_subagent_depth = 1 # allow/deny subagent launches by this role
agent_callable = false # model agents cannot delegate to this role
workflow_subagent = false # Workflow agents cannot delegate to this role

Workflow subagent delegation

[workflow] subagents defaults to false. Set it to true to let Workflow agents delegate to roles whose effective agent_callable and workflow_subagent values allow it. This setting does not affect direct Workflow Node assignment, including an assignment to default.

agent_callable is optional role metadata and defaults to true. It controls whether model-originated child delegation may target the role, including the default role; humans can launch the role with kent run regardless of this value.

workflow_subagent is optional role metadata and defaults to true. Every role, including default and fast, is callable by a Workflow agent only when its effective agent_callable and workflow_subagent values and [workflow] subagents = true all permit it.

Thinking

Thinking selects the model’s reasoning effort. Change it in Chat settings or with /thinking <level>. Available levels depend on the model and provider.

A session’s thinking override takes precedence over its agent configuration and global thinking_level.

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

Reference

Core Settings

Key	Type	Default	Env	CLI	Description
model	string	gpt-6-astra	KENT_MODEL	kent run --model	Model name. If provider inference from the model name is not enough, set provider_override too.
max_subagent_depth	int	2			Max subagent depth, between 0 and 30. Interactive and workflow sessions start at depth 0. 0 disables subagent launches for a role, or by default when set globally. 1 will only allow subagent launches by top-level sessions and Workflow tasks, but not sub-subagents. Higher values allow subagents of subagents, up to and including the selected depth. Set max_subagent_depth under [subagents.<role>] to override the global default.
thinking_level	string	medium	KENT_THINKING_LEVEL	kent run --thinking-level	Provider-specific reasoning effort string.
model_verbosity	string	low			Text verbosity hint for supported models. Allowed: "", low, medium, high. Unsupported models ignore it.
system_prompt_file	optional string	unset			Selected custom main prompt file. Relative paths resolve from the supplying configuration file. Higher layers replace the selection; an empty path is invalid.
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.
tui_native_progress_bar	bool	true			Emits terminal-native indeterminate progress for eligible interactive TUI operations.
hooks.client.lifecycle	string array	unset			Global-only command and fixed arguments for interactive TUI lifecycle hooks.
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 to dial or listen on; client connection discovery follows the exception above. Kent does not use discovery files or silent port rebinding.
server_port	int	53082	KENT_SERVER_PORT		Exact TCP app-server port to dial or listen on; client connection discovery follows the exception above. Must match across clients attached to the same persistence root. Same-machine Unix socket optimization does not override an explicit TCP target.
web_search	string	native	KENT_WEB_SEARCH		Web search backend. Allowed: off, native.
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.
provider_identifier	string	kent	KENT_PROVIDER_IDENTIFIER		Sets the originator header and the <provider_identifier>/<Kent version> User-Agent on OpenAI, ChatGPT Codex, and OpenAI-compatible model-provider requests. The value must be a non-empty HTTP product token, such as kent, my-agent, or acme_codex. A restarted server applies the active value to resumed sessions.
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 Session’s CWD. The native file tools already allow targets under operating-system temporary roots and their canonical platform aliases without approval; This is not sandboxing - the model can still bypass this easily.
model_context_window	int	372000	KENT_MODEL_CONTEXT_WINDOW		Explicit context-window size used for compaction and token accounting. Must be at least 40000, Kent does not support smaller windows.
context_compaction_threshold_tokens	int	353400	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 records confirmed prefix invalidations and reuse disappearance in detail mode. verbose surfaces the same warnings in ongoing mode. off disables them.
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.
shell.postprocess_hook	optional string	unset	KENT_SHELL_POSTPROCESS_HOOK		Executable/script path for a single local command post-processing hook.
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.
timeouts.model_request_seconds	int	400	KENT_TIMEOUTS_MODEL_REQUEST_SECONDS	kent run --model-timeout-seconds	Model request timeout. Most requests are streaming, this only binds stalled requests, so healthy streaming can run for longer than this value.

Workflow

Key	Type	Default	Env	Description
workflow.completion_mode	string	auto	KENT_WORKFLOW_COMPLETION_MODE	Default completion mode for workflow agent nodes that inherit the global default. Allowed: auto, structured_output, tool, shell_command, unstructured_output.
workflow.concurrency	int	5	KENT_WORKFLOW_CONCURRENCY	Agent Node scheduling capacity. Explicit workflow actions may exceed it. Script Nodes do not use it. Must be > 0.
workflow.max_invalid_completion_attempts	int	5	KENT_WORKFLOW_MAX_INVALID_COMPLETION_ATTEMPTS	Number of invalid workflow completion attempts allowed before Kent interrupts the run. Must be > 0.
workflow.pre_compaction_tokens	int	70% of context_compaction_threshold_tokens, rounded down		Workflow Session pre-compaction threshold. Must be positive and no greater than context_compaction_threshold_tokens. See workflow documentation for more info.
workflow.use_required_tool_calls	bool	true		Uses provider-required tool selection for tool and shell_command workflow completion modes. Set to false to use automatic tool selection while preserving Kent’s workflow completion validation.
workflow.subagents	bool	false		Allows workflow agents to delegate to eligible roles, including default and fast.

Nano and supervisor models

See Nano, Supervisor, and Decision models for usage and the [nano] and [reviewer] configuration reference.

Model Capability Overrides

Sometimes you will use a model not yet added to Kent’s model registry. In that case Kent will default to safe settings of what it supports, like no vision or native compaction. Adjust the overrides to let kent know the capabilities the model supports.

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	model/provider default	KENT_MODEL_CAPABILITIES_SUPPORTS_VISION_INPUTS	Overrides support for multimodal image and PDF inputs.

Speech input

Desktop speech uses speech-capable connections selected by the top-level connection setting in global ~/.kent/config.toml. Select multiple connections there to use Kent’s shared connection selection for transcription requests.

Set speech_to_text_model inside [connections.<id>] in that global file to choose a transcription model for OpenAI API or Grok. Codex subscriptions ignore this setting and use their fixed transcription endpoint.

Provider Capability Overrides

Use these only for custom providers or models (such as local 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.supports_provider_verbosity	bool	false	KENT_PROVIDER_CAPABILITIES_SUPPORTS_PROVIDER_VERBOSITY	Controls Responses text.verbosity for unknown models; known models use catalog facts.
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	task-dependent	Tool to ask humans interactive questions. Mandatory for workflows.
tools.shell	true	The primary shell tool.
tools.patch	model-dependent	Freeform patch grammar edit tool for models trained on it (like the GPT family)
tools.edit	model-dependent	JSON text replacement/create/delete edit tool. Intended for models that are not trained to use patch syntax.
tools.trigger_handoff	true	Tool agents can use to proactively compact their own context.
tools.view_image	model-dependent	Ability to view PNG, JPEG, still WebP, still GIF, and PDF files (if supported)
tools.web_search	provider-dependent	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 models that are trained on freeform patch syntax, otherwise edit. To force edit, set edit = true and patch = false.

Concurrent shells

Set shell.max_concurrent in the global configuration to limit running agent-tool shells across the server to prevent overload. The default is 100.

Ripgrep config

Kent also installs an optimized, editable ripgrep config at:

~/.kent/rg.conf

Kent creates rg.conf in the config+data root when missing and exports it to shell tools via RIPGREP_CONFIG_PATH only when you have not already set RIPGREP_CONFIG_PATH yourself.

Subagents

[subagents.<role>] is a table for headless role settings. default is always available and is selected for a new headless kent run when no other role is selected and --agent is omitted or set to default; fast is also built in, and other roles are user-defined. Role tables inherit the base settings and override only keys set in that role. Definitions of the same role merge across global, shared and private files. Ordinary environment and CLI agent settings override the selected role’s declarations.

More info on the Subagents page.

Skills

[skills] is a file-only per-skill boolean table in config.toml. Disabled skills are hidden from models. Keys are matched case-insensitively.

If multiple paths resolve to the same SKILL.md, the first discovered valid entry controls that file. Later aliases are duplicates; enabling another alias does not bypass the first entry’s disabled setting.

[skills]
"<skill name>" = false

[subagents.worker.skills]
"<skill name>" = false

Notes:

• [subagents.<role>.skills] overlays per-skill toggles for that role.
• Use "quoted names" to refer to skill keys containing spaces.