Settings Reference

Auto-generated Reference: This page is generated directly by evaluating DEFAULT_SETTINGS, schema definitions, and metadata from source/services/settings/. Run pnpm --dir website build to re-extract settings.

term2 settings can be configured via:

1. Interactive Settings Menu: Run /settings or /settings <key> in the interactive TUI.
2. Configuration File: Stored in settings.json in your platform’s application state directory.
3. Environment Variables: Overrides for API keys, logging, and environment options.

Modifying Settings

• In interactive mode: type /settings <key> <value> or browse with /settings.
• Settings marked as Runtime Modifiable can be changed mid-session without restarting.
• Non-runtime modifiable settings require restarting term2 to take effect.
• Reset any setting to its default in the settings menu using Ctrl+D.

---

Agent & Models

Key	Type	Default	Runtime Modifiable	Environment Variable	Description
agent.backgroundWaitTimeoutMs	number	3600000	No	—	Overall headless background-work wait limit in milliseconds (default one hour; unfinished work is cancelled and named)
agent.modelSelection	object	{"model":"gpt-5.1","provider":"openai"}	✓ Yes	—	Bound provider and model selection for the main agent
agent.smartModel	array	—	✓ Yes	—	Models for smart-tier helper agents (the hardest side tasks); subagent spawns round-robin the pool, other consumers use the first entry. Falls back to agent.modelSelection when unset.
agent.smartReasoningEffort	`default \	none \	minimal \	low \	medium \
agent.balancedModel	array	—	✓ Yes	—	Models for balanced-tier helper agents (everyday side tasks); subagent spawns round-robin the pool, other consumers use the first entry. Falls back to agent.modelSelection when unset.
agent.balancedReasoningEffort	`default \	none \	minimal \	low \	medium \
agent.cheapModel	array	—	✓ Yes	—	Models for cheap-tier helper agents (simple, high-volume side tasks); subagent spawns round-robin the pool, other consumers use the first entry. Falls back to agent.modelSelection when unset.
agent.cheapReasoningEffort	`default \	none \	minimal \	low \	medium \
agent.choreModel	array	—	✓ Yes	—	Models for small background jobs like repairing failed file edits and reviewing shell auto-approvals (auto-approval reviews, edit healing). Falls back to agent.modelSelection when unset.
agent.reasoningEffort	`default \	none \	minimal \	low \	medium \
agent.temperature	number	—	✓ Yes	—	Model temperature (0-2, controls randomness)
agent.favoriteModels	array	[]	✓ Yes	—	Ordered list of favorited models as “provider/modelId” strings; matched before any provider catalog loads
agent.modelNicknames	map of string to string	{}	✓ Yes	—	Map of nickname -> “provider/modelId” (with optional “:effort” suffix); an exact nickname match wins for –model before any provider catalog loads. Browse them on the model picker Nicknames tab
agent.disabledProviders	array	[]	✓ Yes	—	Provider ids hidden from model pickers and catalogs; managed and reversible in provider management
agent.maxTurns	number	100	No	—	Maximum conversation turns
agent.maxRequestInputTokens	number	null	✓ Yes	—	Per-request estimated or last-observed input cost/latency ceiling; retains work on refusal (null uses known model capacity)
agent.maxOutputTokens	number	32000	✓ Yes	—	Maximum tokens generated by one model request
agent.maxStreamOutputChars	number	100000	✓ Yes	—	Maximum streamed text or tool-argument characters per model request; reasoning above this is truncated, not aborted
agent.maxModelRequestDurationMs	number	0	✓ Yes	—	Optional total wall-clock ceiling for one model request, in milliseconds (0 disables; opt-in backstop)
agent.maxModelStreamIdleMs	number	600000	No	—	Abort a request that streams no output for this many milliseconds; re-arms on each streamed delta so long reasoning survives (0 disables)
agent.retryAttempts	number	2	✓ Yes	—	Number of retry attempts for failed requests
agent.transport	`websocket \	http`	"websocket"	✓ Yes	—
agent.maxParallelToolCalls	number	3	✓ Yes	—	Maximum number of tool calls allowed to run at the same time
agent.backgroundCheckIn.enabled	boolean	true	✓ Yes	—	Wake the agent periodically to check on a still-running background shell job or subagent while idle
agent.backgroundCheckIn.intervalMs	number	300000	✓ Yes	—	How often to check in on a still-running background task
agent.openrouter.apiKey	string	—	✓ Yes	OPENROUTER_API_KEY	OpenRouter API key
agent.openai.apiKey	string	—	✓ Yes	OPENAI_API_KEY	OpenAI API key
agent.openrouter.baseUrl	string	—	No	OPENROUTER_BASE_URL	OpenRouter base URL
agent.openrouter.referrer	string	—	No	OPENROUTER_REFERRER	OpenRouter HTTP Referer header
agent.openrouter.title	string	—	No	OPENROUTER_TITLE	OpenRouter X-Title header
agent.codex.websocketFirstFrameTimeoutMs	number	90000	No	—	Codex WebSocket timeout before the first response frame, in milliseconds
agent.codex.websocketInterFrameTimeoutMs	number	600000	No	—	Codex WebSocket timeout between response frames, in milliseconds
agent.mentorReasoningEffort	`default \	none \	minimal \	low \	medium \
agent.mentorSamples	number	1	No	—	Number of independent mentor answers to gather per consultation (1 = single answer)
agent.mentorPool	array	[]	✓ Yes	—	Models consulted per mentor question, one answer each. When set, overrides agent.mentorSamples
agent.useFlexServiceTier	boolean	false	✓ Yes	—	Use OpenAI Flex Service Tier to reduce costs (OpenAI only)
agent.autoApproveReasoningEffort	`none \	minimal \	low \	medium \	high \
agent.decisionModel	string	—	✓ Yes	—	OpenRouter Decisions model shared by the approval fast path and failure-triage comparisons. For approval, only low/medium-risk, explicit/implied decisions at confidence 0.8 or higher can authorize execution; every other outcome falls back to the chore reviewer. Sends approval context plus failure evidence. Adds API charges
agent.completionVerification	boolean	true	✓ Yes	—	Verify durable-goal completion before marking achieved (true|false). Disable for operational rollback; applies at the next completion boundary.
agent.verificationMaxRepairs	number	3	✓ Yes	—	Maximum autonomous completion-verification repairs per new task (0-10). Existing persisted tasks retain their original budget.

