Debugging Guide

Debugging Guide

Enable Debug Mode

Pass -tabby-debug as a launch argument in Xcode:

1. Product > Scheme > Edit Scheme > Run > Arguments
2. Add -tabby-debug to "Arguments Passed On Launch"

This enables TabbyDebugOptions.isEnabled, which turns on:

• Detailed service-level logging (prompt input, raw model output, normalized output)
• Verbose focus-tracking diagnostics
• Additional runtime metadata in console output

Debug logging is gated so that user content never appears in production logs.

Ghost Text Does Not Appear

Work through this decision tree:

1. Check the menu bar. Open Tabby's menu - does the status say anything useful?

2. Is Tabby disabled?

• Globally turned off? Check the "Enable Globally" toggle.
• App-disabled? The focused app may be in the disabled list. Check Settings > Disabled Apps.
• Terminal? Tabby automatically blocks terminal emulators (TerminalAppDetector).
• Secure field? Tabby refuses to operate on password fields.
• Missing permissions? Input Monitoring and Accessibility must both be granted.

All these checks live in SuggestionAvailabilityEvaluator.disabledReason().

3. Is the field recognized?

• Check FocusSnapshot.capability - is it .supported?
• If .unsupported or .blocked, the AX tree isn't exposing a usable text field. See App Compatibility Notes.

4. Is generation running?

• With -tabby-debug, check Xcode console for prompt/generation output.
• If the model isn't loaded, check LlamaRuntimeManager bootstrap state in the menu bar.

5. Is the result being suppressed?

• SuggestionTextNormalizer strips empty or prefix-echoing output.
• SuggestionSessionReconciler invalidates sessions when editor content diverges from the expected state.

Ghost Text Appears in the Wrong Position

Check the caret geometry quality:

Quality	Meaning	Accuracy
.exact	App provides precise BoundsForRange	Pixel-accurate
.derived	Computed from child frame geometry	Usually close
.estimated	Fallback from field frame	Approximate

If .estimated, the host app doesn't expose precise caret bounds via Accessibility. Check AXTextGeometryResolver and GhostSuggestionLayout.

Suggestions Are Stale or Repeat What I Typed

Two systems prevent this:

• SuggestionTextNormalizer strips leading text that echoes the prefix.
• SuggestionSessionReconciler invalidates sessions when the editor text has changed since generation started.

Check both if you see stale or repeated output.

Model Crashes or Produces Empty Output

• Empty output: Check -tabby-debug console for the raw model response. The normalizer may be stripping everything. If the model returns thinking tokens (e.g., <think>) the prompt should suppress them (see LlamaPromptRenderer).
• Crashes: Check for ggml_abort in the crash log - this usually means an oversized prompt exceeded the context window. Verify model file integrity with ModelFileValidator.

Chrome / Electron Apps Behave Differently

Chrome and Electron apps recycle Accessibility node identifiers (CFHash values) between polls. This makes elementIdentifier unreliable for tracking which field is focused.

Tabby works around this using processIdentifier + focusChangeSequence instead. If you're debugging focus identity issues in these apps, check:

• SuggestionSessionReconciler - session continuity logic
• ContextBuffer - context accumulation across polls

Permissions Granted But Nothing Happens

• Restart the app. PermissionManager checks are cached at startup.
• Check signing. When running from Xcode, your development team must be configured for entitlements to activate. If the app isn't properly signed, macOS may silently deny Accessibility access.
• Check System Settings. Verify Tabby appears in Privacy & Security > Accessibility and Privacy & Security > Input Monitoring with checkmarks.