Configuration File

symtrace automatically loads configuration options from TOML files, enabling team-wide standards for diffing rules, parse limits, query rules, merge drivers, and TUI settings.

File Locations & Precedence

symtrace searches for configuration files in the following order:

1. CLI Flags (highest precedence - overrides all configuration file settings)
2. Repository Local Config: .symtracerc or symtrace.toml in the repository root directory
3. User Global Config: ~/.config/symtrace/symtrace.toml (Unix) or %USERPROFILE%\.config\symtrace\symtrace.toml (Windows)
4. Built-in Defaults (lowest precedence)

Sample Configuration File

[default]
compact = false             # Enable micro-compact inline diff output by default
full_headers = false        # Force full structural headers and timing banners
logic_only = false          # Skip comments and whitespace-only nodes
format = "ansi"             # Default output format: "ansi", "prompt", "json", "markdown", "sarif"
no_incremental = false      # Force full AST re-parse (disable cache reuse)
no_pager = false            # Disable piping output to $PAGER

[limits]
max_file_size = 10485760    # Skip files larger than 10 MiB (default: 5 MiB = 5242880)
max_ast_nodes = 500000      # Skip files with more AST nodes than specified (default: 200000)
max_recursion_depth = 2048  # Maximum AST parsing recursion depth (default: 2048)
parse_timeout_ms = 3000     # Per-file tree-sitter parse timeout in ms (default: 2000)

[output]
color = "auto"              # Terminal color controls: "auto", "always", or "never"
unified_context = 3         # AST context node depth level (default: 3)

[queries]
enabled = true              # Enable custom Tree-Sitter .scm query evaluation
dir = ".symtrace/queries"   # Directory path containing language .scm rule files
fail_on_security_match = false # Exit code 1 when a security query matches in --check mode

[merge]
auto_resolve_formatting = true     # Resolve whitespace/formatting conflicts in 3-way merge
auto_resolve_reorders = true       # Resolve reordered functions automatically
annotate_semantic_conflicts = true  # Add AST context info to merge conflict headers

[tui]
mouse_support = true
layout = "split"            # Layout mode: "split", "single_tree", "single_diff"
theme = "dark"              # Color palette: "dark", "light", "high_contrast"

Section Reference

[default] Section

Option	Type	Default	CLI Equivalent	Description
compact	boolean	false	--compact	Forces micro-compact 1–3 line inline token diffs
full_headers	boolean	false	--full-headers	Forces verbose banners and diagnostics
logic_only	boolean	false	--logic-only	Filters out comments and formatting/whitespace nodes
format	string	"ansi"	--format <FMT>	Output format (ansi, prompt, json, jsonl, markdown, html, sarif)
no_incremental	boolean	false	--no-incremental	Disables incremental AST parsing and cache reuse
no_pager	boolean	false	--no-pager	Prevents piping terminal output into $PAGER

[queries] Section

Option	Type	Default	Description
enabled	boolean	true	Enables custom .scm query rule evaluation
dir	string	".symtrace/queries"	Directory path relative to repo root containing query files
fail_on_security_match	boolean	false	When true, --check exits with code 1 on rule violations

[merge] Section

Option	Type	Default	Description
auto_resolve_formatting	boolean	true	Auto-resolves whitespace/formatting conflicts during 3-way merge
auto_resolve_reorders	boolean	true	Auto-resolves reordered function/struct definitions
annotate_semantic_conflicts	boolean	true	Writes AST entity names inside merge conflict markers