Run Budget & Safeguards

Key	Type	Default	Runtime Modifiable	Environment Variable	Description
agent.runBudget.maxUsdMicros	number	5000000	✓ Yes	—	Spending limit for one run, counted on requests with a known price
agent.runBudget.maxUnpricedTokens	number	5000000	✓ Yes	—	Token limit for one run when the provider reports no price; cache reads count a tenth and subscription providers are exempt
agent.runBudget.maxActiveTimeMs	number	3600000	✓ Yes	—	Active-time limit for one run; time spent waiting for your approval does not count
agent.runBudget.warningHeadroomUsdMicros	number	1000000	✓ Yes	—	Warn when this much of the run cost limit is left
agent.runBudget.warningHeadroomUnpricedTokens	number	1000000	✓ Yes	—	Warn when this many tokens of the run token limit are left
agent.runBudget.warningHeadroomActiveTimeMs	number	900000	✓ Yes	—	Warn when this much of the run time limit is left
agent.runBudget.softHeadroomUsdMicros	number	250000	✓ Yes	—	Nudge the agent to wrap up when this much of the run cost limit is left
agent.runBudget.softHeadroomUnpricedTokens	number	250000	✓ Yes	—	Nudge the agent to wrap up when this many tokens of the run token limit are left
agent.runBudget.softHeadroomActiveTimeMs	number	300000	✓ Yes	—	Nudge the agent to wrap up when this much of the run time limit is left
agent.runBudget.turnBackstop	number	150	✓ Yes	—	Stop a run that reaches this many turns — a safety net against infinite loops, not a budget
agent.runBudget.extensionPercent	number	50	✓ Yes	—	Size of each budget extension, as a percentage of the original limit
agent.runBudget.maxParentExtensions	number	2	✓ Yes	—	Budget extensions a parent agent may grant a subagent before asking you
agent.runBudget.identicalToolCallThreshold	number	3	✓ Yes	—	Identical tool calls in a row, with no edit in between, that count as a stall
agent.runBudget.escalation	`warn \	contain \	pause \	disabled`	"warn"

Subagents & Roles

