Allow regex-based terminal text highlighting (#2788)

[austinywang]

Closes #2788

Summary

• add automatic regex highlight rules for visible terminal text
• expose settings through Settings > Terminal and cmux.json
• add schema/docs/localization and behavioral coverage for parsing/matching

Testing

• Not run locally per repo policy; CI will run the test suite.

---

Note

Medium Risk
New overlay path in GhosttyTerminalView runs user-supplied regex on viewport text each refresh; invalid patterns are skipped but complex rules could affect performance on busy terminals.

Overview
Adds regex-based automatic text highlights for visible terminal output: users define one pattern per line (optional #RRGGBB / #RRGGBBAA + tab for color) via Settings → Terminal, terminal.regexHighlights in cmux.json, schema/docs, and settings search.

Runtime: TerminalRegexHighlightSettings parses and caches compiled rules; TerminalRegexHighlightMatcher finds matches with terminal column width (wide CJK/emoji), caps at 512 runs, and skips invalid regexes. A passthrough TerminalRegexHighlightOverlayView draws colored rounded rects over the Ghostty surface; refresh is coalesced after render, scroll, resize, visibility, and settings changes.

Tests: Unit tests for parsing/matching; a Python regression uses full-window screenshot (not panel snapshot) so overlays are visible. Screenshot window selection is tightened so capturable windows are chosen reliably.

^{Reviewed by Cursor Bugbot for commit e500218. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

Summary by cubic

Adds regex-based automatic highlighting for visible terminal text with per‑rule colors. Highlights align to terminal columns and refresh after render and viewport changes. Closes #2788.

• New Features

  • One regex per line; optional color prefix #RRGGBB or #RRGGBBAA + tab; default #FFE06680.
  • Rounded overlays for viewport matches; clipped to columns; max 512 matches; invalid patterns skipped; refresh on render/scroll/resize/geometry/visibility/settings.
  • New setting in Settings > Terminal (monospaced editor) and in cmux.json (string or array). Docs, schema, localization, search, template examples, and tests added.

• Bug Fixes

  • Correct column math for wide CJK/emoji and zero‑width chars to keep highlights aligned.
  • Ensure overlays render above the terminal and clear when hidden; improve window screenshot capture so overlays appear in tests.

^{Written for commit e500218. Summary will update on new commits.}

Summary by CodeRabbit

Release Notes

• New Features

  • Added automatic terminal text highlighting based on customizable regex patterns.
  • Added Terminal settings panel for defining highlight rules with custom colors.
  • Highlights render as colored overlays on matching terminal text.

• Documentation

  • Updated configuration schema and settings template with regex highlight examples.

• Tests

  • Added test coverage for regex highlight settings and rendering.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cmux	Ready	Preview, Comment	Jun 6, 2026 2:18pm
cmux-staging	Building	Preview, Comment	Jun 6, 2026 2:18pm

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds regex-based automatic terminal text highlighting with user-configurable patterns and colors. Includes data models, settings persistence with notifications, pattern matching against visible terminal text, viewport-synchronized overlay rendering, and full settings UI integration.

Changes

Regex-based Terminal Text Highlighting

Layer / File(s)	Summary
Data models and settings infrastructure Sources/App/WorkspaceRuntimeSettings.swift, Sources/CmuxSettingsJSONPathSupport.swift, web/data/cmux.schema.json, Resources/Localizable.xcstrings	Defines TerminalRegexHighlightRule, TerminalRegexHighlightRun, and TerminalRegexHighlightCompiledRule types. Introduces TerminalRegexHighlightSettings to manage persistence in UserDefaults, parse newline/tab-delimited raw configuration, normalize hex color values, track runtime rule existence with locks, and broadcast change notifications. Registers the new terminal.regexHighlights setting path and JSON schema property.
Regex matching logic Sources/App/WorkspaceRuntimeSettings.swift	Implements TerminalRegexHighlightMatcher to compile rules into NSRegularExpression instances, scan terminal lines with row/column offsets, produce TerminalRegexHighlightRun objects with terminal-column-aware widths (including wide-character handling), enforce run limits, and support optional column clipping.
Highlight rendering view Sources/TerminalRegexHighlightOverlayView.swift	Implements TerminalRegexHighlightOverlayView and TerminalRegexHighlightOverlayMetrics to render highlight backgrounds as cell-aligned colored rectangles with inset and rounded corners, parse hex colors (RGB and ARGB with fallback), cache colors, and ignore hit-testing.
Terminal viewport synchronization Sources/GhosttyTerminalView.swift	Integrates overlay into GhosttySurfaceScrollView with: render callback throttling on GHOSTTY_ACTION_RENDER, multi-trigger refresh scheduling (geometry, scroll, visibility, window, attachment), main refresh pipeline (read viewport text, compile/match rules, update overlay), and cleanup on deinit. Keeps overlay frame aligned with viewport through geometry synchronization.
Settings UI, file store, and configuration Sources/cmuxApp.swift, Sources/KeyboardShortcutSettingsFileStore.swift, Sources/KeyboardShortcutSettingsFileStore+Template.swift, Sources/SettingsNavigation.swift	Adds settings UI with TextEditor for regex pattern editing and reset support, extends file store to parse terminal.regexHighlights from JSON/JSONC (string or array), wires managed-defaults side effects, includes default template examples, and adds navigation/search entries.
Test coverage cmuxTests/AgentSessionAutoResumeSettingsTests.swift, cmuxTests/KeyboardShortcutSettingsFileStoreStartupTests.swift	Comprehensive validation: tests for settings parsing/notifications/state, matcher column clipping and wide-character handling, file store loading, and invalid-pattern skipping.
Build configuration GhosttyTabs.xcodeproj/project.pbxproj, web/app/[locale]/docs/configuration/page.tsx	Registers TerminalRegexHighlightOverlayView.swift as a build target source and adds configuration documentation example.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• manaflow-ai/cmux#4318: Modifies GhosttyTerminalView.swift to reroute Ghostty callback handling via a registry, overlapping with this PR's changes to the GHOSTTY_ACTION_RENDER callback.

Poem

🐰 A rabbit hops through terminals bright,
Regex patterns set each line alight!
Colors dance on scrolling views,
Highlights match what users choose.
From configs true to overlays fine,
Text highlights in perfect line!

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (6 errors, 1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Cmux Swift Actor Isolation	❌ Error	TerminalRegexHighlightCompiledRule contains NSRegularExpression without Sendable conformance, causing Swift 6 actor isolation issues when accessed across boundaries.	Mark TerminalRegexHighlightCompiledRule as @unchecked Sendable since NSRegularExpression is internally thread-safe.
Cmux Swift Blocking Runtime	❌ Error	PR introduces Task.sleep and NSLock blocking patterns in production terminal/rendering code without exception justification, violating swift-blocking-runtime guidelines for latency-sensitive paths.	Remove Task.sleep from scheduleRegexHighlightRefresh (use deferred MainActor task instead); replace NSLocks with MainActor-isolated state or document why they're unavoidable platform bridges.
Cmux Swift @Concurrent	❌ Error	New code in GhosttyTerminalView.swift schedules CPU-heavy regex matching via Task { @mainactor ... } without explicit background hop or @concurrent boundary, blocking main thread.	Move TerminalRegexHighlightMatcher.runs() CPU work off MainActor using @concurrent Task or explicit background dispatch before calling refreshRegexHighlightOverlay().
Cmux Swift File And Package Boundaries	❌ Error	WorkspaceRuntimeSettings.swift (428 lines) embeds independent regex matcher logic in app target violating boundaries; TerminalRegexHighlightMatcher doesn't need app lifecycle, AppKit, or globals.	Extract TerminalRegexHighlightMatcher to a separate package target or file with clear protocol boundaries. Reduce responsibilities to stay under 400-line threshold.
Cmux Full Internationalization	❌ Error	New localization keys only provide English and Japanese translations but the catalog supports 19 locales including ar, bs, da, de, es, fr, it, ko, nb, pl, pt-BR, ru, th, tr, uk, zh-Hans, zh-Hant.	Add translated entries for all 19 locales to settings.terminal.regexHighlights and settings.terminal.regexHighlights.subtitle in Resources/Localizable.xcstrings.
Cmux Architecture Rethink	❌ Error	PR introduces NSLock mutable state, Task.sleep throttling, notification observer side-channel, surface access bypass, and regex materialization pattern violations.	Eliminate locks, replace Task.sleep with render coordination, centralize refresh path, use liveSurfaceForGhosttyAccess, and switch to enumerateMatches for matching.
Docstring Coverage	⚠️ Warning	Docstring coverage is 1.79% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Cmux User-Facing Error Privacy	❓ Inconclusive	The referenced policy file .github/review-bot-rules/user-facing-errors.md does not exist in the repository, making the custom check unverifiable against its actual requirements.	Confirm whether the policy file exists or if it should be created. If the check should apply, provide the correct policy file path or its contents to verify compliance.

✅ Passed checks (9 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR successfully implements all core requirements from issue #2788: regex-based highlighting with patterns and colors [#2788], user configuration in Settings UI and cmux.json [#2788], proper terminal column alignment for rendering [#2788], and correct behavior on scroll/resize [#2788].
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing regex-based terminal highlighting: new overlay view, settings management, configuration file support, schema/docs, localization, and tests. No unrelated changes detected.
Cmux No Hacky Sleeps	✅ Passed	PR modifies no TypeScript/JavaScript/shell code with hacky sleeps, timeouts, or polling. Only TypeScript file is documentation; code changes are Swift (separate check).
Cmux Swift Concurrency	✅ Passed	New code uses proper async/await with stored Task cancelled in deinit; notification observers stored and cleaned; no DispatchQueue.global, Combine, completion handlers, or fire-and-forget Tasks.
Cmux Swift Logging	✅ Passed	PR adds 700+ lines of regex highlight feature code with zero logging violations: no print/NSLog in app code, no ad hoc file logging, no MainActor Logger issues, no secret exposure.
Cmux Swiftui State Layout	✅ Passed	PR uses @AppStorage with custom Binding, pure AppKit overlay view, and no problematic SwiftUI patterns. No violations of state layout rules detected.
Cmux Swift Auxiliary Window Close Shortcuts	✅ Passed	PR adds TerminalRegexHighlightOverlayView as an NSView subview in existing terminal view, not a standalone window/panel/WindowGroup requiring close-shortcut ownership.
Title check	✅ Passed	The title clearly and concisely summarizes the main feature: adding regex-based terminal text highlighting, which is the primary change across all modified files.
Description check	✅ Passed	The PR description includes a comprehensive summary of changes, testing approach, risk assessment, and mentions linked issue #2788.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-2788-regex-highlight

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Greptile Summary

Adds regex-based automatic text highlighting for visible terminal output. Users configure patterns (one per line, with an optional #RRGGBB/#RRGGBBAA + tab color prefix) via Settings > Terminal or cmux.json; highlights render as non-interactive rounded-rect overlays aligned to terminal columns, refreshed after each render frame, scroll, resize, and settings change, with a 512-match cap.

• Core logic (WorkspaceRuntimeSettings.swift): TerminalRegexHighlightSettings (UserDefaults + observer), TerminalRegexHighlightMatcher (terminal-column-width-aware matching), and compiled-rule caching to keep matching off the per-frame compile path.
• Rendering (TerminalRegexHighlightOverlayView.swift): standalone NSView with NSBezierPath rounded-rect drawing; frame tracked against terminal bounds in a shared ancestor container view, following the existing drop-zone overlay pattern.
• Integration (GhosttyTerminalView.swift): Task { @MainActor in ... } one-shot coalescing replaces the previous DispatchWorkItem debounce; GHOSTTY_ACTION_RENDER hook triggers refresh via a lock-guarded flag and DispatchQueue.main.async bridge; all schema, search index, localization (20 locales), settings file import, and end-to-end screenshot test also wired.

Confidence Score: 5/5

Presentation-only change with no auth, data, or persistence risk; the overlay is non-interactive and clears when the view is hidden or detached.

All previous review concerns (regex recompilation per scroll, DispatchWorkItem debounce, Thread.isMainThread guard, wide-character column alignment) are addressed in this revision. The Task-based coalescing correctly handles cancellation before the task runs via the isCancelled guard. The NSLock-protected static cache for hasRuntimeRules() on the render thread is correctly scoped and non-reentrant. Localization covers all 20 supported locales. Schema, search index, settings file import, unit tests, and the end-to-end screenshot test are all wired.

No files require special attention.

Important Files Changed

Filename	Overview
Sources/App/WorkspaceRuntimeSettings.swift	Adds 312 lines: TerminalRegexHighlightRule/Run/CompiledRule structs, TerminalRegexHighlightSettings (UserDefaults + lock-guarded runtime cache, double-check observer setup), and TerminalRegexHighlightMatcher (wide-char/CJK-aware column width, 512-match cap). Logic is sound; NSLock usage is correct and non-reentrant paths confirmed safe.
Sources/GhosttyTerminalView.swift	Adds overlay attach/frame/z-order management, Task-based refresh scheduling, GHOSTTY_ACTION_RENDER hook via lock-guarded flag + DispatchQueue.main.async bridge, and viewport text reading via ghostty_surface_read_text. Cancellation on task replacement and rule clearing handled correctly.
Sources/TerminalRegexHighlightOverlayView.swift	New 115-line NSView subclass for overlay drawing: hitTest returns nil (non-interactive), isFlipped=true, NSBezierPath rounded-rect drawing per run with color caching. Guard conditions prevent drawing when metrics or runs are invalid.
Packages/CmuxSettingsUI/Sources/CmuxSettingsUI/Sections/TerminalSection.swift	Adds regexHighlights TextEditor row with monospaced font, min/max height, and localized label/subtitle. Binding writes directly to DefaultsValueModel on change.
Resources/Localizable.xcstrings	Adds settings.terminal.regexHighlights and settings.terminal.regexHighlights.subtitle entries with translations for all 20 supported locales (ar, bs, da, de, en, es, fr, it, ja, km, ko, nb, pl, pt-BR, ru, th, tr, uk, zh-Hans, zh-Hant).
Sources/KeyboardShortcutSettingsFileStore.swift	Parses regexHighlights from cmux.json as either a string or a string array (joined by newlines), logs invalid values, and notifies on managed defaults change.
tests/test_terminal_regex_highlights.py	End-to-end screenshot test: writes config, reloads, sends marker text, captures full-window PNG, counts green pixels to verify overlay visibility. PNG decoded manually in pure Python to avoid third-party image library dependencies.
cmuxTests/AgentSessionAutoResumeSettingsTests.swift	Adds TerminalRegexHighlightSettingsTests covering parser (plain + color-prefix), notification count, reset, and matcher (clipped runs, invalid pattern skipping, CJK column offset).
web/data/cmux.schema.json	Adds regexHighlights schema entry as a oneOf string-or-string-array with description and empty default.

Sequence Diagram

sequenceDiagram
    participant User as User / cmux.json
    participant Settings as TerminalRegexHighlightSettings
    participant ScrollView as GhosttySurfaceScrollView
    participant Ghostty as Ghostty (render thread)
    participant NSView as GhosttyNSView
    participant Overlay as TerminalRegexHighlightOverlayView

    User->>Settings: setRawHighlights() / notifyDidChange()
    Settings-->>ScrollView: didChangeNotification (main queue)
    ScrollView->>ScrollView: reloadRegexHighlightRules() compile NSRegularExpressions once
    ScrollView->>ScrollView: "scheduleRegexHighlightRefresh() Task { @MainActor }"

    Ghostty->>NSView: handleAction(GHOSTTY_ACTION_RENDER)
    NSView->>Settings: hasRuntimeRules() [lock-guarded cache]
    NSView->>NSView: flag + DispatchQueue.main.async
    NSView-->>ScrollView: scheduleRegexHighlightRefreshAfterRender()
    ScrollView->>ScrollView: scheduleRegexHighlightRefresh() coalesced: no-op if task pending

    Note over ScrollView: Task runs on next MainActor turn
    ScrollView->>Ghostty: ghostty_surface_read_text (viewport)
    Ghostty-->>ScrollView: raw UTF-8 text
    ScrollView->>ScrollView: TerminalRegexHighlightMatcher.runs() wide-char column math + 512-match cap
    ScrollView->>Overlay: configure(runs:metrics:)
    Overlay->>Overlay: "needsDisplay = true / draw() NSBezierPath rounded rects"

Loading

_{Reviews (8): Last reviewed commit: "Normalize Xcode project after merge" | Re-trigger Greptile}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 1086baa. Configure here.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@Resources/Localizable.xcstrings`:
- Around line 105483-105516: The two new localization keys
settings.terminal.regexHighlights and settings.terminal.regexHighlights.subtitle
only include en and ja; add matching entries for every locale already present in
this Resources/*.xcstrings catalog (copy other keys’ locales as a template),
providing translated "stringUnit" values with "state":"translated" and the
appropriate localized strings for each locale; ensure the same structure
(extractionState, localizations → <locale> → stringUnit) is used so the catalog
contains a translation entry for every supported locale.

In `@Sources/App/WorkspaceRuntimeSettings.swift`:
- Around line 338-379: The current scalar-based width logic causes mismatches
for multi-scalar grapheme clusters; change terminalColumnWidth(_ text:
Substring) to iterate over grapheme clusters (for character in text) and compute
each cluster's cell width by inspecting that Character's Unicode scalars: if all
scalars are zero-width (use the existing terminalColumnWidth(for:) checks for 0,
ZWJ, variation selectors and generalCategory) treat the cluster as width 0;
otherwise treat the cluster as wide (2) if any scalar in the cluster matches
isWideTerminalScalar(_:) and not otherwise zero-width, else width 1; update any
matcher code in TerminalRegexHighlightOverlayView that relied on per-scalar
accumulation to call the revised terminalColumnWidth(_:) so
run.column/run.length reflect grapheme cell widths.
- Around line 304-330: The code in TerminalRegexHighlightMatcher.runs currently
calls compiledRule.expression.matches(in:range:), which materializes all matches
before you can enforce maxRuns; replace that call with
compiledRule.expression.enumerateMatches(in:options:range:using:) and in the
enumeration closure process each non-optional match (remove the unnecessary
optional binding), compute column/length/clippedLength as before, append
TerminalRegexHighlightRun items, and when runs.count >= maxRuns set the stop
pointer to true to terminate enumeration early; ensure you keep the existing
logic around maxColumnCount and terminalColumnWidth and preserve the
early-continue guards but remove any code that assumed match could be nil.

In `@Sources/GhosttyTerminalView.swift`:
- Around line 12668-12713: This deferred refresh must use
TerminalSurface.liveSurfaceForGhosttyAccess(reason:) instead of reading
surfaceView.terminalSurface?.surface directly because the native surface can be
torn down between scheduling and execution; update the code block that reads and
checks the surface (currently using surfaceView.terminalSurface?.surface,
cmuxSurfacePointerAppearsLive, ghostty_surface_size and readViewportText) to
call surfaceView.terminalSurface?.liveSurfaceForGhosttyAccess(reason: "<describe
purpose>"), guard the returned live surface/token is non-nil, use that live
surface for ghostty_surface_size and readViewportText (and any cmux checks),
then release/let the live access scope end per the liveSurfaceForGhosttyAccess
API before returning; keep the existing fallbacks that call
regexHighlightOverlayView.clear() on early failure and then pass the obtained
surface into TerminalRegexHighlightMatcher.runs and metrics as before.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 92b0ba2c-f9ef-4352-b925-b2cb658e32fd

📥 Commits

Reviewing files that changed from the base of the PR and between 5829da2 and 1086baa.

📒 Files selected for processing (14)

• GhosttyTabs.xcodeproj/project.pbxproj
• Resources/Localizable.xcstrings
• Sources/App/WorkspaceRuntimeSettings.swift
• Sources/CmuxSettingsJSONPathSupport.swift
• Sources/GhosttyTerminalView.swift
• Sources/KeyboardShortcutSettingsFileStore+Template.swift
• Sources/KeyboardShortcutSettingsFileStore.swift
• Sources/SettingsNavigation.swift
• Sources/TerminalRegexHighlightOverlayView.swift
• Sources/cmuxApp.swift
• cmuxTests/AgentSessionAutoResumeSettingsTests.swift
• cmuxTests/KeyboardShortcutSettingsFileStoreStartupTests.swift
• web/app/[locale]/docs/configuration/page.tsx
• web/data/cmux.schema.json

[cubic-dev-ai]

3 issues found across 14 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

All CodeRabbit inline comments from this older review were addressed in later commits, the related review threads are resolved, and the current CodeRabbit check is green on the latest branch head.