Debug your configuration

You added a rule to SYNTIC.md, a hook, a permission rule or an MCP server, and it does not seem to do anything. This page walks through the built-in tools for finding out what Syntic Code actually loaded, in the order that usually finds the problem fastest.

Start with the doctor

syntic doctor

prints a read-only report of the environment Syntic Code resolves from the current folder:

Line	Tells you
`version`	Which build is running.
`config dir`, `data dir`	Where your user configuration and saved sessions are read from (moved by `SYNTIC_CONFIG_DIR` and `SYNTIC_DATA_DIR`).
`model`, `api endpoint`	The model and address a session would use.
`mcp servers`, `agents`	How many MCP servers are configured and custom agents discovered.
Sign-in	Whether a credential is found, and where it comes from.
Output limits	Any limit you changed with an environment variable, and the value in force.
Sessions	Damaged saved sessions for this project, with what to do about each.

Inside a session, /doctor (also /checkup) shows the same, plus Checks: settings files with errors or unknown keys, MCP servers that did not connect, and memory files long enough to cost real context.

/doctor fix

applies the fixes that are safe and local: a settings value the loader already ignores (wrong type, out of range, not one of the allowed choices) is removed after the file is copied to <file>.bak, and MCP servers that are down are reconnected. Unknown keys, organization policy files and long memory files are never changed.

See what loaded into context

Command	Shows
`/context`	How full the context window is, split into system prompt, memory, conversation and tools.
`/memory`	Every instruction file loaded in this session (`SYNTIC.md`, `SYNTIC.local.md`, rules files, imports). `Enter` opens one in your editor.
`/skills`	Every skill this session can see, and where it comes from.
`/agents`	Custom agents, in the Library tab.
`/skill-doctor`	Which skills cost context and which went unused.
`syntic --dump-system-prompt`	The full system prompt your settings produce, printed without starting a session.

If an instruction file is missing from /memory:

Check its location against which files are loaded. A SYNTIC.md in a subfolder loads only once the agent starts working there.
Check synticMdExcludes and SYNTIC_MEMORY_EXCLUDES for a pattern that matches it.
A rules file with paths: loads only when the agent touches a matching file.
SYNTIC_DISABLE_MEMORY=1, --bare and --safe-mode load less memory.

To log every load, add an InstructionsLoaded hook.

Edits made during a session

The system prompt is built when a session starts and reused for every request, which keeps the prompt cache warm. An edit to SYNTIC.md or an output style may not reach the system prompt until the next session. Start with --system-prompt-snapshot off to rebuild it for every request while you iterate.

Check resolved settings

Settings come from several files, combined in this order (later wins):

Layer	File
User	`~/.syntic/settings.json`
Project	`.syntic/settings.json`
Local	`.syntic/settings.local.json`
Organization	Managed settings (Managed settings)

Command-line flags apply on top for one run. Lists such as permission rules and hooks are combined across files, not replaced.

To	Run
See or change settings in the session	`/config` (also `/settings`)
Print what one file contains	`syntic config list` (user), `syntic config list --project`, `syntic config list --local`
Read one key from one file	`syntic config get <key> [--project\|--local]`
See account, model and mode	`/status`
See and edit permission rules	`/permissions`

Common reasons a setting has no effect:

The folder is not trusted. Until you trust a folder, its project and local settings, hooks and MCP servers are not read at all. Trusted folders are listed in ~/.syntic/trusted_folders (Folder trust).
The JSON is broken. A file that is not valid JSON is skipped. /doctor names it.
The value has the wrong type. The key is dropped and reported; the rest of the file still applies.
The key is project-proof. Some keys are never read from project files, so a repository cannot take over your machine: credentials, the API address, the shell, modes that skip permission prompts, and switches such as browserAutomation, computerUse and channels. Put them in your user settings.
The organization sets it. Managed settings win over everything else.
A flag overrides it. --model, --permission-mode, --settings and similar flags win for that run.

Check MCP servers

To	Run
See every server and its state	`/mcp`
List servers and their scopes	`syntic mcp list`
Start each local server once to see if it answers	`syntic mcp list --check`
Show one server’s definition (secrets masked)	`syntic mcp get <name>`
Log connection details	`syntic --mcp-debug` (writes to `~/.syntic/logs/syntic.log` in interactive sessions)

A server that never appears is usually a project server in an untrusted folder, or one you declined. syntic mcp reset-project-choices asks again. More in MCP servers.

Check hooks

To	Run
List every hook, grouped by event, with its source file	`/hooks`
Test a hook script by hand	`echo '<event JSON>' \| ./my-hook.sh; echo $?`
See hooks run in a script	`syntic -p "…" --output-format stream-json --verbose --include-hook-events`
Log hook runs	`syntic --debug`

If /hooks does not list a hook, its file was not read (untrusted folder, broken JSON) or hooks are turned off (disableAllHooks, --bare, --safe-mode, SYNTIC_DISABLE_HOOKS). If it is listed but does nothing, check the matcher. The hooks guide covers the rest.

Test against a clean configuration

The fastest way to tell “my setup” from “Syntic Code” is to start without your setup:

Start with	Leaves out
`syntic --safe-mode` (or `SYNTIC_SAFE_MODE=1`)	Instruction files, plugins, skills, hooks and every MCP server.
`syntic --bare`	Hooks from settings files, plugins, skill discovery, auto memory and background work. MCP servers only from `--mcp-config`.
`syntic --setting-sources user`	Project and local settings files.
`syntic --setting-sources project,local`	Your user settings file.
`SYNTIC_CONFIG_DIR=$(mktemp -d) syntic`	Your whole user configuration (you will need to sign in in that folder).

If the problem goes away, turn things back on one at a time: /hooks, /mcp, /plugin and /skills can switch single pieces off for the session.

Turn on debug logs

How	Logs
`syntic --debug`	Detailed logs to standard error.
`syntic --debug api,hooks`	Only those areas.
`syntic --debug --debug-file /tmp/syntic.log`	Also to a file.
`/debug`	Turns on detailed logging in a running session, without a restart. `/debug off` turns it down again.
`/debug <what is wrong>`	Turns it on and asks the agent to help troubleshoot, pointing it at the log file.

Common causes

Symptom	Usual cause
Project instructions and settings are ignored	The folder is not trusted.
A rule in `SYNTIC.md` is not followed	It loaded, but it conflicts with a more specific file, or it is buried in a long file. Keep it short and move detail to path-scoped rules.
A permission rule does not match	The rule pattern is different from the command as typed (for example `npm test` vs `npm run test`). `/permissions` lists the rules in force.
A hook works in the terminal but not in Syntic Code	It depends on your interactive shell setup, or uses a relative path. Use `$SYNTIC_PROJECT_DIR`.
An MCP server works on one machine but not another	An environment variable used in its config is not set, or its runtime is missing.
A setting works for you but not for a teammate	It is in your user or local file, not in `.syntic/settings.json`.
Behavior changed after a pull	A teammate changed `.syntic/settings.json`, `SYNTIC.md` or `.mcp.json`. Check `git log` on those files.

Still stuck? /feedback <what happened> saves a report with your session details, and Syntic support can help from there.

Install and sign-in Error messages