Key	Type	Default	Runtime Modifiable	Environment Variable	Description
agent.subagentExplorerReasoningEffort	`default \	none \	minimal \	low \	medium \
agent.subagentWorkerReasoningEffort	`default \	none \	minimal \	low \	medium \
agent.subagentLibrarianReasoningEffort	`default \	none \	minimal \	low \	medium \
subagent.asyncSessionTtlMs	number	1800000	✓ Yes	—	How long completed async subagent sessions are retained in memory before eviction, in milliseconds
subagent.asyncMessageCap	number	50	✓ Yes	—	Maximum number of user turns to retain in a persisted async subagent session

Shell & Sandbox

Key	Type	Default	Runtime Modifiable	Environment Variable	Description
shell.timeout	number	120000	✓ Yes	—	Shell command timeout in milliseconds
shell.backgroundTimeout	number	1800000	✓ Yes	—	Timeout for background shell jobs, in milliseconds. Capped: 0 or unbounded values are rejected.
shell.maxOutputLines	number	1000	✓ Yes	—	Maximum lines of shell output to capture
shell.maxOutputChars	number	40000	✓ Yes	—	Maximum characters of shell output to capture
shell.autoApproveMode	`off \	advisory \	auto \	always`	"off"
sandbox.enabled	boolean	true	✓ Yes	—	Enable sandbox mode for safer command execution (true|false)
sandbox.readPolicy	`standard \	strict`	"standard"	✓ Yes	—
sandbox.allowReadExtra	array	[]	✓ Yes	—	Additional paths allowed for sandbox file reads (comma-separated)
sandbox.dockerHostControlProjects	array	[]	✓ Yes	—	Projects you allowed to control Docker on the host; remove a path to revoke its access (JSON array)
sandbox.allowNetworking	boolean	false	✓ Yes	—	Allow sandboxed commands to access the network (true|false)

Context & Compaction

Key	Type	Default	Runtime Modifiable	Environment Variable	Description
agent.sessionRollover.enabled	boolean	true	✓ Yes	—	Remind the agent when context reaches milestones so it can plan a session rollover (true|false)
agent.sessionRollover.milestones	array	[200000,300000,400000]	✓ Yes	—	Context token milestones that trigger session rollover reminders (e.g. 200000, 300000, 400000)
agent.sessionRollover.autoBrief	boolean	true	✓ Yes	—	Automatically pass the handoff brief into the new session upon rollover (true|false)
agent.contextCompaction.enabled	boolean	true	✓ Yes	—	Enable context compaction (true|false)
agent.contextCompaction.mode	`native \	auto \	local`	"auto"	✓ Yes
agent.contextCompaction.compactThreshold	number	0.8	✓ Yes	—	Context-window ratio for automatic context compaction (0-1, 0%-100%)
agent.contextCompaction.compactThresholdTokens	number	null	✓ Yes	—	Optional raw-token ceiling for automatic context compaction (null or integer >=1000)

Tools & Permissions

Key	Type	Default	Runtime Modifiable	Environment Variable	Description
tools.logFileOperations	boolean	true	No	LOG_FILE_OPERATIONS	Log file operations to disk (true|false)
tools.enableEditHealing	boolean	true	No	—	Use AI to automatically correct failed search_replace operations
tools.shell.enabled	boolean	true	✓ Yes	—	Enable shell tools for the main agent (true|false). Does not restrict subagents; applies on the next model request.
tools.web.enabled	boolean	true	✓ Yes	—	Enable web_search and web_fetch tools for the main agent (true|false). Does not restrict subagents; applies on the next model request.
tools.fileRead.enabled	boolean	true	✓ Yes	—	Enable file read tools for the main agent (true|false); applies on the next model request.
tools.fileWrite.enabled	boolean	true	✓ Yes	—	Enable file edit tools for the main agent (true|false). Does not restrict subagents; applies on the next model request.
tools.memory.enabled	boolean	true	✓ Yes	—	Enable memory tools for the main agent (true|false). Does not restrict subagents; applies on the next model request.
tools.sessions.enabled	boolean	true	✓ Yes	—	Enable prior-session tools for the main agent (true|false). Applies on the next model request.
tools.skills.enabled	boolean	true	✓ Yes	—	Enable the activate_skill tool and skill catalog for the main agent (true|false). Applies on the next model request.
tools.mentor.enabled	boolean	true	✓ Yes	—	Enable the ask_mentor tool for the main agent (true|false). Also requires a configured mentor model; applies on the next model request.
tools.subagents.enabled	boolean	true	✓ Yes	—	Enable subagent delegation tools for the main agent (true|false). Does not restrict the subagents themselves; applies on the next model request.
tools.backgroundTasks.enabled	boolean	true	✓ Yes	—	Enable background task tools for the main agent (true|false). Applies on the next model request.
tools.userInteraction.enabled	boolean	true	✓ Yes	—	Enable the ask_user tool for the main agent (true|false). Applies on the next model request.
tools.codeContext.enabled	boolean	true	✓ Yes	—	Enable code-context tools for the main agent (true|false). Applies on the next model request.

UI & Terminal

Key	Type	Default	Runtime Modifiable	Environment Variable	Description
ui.historySize	number	1000	No	—	Number of history items to keep
ui.pasteThreshold	number	3000	✓ Yes	—	Max paste length before text is replaced by a placeholder
ui.displayMode	`standard \	concise`	"concise"	✓ Yes	—
ui.theme	`auto \	dark \	light \	high-contrast \	mono`
ui.skin	`classic \	rail \	cards \	ledger \	zen`
app.shellPath	string	—	No	SHELL, COMSPEC	Path to shell executable
app.activeProfileId	string	"builtin:bare"	✓ Yes	—	Active profile identifier (builtin:bare, builtin:plan, etc.)
app.mentorMode	boolean	false	✓ Yes	—	Legacy mentor mode flag (mapped to active profile)
app.liteMode	boolean	false	✓ Yes	—	Legacy lite mode flag (selects the Bare profile)
app.planMode	boolean	false	✓ Yes	—	Plan mode: read-only research and implementation planning (true|false)
app.orchestratorMode	boolean	false	✓ Yes	—	Delegate tool-backed work through subagents (true|false)
app.notifications	boolean	true	✓ Yes	—	Enable desktop notifications when the terminal is unfocused (true|false)
app.notificationsOnApproval	boolean	true	✓ Yes	—	Notify when the agent pauses awaiting tool-call approval (true|false)
app.notificationsOnComplete	boolean	true	✓ Yes	—	Notify when the agent finishes responding (true|false)
app.searchViaShell	string	"auto"	✓ Yes	—	Use shell commands (ripgrep/find) for codebase search instead of built-in tools; only on withholds them, auto matches off (auto|on|off)

Memory & Skills

Key	Type	Default	Runtime Modifiable	Environment Variable	Description
memory.enabled	boolean	true	✓ Yes	—	Enable persistent memory across sessions (true|false)
memory.directory	string	platform data directory (Linux: ~/.local/share/term2-nodejs/memory; macOS: ~/Library/Application Support/term2-nodejs/memory; Windows: %LOCALAPPDATA%\term2-nodejs\Data\memory)	No	—	Directory where memory files are stored (path)
memory.contextBudgetChars	number	8000	✓ Yes	—	Character budget for the injected memory index (number)
memory.searchDefaultLimit	number	10	✓ Yes	—	Default number of search results to return (number)
memory.searchMaxLimit	number	50	✓ Yes	—	Maximum number of search results to return (number)

Logging & Debug

Key	Type	Default	Runtime Modifiable	Environment Variable	Description
logging.logLevel	`error \	warn \	info \	security \	debug`
logging.disableLogging	boolean	false	No	DISABLE_LOGGING	Disable all file logging (true|false)
logging.debugLogging	boolean	false	No	DEBUG_LOGGING	Enable debug logging to disk (true|false)
logging.suppressConsoleOutput	boolean	true	✓ Yes	—	Suppress console output (true|false) to avoid interfering with Ink UI
debug.debugBashTool	boolean	false	No	DEBUG_BASH_TOOL	Enable debug logging for the bash tool (true|false)

SSH & Remote

Key	Type	Default	Runtime Modifiable	Environment Variable	Description
ssh.enabled	boolean	false	No	—	Enable SSH remote execution (true|false)
ssh.host	string	—	No	—	SSH remote host
ssh.port	number	22	No	—	SSH remote port
ssh.username	string	—	No	—	SSH remote username
ssh.remoteDir	string	—	No	—	SSH remote directory

Web Search

Key	Type	Default	Runtime Modifiable	Environment Variable	Description
webSearch.provider	string	"tavily"	✓ Yes	WEB_SEARCH_PROVIDER	Web search provider (tavily, exa, firecrawl, searxng)
webSearch.tavily.apiKey	string	—	✓ Yes	TAVILY_API_KEY	Tavily search API key
webSearch.exa.apiKey	string	—	✓ Yes	EXA_API_KEY	Exa search API key
webSearch.firecrawl.apiKey	string	—	No	—	Firecrawl API key
webSearch.firecrawl.baseUrl	string	—	No	—	Firecrawl API base URL
webSearch.searxng.baseUrl	string	—	No	—	SearXNG base URL

Hooks & Environment

Key	Type	Default	Runtime Modifiable	Environment Variable	Description
verifier.model	string	""	✓ Yes	—	Independent verifier model ID; empty uses the session model and provider
enable_agent_workflow	boolean	false	No	—	Enable bounded JavaScript workflows that coordinate concurrent read-only agents (true|false)
environment.nodeEnv	string	—	No	NODE_ENV	Node environment (development|production|test)
hooks.user.enabled	boolean	true	✓ Yes	—	Load trusted user hooks from ~/.term2/hooks (true|false)
hooks.project.enabled	boolean	false	✓ Yes	—	Discover project hooks when the project root is trusted (true|false)
hooks.trustedProjectRoots	array	[]	No	—	Canonical project roots trusted to load hooks (JSON array)
hooks.includeUserText	boolean	false	✓ Yes	—	Include user turn text in hook payloads (true|false)
hooks.includeToolArguments	boolean	false	✓ Yes	—	Include full tool arguments in hook payloads (true|false)
hooks.includeToolResults	boolean	false	✓ Yes	—	Include full tool results in hook payloads (true|false)
hooks.timeoutMs	number	5000	✓ Yes	—	Maximum time to await one hook callback in milliseconds