Settings Reference
Auto-generated Reference: This page is generated directly by evaluating
DEFAULT_SETTINGS, schema definitions, and metadata fromsource/services/settings/. Runpnpm --dir website buildto re-extract settings.
term2 settings can be configured via:
- Interactive Settings Menu: Run
/settingsor/settings <key>in the interactive TUI. - Configuration File: Stored in
settings.jsonin your platform’s application state directory. - Environment Variables: Overrides for API keys, logging, and environment options.
Modifying Settings
Section titled “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
Section titled “Agent & Models”| Key | Type | Default | Runtime Modifiable | Environment Variable | Description |
|---|---|---|---|---|---|
agent.model |
string |
"gpt-5.1" |
✓ Yes | OPENROUTER_MODEL |
The AI model to use (e.g. gpt-4, claude-3-opus) |
agent.efficientModel |
string |
— | ✓ Yes | — | Model for lower-tier workflow agents. Falls back to agent.model when unset. |
agent.capableModel |
string |
— | ✓ Yes | — | Model for higher-tier workflow agents. Falls back to agent.model when unset. |
agent.smartModel |
string |
— | ✓ Yes | — | Models for smart ancillary tasks; subagent spawns round-robin the pool, other consumers use the first entry. Falls back to agent.model when unset. |
agent.smartProvider |
string |
— | ✓ Yes | — | Provider for smart ancillary tasks. Falls back to agent.provider when unset. |
agent.smartReasoningEffort |
`default \ | none \ | minimal \ | low \ | medium \ |
agent.balancedModel |
string |
— | ✓ Yes | — | Models for balanced ancillary tasks; subagent spawns round-robin the pool, other consumers use the first entry. Falls back to agent.model when unset. |
agent.balancedProvider |
string |
— | ✓ Yes | — | Provider for balanced ancillary tasks. Falls back to agent.provider when unset. |
agent.balancedReasoningEffort |
`default \ | none \ | minimal \ | low \ | medium \ |
agent.cheapModel |
string |
— | ✓ Yes | — | Models for cheap ancillary tasks; subagent spawns round-robin the pool, other consumers use the first entry. Falls back to agent.model when unset. |
agent.cheapProvider |
string |
— | ✓ Yes | — | Provider for cheap ancillary tasks. Falls back to agent.provider when unset. |
agent.cheapReasoningEffort |
`default \ | none \ | minimal \ | low \ | medium \ |
agent.choreModel |
string |
— | ✓ Yes | — | Models for chore ancillary tasks (auto-approval reviews, edit healing). Falls back to agent.model when unset. |
agent.choreProvider |
string |
— | ✓ Yes | — | Provider for chore ancillary tasks. Falls back to agent.provider when unset. |
agent.reasoningEffort |
`default \ | none \ | minimal \ | low \ | medium \ |
agent.temperature |
number |
— | ✓ Yes | — | Model temperature (0-2, controls randomness) |
agent.provider |
string |
"openai" |
✓ Yes | — | Provider to use for the agent |
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 |
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.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 | — | Proactive check-ins on a still-running background shell job or subagent while the session is otherwise idle |
agent.backgroundCheckIn.intervalMs |
number |
300000 |
✓ Yes | — | Proactive check-ins on a still-running background shell job or subagent while the session is otherwise idle |
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.mentorModel |
string |
— | ✓ Yes | — | Model to use as a mentor |
agent.mentorProvider |
string |
— | ✓ Yes | — | Provider to use for the mentor model (defaults to agent.provider when unset) |
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.autoApproveModel |
string |
"gpt-4o-mini" |
✓ Yes | — | Faster model to use for auto-approval evaluation |
agent.autoApproveProvider |
string |
— | ✓ Yes | — | Provider to use for the auto-approval model (defaults to agent.provider when unset) |
agent.autoApproveReasoningEffort |
`none \ | minimal \ | low \ | medium \ | high \ |
Run Budget & Safeguards
Section titled “Run Budget & Safeguards”| Key | Type | Default | Runtime Modifiable | Environment Variable | Description |
|---|---|---|---|---|---|
agent.runBudget.maxUsdMicros |
number |
5000000 |
✓ Yes | — | Per-run staged budget and stall-detection policy |
agent.runBudget.maxUnpricedTokens |
number |
5000000 |
✓ Yes | — | Per-run staged budget and stall-detection policy |
agent.runBudget.maxActiveTimeMs |
number |
3600000 |
✓ Yes | — | Per-run staged budget and stall-detection policy |
agent.runBudget.warningHeadroomUsdMicros |
number |
1000000 |
✓ Yes | — | Per-run staged budget and stall-detection policy |
agent.runBudget.warningHeadroomUnpricedTokens |
number |
1000000 |
✓ Yes | — | Per-run staged budget and stall-detection policy |
agent.runBudget.warningHeadroomActiveTimeMs |
number |
900000 |
✓ Yes | — | Per-run staged budget and stall-detection policy |
agent.runBudget.softHeadroomUsdMicros |
number |
250000 |
✓ Yes | — | Per-run staged budget and stall-detection policy |
agent.runBudget.softHeadroomUnpricedTokens |
number |
250000 |
✓ Yes | — | Per-run staged budget and stall-detection policy |
agent.runBudget.softHeadroomActiveTimeMs |
number |
300000 |
✓ Yes | — | Per-run staged budget and stall-detection policy |
agent.runBudget.turnBackstop |
number |
150 |
✓ Yes | — | Per-run staged budget and stall-detection policy |
agent.runBudget.extensionPercent |
number |
50 |
✓ Yes | — | Per-run staged budget and stall-detection policy |
agent.runBudget.maxParentExtensions |
number |
2 |
✓ Yes | — | Per-run staged budget and stall-detection policy |
agent.runBudget.identicalToolCallThreshold |
number |
3 |
✓ Yes | — | Per-run staged budget and stall-detection policy |
agent.runBudget.escalation |
`warn \ | pause \ | disabled` | "warn" |
✓ Yes |
Subagents & Roles
Section titled “Subagents & Roles”| Key | Type | Default | Runtime Modifiable | Environment Variable | Description |
|---|---|---|---|---|---|
agent.subagentExplorerModel |
string |
— | ✓ Yes | — | Model override for the explorer subagent. Falls back to agent.model when unset. |
agent.subagentExplorerProvider |
string |
— | ✓ Yes | — | Provider override for the explorer subagent. Falls back to agent.provider when unset. |
agent.subagentExplorerReasoningEffort |
`default \ | none \ | minimal \ | low \ | medium \ |
agent.subagentWorkerModel |
string |
— | ✓ Yes | — | Model override for the worker subagent. Falls back to agent.model when unset. |
agent.subagentWorkerProvider |
string |
— | ✓ Yes | — | Provider override for the worker subagent. Falls back to agent.provider when unset. |
agent.subagentWorkerReasoningEffort |
`default \ | none \ | minimal \ | low \ | medium \ |
agent.subagentLibrarianModel |
string |
— | ✓ Yes | — | Model override for the librarian subagent. Falls back to agent.model when unset. |
agent.subagentLibrarianProvider |
string |
— | ✓ Yes | — | Provider override for the librarian subagent. Falls back to agent.provider when unset. |
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
Section titled “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" |
shell.useRtkCompression |
boolean |
false |
✓ Yes | — | Use RTK to compress shell command output |
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 with persistent Docker host-control grants; remove a path here to revoke it (JSON array) |
sandbox.allowNetworking |
boolean |
false |
✓ Yes | — | Allow sandboxed commands to access the network (true|false) |
Context & Compaction
Section titled “Context & Compaction”| Key | Type | Default | Runtime Modifiable | Environment Variable | Description |
|---|---|---|---|---|---|
agent.sessionRollover.enabled |
boolean |
true |
✓ Yes | — | Agent advice for handing off a growing session at context milestones |
agent.sessionRollover.milestones |
array |
[200000,300000,400000] |
✓ Yes | — | Agent advice for handing off a growing session at context milestones |
agent.sessionRollover.autoBrief |
boolean |
true |
✓ Yes | — | Agent advice for handing off a growing session at context milestones |
agent.contextCompaction.enabled |
boolean |
false |
✓ Yes | — | Native and application-owned context compaction settings |
agent.contextCompaction.mode |
`native \ | auto \ | local` | "auto" |
✓ Yes |
agent.contextCompaction.compactThreshold |
number |
0.8 |
✓ Yes | — | Native and application-owned context compaction settings |
agent.contextCompaction.compactThresholdTokens |
number |
null |
✓ Yes | — | Native and application-owned context compaction settings |
Tools & Permissions
Section titled “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.editHealingModel |
string |
"gpt-4o-mini" |
✓ Yes | — | Model to use for edit healing (fast/cheap) |
tools.editHealingProvider |
string |
— | ✓ Yes | — | Provider to use for the edit-healing model (defaults to agent.provider when unset) |
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 (read_file, grep, glob) for the main agent (true|false). In Lite, outside-workspace reads follow Lite mode, not this toggle; applies on the next model request. |
tools.fileWrite.enabled |
boolean |
true |
✓ Yes | — | Enable file edit tools (apply_patch / create_file / search_replace) 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 (memory_*) 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 (session_list, session_search, session_read, session_rollover) 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 (run_subagent and its async controls) 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 (get_shell_job, cancel_shell_job, configure_task_check_in) 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 (read_code_outline, code_context_search) for the main agent (true|false). Applies on the next model request. |
UI & Terminal
Section titled “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 | — |
app.shellPath |
string |
— | No | SHELL, COMSPEC |
Path to shell executable |
app.activeProfileId |
string |
"builtin:standard" |
✓ Yes | — | Active profile identifier (builtin:standard, 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 (mapped to active 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
Section titled “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
Section titled “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
Section titled “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
Section titled “Web Search”| Key | Type | Default | Runtime Modifiable | Environment Variable | Description |
|---|---|---|---|---|---|
webSearch.provider |
string |
"tavily" |
✓ Yes | WEB_SEARCH_PROVIDER |
Web search provider (tavily, exa) |
webSearch.tavily.apiKey |
string |
— | ✓ Yes | TAVILY_API_KEY |
Tavily search API key |
webSearch.exa.apiKey |
string |
— | ✓ Yes | EXA_API_KEY |
Exa search API key |
Hooks & Environment
Section titled “Hooks & Environment”| Key | Type | Default | Runtime Modifiable | Environment Variable | Description |
|---|---|---|---|---|---|
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 |