Settings keys
Every key Syntic Code reads from its settings files. Where the files live and which one wins is on Settings files. “Policy” means an organization’s managed file may set it (Organization policy).
Core
| Key | Type | Default | Policy | What it does |
|---|---|---|---|---|
model | string | platform default | yes | Model for the main conversation. |
smallModel | string | platform default | yes | Model for background helper tasks. |
fallbackModel | string or list (up to 3) | none | yes | Models to try when the main one is unavailable. |
permissionMode | default, acceptEdits, auto, plan, bypass, dontAsk | default (auto on new installs; auto-edit in a trusted folder when unset) | yes | The mode sessions start in. acceptEdits is shown as auto-edit; the older bypassPermissions is migrated to bypass. A project file cannot choose auto or bypass. See Permission modes. |
agent | string | none | no | Run the main session as this custom agent. |
agents | object {"defaultMaxBudgetUsd": n} | none | yes | Spend cap in dollars for each sub-agent run whose definition sets no maxBudgetUsd. |
outputStyle | string | default | no | Output style. |
env | object | none | yes | Environment variables for the session’s commands (trusted folders only). |
shell | string | your login shell | no | The shell for commands. |
maxTurns | number | 0 (no limit) | yes | Most agent turns per run. |
apiKeyHelper | command | none | no | A command that prints a credential (user settings only). |
apiKey | string | none | no | A stored API credential. Signing in, the environment or apiKeyHelper are better choices; it is never printed back in full. |
apiBaseUrl | string | the Syntic service | yes | Send API requests to a different endpoint. |
bashOutputMaxChars | number (up to 150000) | 30000 | no | How much shell output the model receives before the rest is cut. |
language | string | follows you | no | Language for replies and session titles. |
Permissions
| Key | Type | What it does |
|---|---|---|
permissions.allow / ask / deny | list of rules | Run without asking / always ask / refuse. See rules. |
permissions.defaultMode | mode | Same as permissionMode. |
permissions.additionalDirectories | list of paths | Extra folders sessions may work in. |
permissions.disableAutoMode | "disable" or true | Auto mode cannot be chosen. |
permissions.disableBypassPermissionsMode | "disable" or true | Bypass mode cannot be chosen. |
permissions.blockReadsOutsideWorkingDirectories | bool | Keep file reads inside the working folders. |
allowManagedPermissionRulesOnly | bool | Policy only: only the policy’s allow rules count. |
alwaysAllow / alwaysAsk / alwaysDeny | list of rules | Older flat forms of the three lists. |
autoMode | object | allow, soft_deny, hard_deny lists, plus review, reviewReadOnly, classifyAllShell. See auto mode. |
sandbox | object | The shell sandbox: enabled, failIfUnavailable, autoAllowBashIfSandboxed, strictCwd, network, filesystem, excludedCommands, allowUnsandboxedCommands, allowAppleEvents, bwrapPath. |
browserAutomation | object | {"enabled": true} offers the Browser tool; optional chromePath, userDataDir, headless. User and policy files only; a project cannot turn it on. |
computerUse | object | {"enabled": true} offers the computer-control tool. User and policy files only. |
Hooks
| Key | Type | What it does |
|---|---|---|
hooks | object | Hooks by event. See Hooks. |
disableAllHooks | bool | Turn hooks off (in policy: all hooks). |
allowManagedHooksOnly | bool | Policy: only the policy’s hooks run. |
allowedHttpHookUrls | list of URL patterns | URLs http hooks may call. |
MCP, plugins and skills
| Key | Type | What it does |
|---|---|---|
mcpServers | object | MCP server definitions. |
allowedMcpServers / deniedMcpServers | list | Which MCP servers may start (allow list is policy only). |
channelsEnabled | bool | false turns MCP channels off (user or policy files). |
channels | list of server names | User settings only: MCP servers allowed to push messages into your session, added to --channels. |
allowedChannelServers | list | Policy only: narrows which servers may push messages. |
extraKnownMarketplaces (also additionalMarketplaces) | object | Plugin marketplaces known by name. |
enabledPlugins | object | Policy: {"plugin@marketplace": false} forces a plugin off. |
strictKnownMarketplaces (also allowedMarketplaces), blockedMarketplaces | list | Which marketplaces may be used. |
pluginTrustMessage | string | Policy: a note shown after each plugin install. |
skillOverrides | object | Per skill: off, user-invocable-only, name-only. |
disableSkillShellExecution | bool | Do not run inline shell in skills and commands. |
Models and reasoning
| Key | Type | What it does |
|---|---|---|
modelPicker | list | Models /model shows, in order (name or {"model", "label"}). |
availableModels / deniedModels | list of patterns | Which models can be chosen. |
effortLevel | level | Starting reasoning effort. |
effortByModel | object | Saved effort per model, for example {"Syntic Code": "high"}. Written by /effort; a model with no entry uses effortLevel. |
maxEffortLevel | level or per-model object | Highest effort allowed. |
maxThinkingTokens | number (16384) | Reasoning budget per turn. |
alwaysThinkingEnabled | bool | false starts with reasoning off. |
fastMode | bool | Start in fast mode. |
contextWindow | number (200000) | Context size assumed for unknown models. |
autoContinueAfterUsageLimit | bool | false stops instead of continuing after a usage window resets. |
toolSearch | object | On-demand tool loading per model: {"disabledModels": ["Amara Deep", "amara*"]} sends every tool up front, without ToolSearch loading, for the models named (exact name in any case, or a * pattern). Used only when the service’s model list does not say whether a model supports on-demand loading, and after SYNTIC_TOOLSEARCH_DENY_MODELS. Lists from every settings file are joined. |
Memory and context
| Key | Type | What it does |
|---|---|---|
autoMemoryEnabled | bool (true) | Auto memory on or off. |
autoMemoryUpkeep | bool (true) | Background saving and tidying of auto memory. |
autoMemoryDirectory | absolute path | Where auto memory is kept (user and local settings only). |
synticMdExcludes | list of patterns | Memory files to skip. |
includeGitInstructions | bool | false leaves the built-in git guidance out. |
autoCompact | bool (true) | Automatic compaction. |
autoCompactThreshold | number (0.8) | Share of the window that triggers compaction. |
autoCompactWindows | object | Per-model window compaction measures against (set by /autocompact). |
promptCacheTtl / subagentPromptCacheTtl | "5m" or "1h" | How long cached prompts last: main session / subagents. |
cleanupPeriodDays | number | Delete transcripts older than this. |
plansDirectory | path (~/.syntic/plans) | Where plan files go. |
Git and commits
| Key | Type | What it does |
|---|---|---|
attribution | false or {"commit": text, "pr": text} | The attribution added to commits and pull requests. |
includeCoAuthoredBy | bool (true) | Older switch for the commit co-author line. |
commitSessionTrailer | bool (false) | End commits with Syntic-Session: <id> (needs git 2.32+). |
worktree | object | baseRef (head or fresh) and sparsePaths for new worktrees. |
verification | false or {"enabled": bool, "maxSeconds": n} | After a substantial turn, a read-only check compares the change with your request; its verdict is the turn’s Checked: line. On by default, 120 seconds at most; false turns it off. |
Sessions
| Key | Type | What it does |
|---|---|---|
crossSessionInbound | ask, auto, refuse | What happens to messages from your other sessions. |
sessionMessagesAutoRun | bool | Same as crossSessionInbound: auto. |
dialogExpiry | seconds | Dismiss a waiting message after this long. |
disableDeepLinks | bool | Refuse syntic-cli:// links. |
disableDeepLinkRegistration | bool | Do not register the link handler. |
Interface
| Key | Type | Default | What it does |
|---|---|---|---|
theme | theme name | auto | Interface colors: auto, dark, light, the color-blind and 16-color themes, and others listed on Themes. |
syntaxTheme | string | follows theme | Code block colors. |
themeColors | object | none | Override individual colors. |
renderer | inline, fullscreen | inline | Drawing mode (from the next start). |
verbose | bool | false | Show tool results in full. |
vimMode | bool | false | Vim keys in the prompt. |
vimInsertModeRemaps | object | none | Two-key sequences that leave insert mode. |
vimRegisterPersist | bool | true | Keep the vim register across sessions. |
statusLine | {"command": …} | none | Your status line script. |
subagentStatusLine | {"command": …} | none | A script for each running subagent’s row. |
showTurnDuration | bool | true | Show how long each reply took. |
showThinkingSummaries, expandThinking | bool | false | Show reasoning in full. |
respondToBashCommands | bool | false | Let the agent react to your ! commands right away. |
screenReader | bool | false | Screen reader mode. |
prefersReducedMotion | bool | false | Calmer spinner, no animations. |
notificationsEnabled | bool | true | Notifications when long turns finish. |
terminalProgressBarEnabled | bool | true | Busy indicator on the terminal tab. |
promptSuggestionEnabled | bool | true | Suggest a next prompt in the empty prompt box. |
autoScrollEnabled | bool | true | Follow new output. |
timeFormat | 12h, 24h | 12h | Clock format. |
maxProseWidth | number (≥ 40) | full width | Widest reply text runs. |
scrollSpeed | 0.25–10 | 1 | Mouse wheel speed. |
wheelAcceleration | bool | true | Faster scrolling on quick flicks. |
respectGitignore | bool | true | Leave ignored files out of @ suggestions. |
fileSuggestion | {"type": "command", "command": …} | built in | Your own @ file suggestions. |
copyFullResponse | bool | false | /copy takes the whole reply without asking. |
spellCheckEnabled | bool | true | Underline misspellings (needs aspell or hunspell). |
spinnerTipsEnabled, spinnerTips, spinnerVerbs | Spinner tips and words. | ||
spinnerTipsOverride | object | none | Your organization’s tips: tips (text, or {"text", "priority"}), tipsFile (one tip per line, # for comments), label (a prefix), excludeDefault (hide built-in tips). |
showAgentsViewByDefault | bool | false | Open the agents view when background agents start. |
showClearContextOnPlanAccept | bool | false | Offer “clear context” when approving a plan. |
workflowSizeGuideline | small, medium, large, unrestricted | medium | Advice on workflow size. |
prStatusFooterEnabled | bool | false | Pull request state in the footer (needs gh). |
prUrlTemplate | string | none | Where the pull request badge links. |
footerLinksRegexes | list | none | Footer badges from the branch name (up to 3). |
feedbackSurvey | bool | true | The occasional one-question survey (answers stay local). |
autoConnectIde | bool | true | Connect to your editor when started in its terminal. |
companyAnnouncements | list of strings | none | Messages shown at start, one per day. |
Organization policy only
| Key | What it does |
|---|---|
minimumVersion / maximumVersion | Versions outside the range do not start a session. |
forceLoginOrgUUID | Only sign-ins to this organization are accepted. |
forceLoginMethod | subscription or console: the only sign-in method allowed. A sign-in that asks for the other is refused with a message naming the right one. Read from policy files and your user file, never from a project. |
processWrapper | A launcher (absolute path, as a string or a list of arguments) that every shell command, hook and MCP server is started through, for example an auditing tool. Policy only. |
modelPricing | Your organization’s rates for cost figures. |
requireRemoteManagedSettings | Refuse to start without fresh service-delivered settings. |
parentSettingsBehavior | How settings from a program that embeds Syntic Code combine with the policy. |
Kept by Syntic Code
Syntic Code writes these itself. There is no need to set them by hand.
| Key | What it records |
|---|---|
hasCompletedOnboarding | First-run setup is finished. |
loginMethod | The sign-in method you chose last, so signing in again does not ask. |
terminalSetup | The terminal key setup has been applied. |
schemaVersion | The settings format version, updated when settings are migrated. |
Old names
These older keys are still understood and moved to their new names when settings are migrated: allowedTools → alwaysAllow, deniedTools → alwaysDeny, maxThinking → maxThinkingTokens, compactThreshold → autoCompactThreshold. A permissions block with allow, ask, deny and defaultMode is read as described above.
Other files
| File | Holds |
|---|---|
~/.syntic/keybindings.json | Your key bindings. |
~/.syntic/update.json | channel and checkForUpdates. |
.mcp.json, ~/.syntic/.mcp.json | MCP servers. |
.syntic/hooks.json, ~/.syntic/hooks.json | Hooks kept apart from settings. |
.syntic/permissions.json, ~/.syntic/permissions.json | Rules kept apart from settings (allow, ask, deny). |