Selesai stores settings as JSON in two files: ~/.selesai/agent/settings.json (global, applies to every project) and .selesai/settings.json (project, overrides global for the current directory). Edit the files directly, or run /settings inside a session to change common options interactively.
This page covers the settings most people actually touch. The exhaustive reference lives in docs/settings.md on GitHub, and per-extension options are on the Customization page.
Model
Setting
Type
Default
What it does
defaultProvider
string
—
Default provider, e.g. "anthropic" or "openai".
defaultModel
string
—
Default model ID used for new sessions.
defaultThinkingLevel
string
—
How much the agent thinks before answering: "off", "minimal", "low", "medium", "high", or "xhigh".
enabledModels
string[]
—
Model patterns for Ctrl+P cycling, e.g. ["claude-*"].
Tools
Setting
Type
Default
What it does
defaultTools
string[]
—
Initial built-in tool selection for new sessions. When set, new sessions start with only these tools enabled (useful alongside the SDK); when omitted, the default read, bash, edit, write are used.
Appearance
Setting
Type
Default
What it does
theme
string
"dark"
"dark", "light", or a custom theme name. You can also set an initial theme for a single run with --use-theme <name>.
quietStartup
boolean
false
Hide the keybinding help and loaded-resources listing for a calmer launch. The brand banner always appears and dismisses on your first message.
tuiMode
string
"fullscreen"
"fullscreen" (default dock layout) or "regular" (classic Pi layout).
fullscreenExitOutput
string
"transcript"
What happens on exit from fullscreen: print the transcript ("transcript") or only a session resume hint ("resume-hint").
fullscreenCopyOnSelect
boolean
true
Automatically copy selected text in fullscreen mode; disable to copy selections with Ctrl+X.
Context
Setting
Type
Default
What it does
compaction.enabled
boolean
true
Auto-compact old context when a conversation grows large.
compaction.reserveTokens
number
16384
Tokens kept free for the model’s reply.
compaction.keepRecentTokens
number
20000
Recent tokens that are never summarized.
Trust and safety
Setting
Type
Default
What it does
defaultProjectTrust
string
"ask"
Fallback for trusting a project in non-interactive runs: "ask", "always", or "never". Global setting only.
Images & vision
When the active model can’t see images (e.g. a text-only DeepSeek model), you can route images
to a vision model that describes them as text. Set the caption model and its context budget in
/settings (“Vision caption model” / “Vision context tokens”) or via these settings:
Setting
Type
Default
What it does
images.imageCaptionModel
string
unset
Vision model (provider/model) used to describe images when the main model can’t accept them, e.g. "tokenin/gemma-4". Unset (or "off") disables captioning.
images.imageCaptionContextTokens
number
16384
Max token budget (approx) for the recent-conversation context sent to the vision model. Messages are kept whole (cut at message boundaries only); the user’s current prompt is always included. 0 sends no prior conversation.
images.autoResize
boolean
true
Resize images to 2000×2000 max for model compatibility.
images.blockImages
boolean
false
Prevent images from being sent to any LLM.
terminal.images
string
"auto"
Terminal image protocol: "kitty", "iterm2", "auto", or false to disable inline images.
terminal.trueColor
boolean/string
"auto"
Pin true-color support (true/false) or keep "auto" detection.
terminal.hyperlinks
boolean/string
"auto"
Pin hyperlink support (true/false) or keep "auto" detection.
Extensibility
Setting
Type
Default
What it does
packages
array
[]
npm/git packages that load extensions, skills, prompts, and themes.
extensions
string[]
[]
Local extension files or directories to load.
skills
string[]
[]
Additional skill files or directories, or explicit +/- patterns. Normal discovery automatically loads skills from ~/.selesai/agent/skills/, ~/.agents/skills/, .selesai/skills/, and project/ancestor .agents/skills/ directories, so this setting is not required for ordinary skills.
Where things live
Location
Scope
~/.selesai/agent/settings.json
Global — applies to every project.
.selesai/settings.json
Project — overrides global values for the current directory.
Nested objects are merged, so a project file only needs to override the keys it cares about.
Factory reset
To restore your global settings to the bundled factory defaults, run /settings-factory-reset inside a session. It warns before replacing ~/.selesai/agent/settings.json, saves a .bak backup next to the file, and leaves credentials (auth.json), sessions, extensions, skills, and themes untouched.
