Settings files

Syntic Code reads its settings from JSON files at a few levels, so you can keep personal preferences, team rules and machine-specific tweaks apart. Every key is listed in the settings reference.

Where settings live

The project folder is the nearest .syntic/ above where you start. The user folder can be moved with SYNTIC_CONFIG_DIR.

Which value wins

Later sources override earlier ones:

user → project → local → environment variables (SYNTIC_SETTING_*) → organization policy → command-line flags

A flag can pick a value for one run, but it cannot get around what policy forbids: policy deny rules, disabled modes and allow lists still apply.

Lists of permission rules and hooks are combined across files rather than replaced. A few things can never come from a project’s files, so a repository cannot take over your account: the credential, the API address, the shell, and modes that skip permission prompts. And until you trust a folder, its project and local files are not read at all.

Change settings

syntic config

Add --project for .syntic/settings.json or --local for .syntic/settings.local.json; the default (--global) is your user file.

For one run

A starter file

A project .syntic/settings.json a team might commit:

{
  "model": "Syntic Code",
  "permissions": {
    "allow": ["Bash(pnpm test:*)", "Bash(pnpm lint:*)", "Bash(git status)", "Bash(git diff:*)"],
    "ask":   ["Bash(git push:*)"],
    "deny":  ["Read(.env)", "Read(*.pem)"]
  },
  "env": { "NODE_ENV": "development" },
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "pnpm prettier --write ." }] }
    ]
  },
  "worktree": { "baseRef": "fresh" }
}

And a personal ~/.syntic/settings.json:

{
  "theme": "auto",
  "vimMode": true,
  "statusLine": { "command": "~/.syntic/statusline.sh" },
  "notificationsEnabled": true,
  "promptCacheTtl": "1h",
  "outputStyle": "Concise"
}

outputStyle belongs in your user file: the active style is read from user settings, policy or the environment, not from a project file. More complete files for different situations are on Example settings.

Bad values

A file that is not valid JSON is skipped and reported. A key with the wrong type is dropped and reported at start, in the session and by syntic doctor; the rest of the file still applies. A broken organization policy file stops Syntic Code from starting and names the file.

When a setting does not apply

Work through these in order:

1. Is the file valid? Run syntic doctor. It reports files that are not valid JSON, keys with the wrong type, and unknown keys (with a “did you mean” hint for near misses).
2. Is the folder trusted? Project and local files are skipped until you trust the folder (Folder trust).
3. Is the key allowed at that level? A project file cannot set apiKey, apiBaseUrl, shell, or a permissionMode of auto or bypass. Some keys, such as outputStyle, are read only from your user file.
4. Does something stronger set it? An environment variable, a flag, or organization policy beats your files. syntic doctor lists policy keys in force.
5. Is it a list? Rule and hook lists add up across files instead of replacing each other, so a rule you removed in one file may still come from another.
6. Check the value Syntic Code sees: syntic config get <key> (add --project or --local for those files).

Old key names are migrated rather than dropped: allowedTools becomes alwaysAllow, deniedTools becomes alwaysDeny, maxThinking becomes maxThinkingTokens, and compactThreshold becomes autoCompactThreshold. A notice tells you to rename them.

The .syntic folders

In your home folder (~/.syntic)

In a project (<repo>/.syntic)

Session transcripts are not stored here; they live in your system’s application data folder (Sessions).