Build with Syntic CodeTroubleshootingSpeed and stability

Speed & stability

Slow to start

CauseFix
Many MCP serversServers start in parallel and slow ones join later, but each still costs time. Turn off the ones you rarely use (/mcp), or use --strict-mcp-config with just what you need.
Many pluginsDisable plugins you do not use (/plugin), or test with --safe-mode.
Hooks on SessionStartA slow hook delays the first turn. Check /hooks; give long jobs "async": true.
A huge folderStart in the project folder rather than your home folder or /.

Slow replies

  • Use fast mode (/fast) or lower the effort (/effort low) for simple work.
  • Shrink the context. A long conversation makes every request bigger. /compact, or /clear when you switch tasks. /context shows what takes the space.
  • Trim memory. A large SYNTIC.md loads on every request. Move area-specific notes into .syntic/rules/ files with paths.
  • Fewer tools. Each MCP server and plugin adds tool descriptions. /skill-doctor shows unused skills.
  • Keep the cache warm. If you pause often, "promptCacheTtl": "1h" keeps follow-ups fast.
  • Long tool calls move aside. A command or MCP call that runs long can go to the background (Ctrl+B), so the agent keeps working.

The agent seems stuck

  • Look at the working line: it shows elapsed time and what the agent is doing. No reply from the Syntic server for …s — still waiting means the model has not started answering yet.
  • A shell command waiting for input (a password prompt, a pager) cannot be answered by the agent. It is told when a background command looks stuck; press Esc and give it a non-interactive alternative.
  • Subagents with no progress are stopped after 10 minutes (SYNTIC_SUBAGENT_STALL_SECS).
  • Press Esc to stop the turn. Your message comes back so you can rephrase it.

Memory and CPU

  • Very long sessions use more memory. Start a new session with /clear (the old one stays resumable).
  • Background commands with endless output are stopped at 64 MB (SYNTIC_BG_OUTPUT_CAP_MB).
  • On Linux, SYNTIC_BASH_MEMORY_LIMIT_MB caps the memory of each command the agent runs.
  • /heapdump writes a memory report you can attach to a bug report.

Display problems

ProblemTry
Flicker or torn framesSYNTIC_SYNC_OUTPUT=0, or switch view with /tui inline / /tui fullscreen.
Strange characters or boxesUse a font with good Unicode coverage, or --screen-reader for plain ASCII.
Wrong colors, or text too faintTry /theme (ansi uses your terminal’s own colors; auto follows its background).
No colors at allCheck NO_COLOR is not set.
Shift+Enter sends the messageRun /terminal-setup, or use Ctrl+J or \ then Enter.
Alt/Option shortcuts do nothing on a MacMake your terminal send Option as Meta (see Terminal setup).
Mouse selection does not work in full screenHold your terminal’s selection modifier, or set SYNTIC_DISABLE_MOUSE=1.
Selection stops at the edge of the screenKeep holding the button at the top edge: in the inline view the Ctrl+O transcript opens and scrolls while the selection grows.
The wheel opens the transcript instead of scrolling the terminal (inline view)That is how the inline view reads the mouse. Set SYNTIC_DISABLE_MOUSE=1 for your terminal’s own scrollback.
Inside tmux control mode the screen is wrongSet SYNTIC_TMUX_CONTROL_MODE=1.

Crashes and leftovers

If Syntic Code is killed or crashes, shell commands it started are cleaned up the next time it starts. Background sessions that were cut off show as interrupted in syntic sessions; syntic respawn --interrupted continues them.

Error messages