You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat(settings): import Kitty configs through a shared terminal config import pipeline - #37375
This adds a one-click Import from Kitty, next to Import from Ghostty. To do that, the Ghostty-only import becomes one shared terminal config import pipeline: discover a config or pick a file, parse it, map it to an Orca settings patch, preview it with the unsupported keys listed, then apply.
Root cause: the import pipeline (reading, the size and regular-file guards, the file picker, diffing against current settings, the preview modal and the apply path) was hard-wired to Ghostty, so a second terminal would have meant a parallel copy. It is now src/main/terminal-config-import/, with format-specific parsers and mappers plugged in as TerminalConfigImporters:
src/main/ghostty/index.ts is now just the Ghostty importer.
src/main/kitty/ is new: discovery, parser and mapper.
The renderer reuses the existing modal and hook, renamed to TerminalConfigImportModal and useTerminalConfigImport, with per-format copy. No new UI.
Kitty semantics follow Kitty's own source (tools/utils/paths.go, kitty/conf/utils.py):
Discovery:KITTY_CONFIG_DIRECTORY, then $XDG_CONFIG_HOME, $XDG_CONFIG_DIRS, ~/.config, and on macOS ~/Library/Preferences. The first kitty/kitty.conf found wins. Kitty has no Windows build, so on Windows only KITTY_CONFIG_DIRECTORY or a picked file applies.
Syntax:key value lines, \ continuation lines, and # only as a whole-line comment.
include / globinclude:
Paths resolve relative to the including file, with ~, $VAR and ${KITTY_OS} expansion.
Repeated files are deduped by real path, so symlinked directories cannot loop.
Missing includes are skipped silently, as Kitty does.
Limits: 64 files and 4 MB in total, each file still capped at 1 MB and required to be a regular file.
globinclude supports wildcards in the file name only (themes/*.conf). Wildcards in directory names are reported as unsupported.
geninclude and envinclude are never run or read. They are listed as unsupported.
Color overrides, merged into the active light/dark slot the same way as the Ghostty import
cursor_shape
Cursor style
cursor_blink_interval
Cursor blink
background_opacity
Background opacity
background_blur
Window material
window_padding_width, 1–4 values
Padding X and Y
macos_option_as_alt (macOS only)
Option as Alt
Everything else (map, tab_bar_*, …) is listed as unsupported. *-theme.auto.conf appearance themes are detected and reported, not imported.
The picker from #37353 works for Kitty too. A picked kitty.conf follows its includes relative to its own folder. Like the Ghostty import, Kitty import is hidden on the paired web client, because it reads files on the machine where Orca's main process runs.
Stacked on #37368, which is stacked on #37353. This PR will be retargeted to main as those land.
Visual proof
These screenshots use a throwaway HOME and XDG_CONFIG_HOME with a kitty.conf that does include current-theme.conf.
Before (origin/main)
After
Section, dark
Section, light
Kitty preview, with the included theme file listed and unsupported keys reported:
Dark
Light
Merge-risk assessment: Low
Blast radius:
The Ghostty import's main-process code was moved behind the shared pipeline. Behavior is the same, and the existing Ghostty test suites pass unchanged except for renamed imports.
The renderer hook and modal were renamed and generalized. One new IPC channel, settings:previewKittyImport, was added.
The import IPC handlers moved into src/main/ipc/settings-import-handlers.ts, which keeps settings.ts under its line limit.
Back-compat: no settings schema changes. Kitty writes the same keys as the Ghostty import. The preview type was renamed from GhosttyImportPreview to TerminalConfigImportPreview. Preload and main ship together, so there is no mixed-version IPC.
Security: the renderer can still only send { kind }. Kitty includes are bounded, deduped by real path and never executed.
Negative user-facing tradeoffs
Kitty's per-appearance dark-theme.auto.conf / light-theme.auto.conf themes are not imported. They are only listed as unsupported, so their colors do not come across.
globinclude with wildcards in directory names is not followed. It is listed as unsupported.
font_family monospace (Kitty's "system default") is reported as unsupported rather than mapped.
There is no onboarding detection for Kitty. Onboarding still offers only the Ghostty import.
There is one more button in Settings → Terminal Typography.
font_size and window_padding_width are copied 1:1, the same as the Ghostty import. On Linux displays where Kitty renders 1pt as more than 1px (96 DPI), imported text looks a bit smaller in Orca than in Kitty.
Validation
pnpm tc:node and pnpm tc:web are clean.
pnpm test src/main/kitty src/main/ghostty src/main/ipc src/main/warp-themes src/renderer/src/components/settings src/renderer/src/components/onboarding passes. The new kitty-import.test.ts uses real temp dirs and checks:
include, globinclude and continuation lines are followed;
geninclude is not run;
values Orca can't represent are reported, including the constructor prototype-key case.
oxlint and oxfmt were run on the changed files. verify:localization-extraction and verify:localization-coverage pass; the Kitty product-name keywords are allowlisted like Ghostty's.
Real app checks used a dev build with ORCA_BACKGROUND_LAUNCH=1, CDP port 9365, and a throwaway HOME, XDG_CONFIG_HOME and user-data dir:
Import from Kitty previewed kitty.conf and the included current-theme.conf.
Apply persisted font Iosevka Term, size 15, cursor bar, blink off, opacity 0.92 and padding 10/6. The colors went into the active (light) slot.
Choose Config File on ~/dotfiles/kitty/kitty.conf followed its sibling include and reported geninclude as unsupported. The native dialog was stubbed through the main-process inspector.
Import from Ghostty still worked through the shared modal.
Reviews:
One Opus sub-agent. I fixed every finding:
prototype-key lookups now use Maps;
values are case-insensitive, and Kitty's boolean spellings are accepted;
a malformed globinclude no longer crashes;
numbers are bounded;
includes have a total-bytes budget and are deduped by realpath;
ENOENT includes are skipped quietly;
leftover code and mixed path separators were cleaned up.
Codex (gpt-6.1-sol, xhigh) finished after the first push. I fixed:
[P1] a translated * regex could backtrack exponentially. It is now a linear */? matcher, and bracket globs are reported as unsupported;
[P2] bracket globs selected the wrong files;
[P2] a read-only system XDG_CONFIG_DIRS config could shadow the user's own config. Discovery now applies Kitty's writable-directory check;
[P2]postscript_name= and full_name= font selectors were imported as family names. They are now reported as unsupported.
Not changed: Kitty's point sizes are copied 1:1 into Orca's px sizes. This matches the existing Ghostty import and macOS's 1pt = 1px. See tradeoffs.
up to 4 stat calls for discovery, stopping at the first hit;
one bounded read per included file, at most 64 files and 4 MB in total;
at most one readdir per globinclude, capped at 1,000 entries;
3 stat calls for the auto-theme files.
Measured in the dev build over 30 runs: the Kitty preview (2 files) took p50 0.50 ms / p95 0.80 ms. The Ghostty preview through the shared pipeline took p50 0.80 ms / p95 1.00 ms, comparable to before the refactor (feat(settings): let the Ghostty import read a config file you pick #37353: p50 0.60 ms).
Files skipped from review as they are similar to previous changes: 1
src/renderer/src/i18n/locales/en.json
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 1 remain after this review.
Walkthrough
The change adds Kitty configuration discovery, parsing, supported-option mapping, and preview generation. Ghostty previews now use shared terminal-configuration types and preview handling. Settings IPC, preload interfaces, and the renderer expose both import formats through a shared hook and modal. Search entries, localized copy, onboarding types, and tests are updated.
Merge Risk: Low · up to 408af
Kitty imports can exceed the intended total file-size limit for multibyte configurations. This is a bounded risk to address or explicitly accept before merging.
Pre-merge checks: 3 · 2
Failed checks: 2 warnings
Check name
Status
Explanation
Resolution
Linked Issues check
[#18354] Implemented: shared import pipeline (src/main/terminal-config-import/), Kitty discovery (src/main/kitty/discovery.ts), include and globinclude loading with real-path dedupe and 64-file/4 MB l…
Either implement these requirements or obtain an explicit scope decision from the issue owner that drops them. To implement: (a) in parseKittyLines, accept key=value in addition to key value, and strip # comments that follow whitespac…
Docstring Coverage
Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documenta…
Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed checks: 3 passed
Check name
Status
Explanation
Title check
The title clearly and concisely describes the main change: adding Kitty config import through a shared terminal config pipeline.
Description check
The description is mostly complete and covers the user-facing change, implementation, rationale, linked issue, visual proof, testing, risks, tradeoffs, compatibility, security, and performance. It doe…
Out of Scope Changes check
Changed files map to the Kitty import or to the shared-pipeline refactor needed for it: src/main/kitty/* (discovery, parser, mapper, index, tests), src/main/terminal-config-import/* (shared preview, r…
Full details: Description check
Explanation
The description is mostly complete and covers the user-facing change, implementation, rationale, linked issue, visual proof, testing, risks, tradeoffs, compatibility, security, and performance. It does not use every template heading, and some checklist items and AI disclosure details are absent, but the required change context is sufficiently documented.
Full details: Out of Scope Changes check
Explanation
Changed files map to the Kitty import or to the shared-pipeline refactor needed for it: src/main/kitty/* (discovery, parser, mapper, index, tests), src/main/terminal-config-import/* (shared preview, reader, settings-changes), the Ghostty importer rewritten as a TerminalConfigImporter in src/main/ghostty/index.ts, renamed shared types and hooks, the modal generalized to TerminalConfigImportModal, the IPC handlers moved to settings-import-handlers.ts, the preload API addition for previewKittyImport, locale strings, the localization allowlist, and the search entry for Kitty. The Ghostty theme code (src/main/ghostty/theme-mapping.ts) exists at the merge base, and the current whole-PR file summary does not list theme-mapping, theme-resolution, or warp-themes changes. The prior concern about added Ghostty theme mapping and Warp theme changes is therefore not present at the reviewed head. Ghostty theme handling is only reached through the new importer. The evidence is the whole-PR file summary and one base file read; the full diff was not read.
Full details: Linked Issues check
Explanation
[#18354] Implemented: shared import pipeline (src/main/terminal-config-import/), Kitty discovery (src/main/kitty/discovery.ts), include and globinclude loading with real-path dedupe and 64-file/4 MB limits, mapping for fonts, colors, opacity, blur, cursor, padding, and macOS option-as-alt, unsupported-key reporting, preview/apply through TerminalConfigImportModal, and tests in src/main/kitty/kitty-import.test.ts. Unmet explicit requirements in src/main/kitty/parser.ts and discovery.ts at the reviewed head:
(1) Syntax: KEY_RE = /^([a-zA-Z][a-zA-Z0-9_-]*)\s+(.+)$/ accepts only whitespace-separated key value. The issue requires key=value support. The PR description states that Kitty's own syntax is key value only. This conflicts with the issue text, and the issue text is the stated requirement.
(2) Comments: # is treated only as a whole-line comment. The issue requires stripping # after whitespace outside quotes. The PR description deliberately follows Kitty's behavior.
(3) font_family precedence: loadFile calls options.delete(key) then options.set(key, value), so the last font_family wins. The issue requires first valid entry to win (avoids #15985).
(4) Include depth: no depth counter exists in loadFile. The issue requires depth 10. The PR substitutes a 64-file cap and realpath dedupe. Cycle protection is present; the depth limit is not.
(5) Windows: getKittyConfigPaths returns no candidates on Windows per the summary. The issue requires Win32 %APPDATA%/kitty/kitty.conf. The PR description states Kitty has no Windows build, so this is a documented deviation.
Requirements (1) to (5) are not implemented. Tests do not cover font_family precedence or key=value parsing.
Resolution
Either implement these requirements or obtain an explicit scope decision from the issue owner that drops them. To implement: (a) in parseKittyLines, accept key=value in addition to key value, and strip # comments that follow whitespace outside quotes; (b) in loadKittyConfig, keep the first valid font_family value and ignore later ones; (c) pass a depth counter through loadFile and stop including files at depth 10; (d) add a Windows candidate built with path.win32.join(%APPDATA%, 'kitty', 'kitty.conf') in getKittyConfigPaths, or record the waiver in the issue. Add focused tests for each case in kitty-import.test.ts. Update the PR description if the decision is to drop any requirement.
Full details: Docstring Coverage
Explanation
Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 36 functions across 28 files. (1 skipped: 1 unsupported.)
Resolution
Write docstrings for the functions missing them to satisfy the coverage threshold.
Finishing Touches
Generate docstrings
Commit to this branch
Create a new PR
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
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.
When both candidates exist, place ~/.config before XDG_CONFIG_DIRS. The current order can import a system configuration instead of the user configuration that Kitty selects.
The reason will be displayed to describe this comment to others. Learn more.
Minor · Functional Correctness · Quick win
Do not require write access to the Kitty config directory.
When the process can read kitty.conf but cannot write its parent directory, await access(path.dirname(configPath), constants.W_OK) skips the file. Automatic import then returns found: false, even though the importer only reads the config.
Suggested fix
-import { constants } from 'node:fs'-import { access, stat } from 'node:fs/promises'+import { stat } from 'node:fs/promises'-/** Kitty reads a single kitty.conf: the first location that has one in a writable directory. */+/** Kitty reads a single kitty.conf: the first location that has one. */
export async function findKittyConfigPaths(): Promise<string[]> {
for (const configPath of getKittyConfigPaths()) {
try {
- // The writability check keeps a read-only system default (e.g. /etc/xdg) from shadowing the user's config.
if ((await stat(configPath)).isFile()) {
- await access(path.dirname(configPath), constants.W_OK)
return [configPath]
}
Committable suggestion
IMPORTANT
Review the replacement and indentation, then test before committing.
Suggested change
/** Kitty reads a single kitty.conf: the first location that has one in a writable directory. */
The reason will be displayed to describe this comment to others. Learn more.
Minor · Functional Correctness · Quick win
Count UTF-8 bytes, not UTF-16 code units, for the total-bytes limit.
MAX_TOTAL_BYTES limits bytes. read.content.length counts UTF-16 code units. For multi-byte text, length is lower than the real byte count. The readConfigFile size check already uses bytes (info.size), so the two limits are inconsistent. A set of included files with non-ASCII content can read well past the 4 MB limit before this check fires. Use Buffer.byteLength.
Proposed fix
--- "a/src/main/kitty/parser.ts"+++ "b/src/main/kitty/parser.ts"@@ -143,7 +143,7 @@
}
return
}
- totalBytes += read.content.length+ totalBytes += Buffer.byteLength(read.content, 'utf8')
if (totalBytes > MAX_TOTAL_BYTES) {
unsupportedKeys.add(`include (more than ${MAX_TOTAL_BYTES} bytes in total)`)
return
Based on learnings: "Flag Node.js/TypeScript checks using str.length as the byte count for a UTF-8 'max bytes' limit."
Committable suggestion
IMPORTANT
Review the replacement and indentation, then test before committing.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This adds a one-click Import from Kitty, next to Import from Ghostty. To do that, the Ghostty-only import becomes one shared terminal config import pipeline: discover a config or pick a file, parse it, map it to an Orca settings patch, preview it with the unsupported keys listed, then apply.
Root cause: the import pipeline (reading, the size and regular-file guards, the file picker, diffing against current settings, the preview modal and the apply path) was hard-wired to Ghostty, so a second terminal would have meant a parallel copy. It is now
src/main/terminal-config-import/, with format-specific parsers and mappers plugged in asTerminalConfigImporters:src/main/ghostty/index.tsis now just the Ghostty importer.src/main/kitty/is new: discovery, parser and mapper.TerminalConfigImportModalanduseTerminalConfigImport, with per-format copy. No new UI.Kitty semantics follow Kitty's own source (
tools/utils/paths.go,kitty/conf/utils.py):Discovery:
KITTY_CONFIG_DIRECTORY, then$XDG_CONFIG_HOME,$XDG_CONFIG_DIRS,~/.config, and on macOS~/Library/Preferences. The firstkitty/kitty.conffound wins. Kitty has no Windows build, so on Windows onlyKITTY_CONFIG_DIRECTORYor a picked file applies.Syntax:
key valuelines,\continuation lines, and#only as a whole-line comment.include/globinclude:~,$VARand${KITTY_OS}expansion.globincludesupports wildcards in the file name only (themes/*.conf). Wildcards in directory names are reported as unsupported.genincludeandenvincludeare never run or read. They are listed as unsupported.Mapping:
font_family, including thefamily="…"spec formfont_sizeforeground,background,cursor,cursor_text_color,selection_*,color0–color15cursor_shapecursor_blink_intervalbackground_opacitybackground_blurwindow_padding_width, 1–4 valuesmacos_option_as_alt(macOS only)Everything else (
map,tab_bar_*, …) is listed as unsupported.*-theme.auto.confappearance themes are detected and reported, not imported.The picker from #37353 works for Kitty too. A picked
kitty.conffollows its includes relative to its own folder. Like the Ghostty import, Kitty import is hidden on the paired web client, because it reads files on the machine where Orca's main process runs.Closes #18354
Stacked on #37368, which is stacked on #37353. This PR will be retargeted to
mainas those land.Visual proof
These screenshots use a throwaway
HOMEandXDG_CONFIG_HOMEwith akitty.confthat doesinclude current-theme.conf.Kitty preview, with the included theme file listed and unsupported keys reported:
Merge-risk assessment: Low
settings:previewKittyImport, was added.src/main/ipc/settings-import-handlers.ts, which keepssettings.tsunder its line limit.GhosttyImportPreviewtoTerminalConfigImportPreview. Preload and main ship together, so there is no mixed-version IPC.{ kind }. Kitty includes are bounded, deduped by real path and never executed.Negative user-facing tradeoffs
dark-theme.auto.conf/light-theme.auto.confthemes are not imported. They are only listed as unsupported, so their colors do not come across.globincludewith wildcards in directory names is not followed. It is listed as unsupported.font_family monospace(Kitty's "system default") is reported as unsupported rather than mapped.font_sizeandwindow_padding_widthare copied 1:1, the same as the Ghostty import. On Linux displays where Kitty renders 1pt as more than 1px (96 DPI), imported text looks a bit smaller in Orca than in Kitty.Validation
pnpm tc:nodeandpnpm tc:webare clean.pnpm test src/main/kitty src/main/ghostty src/main/ipc src/main/warp-themes src/renderer/src/components/settings src/renderer/src/components/onboardingpasses. The newkitty-import.test.tsuses real temp dirs and checks:include,globincludeand continuation lines are followed;genincludeis not run;constructorprototype-key case.verify:localization-extractionandverify:localization-coveragepass; the Kitty product-name keywords are allowlisted like Ghostty's.ORCA_BACKGROUND_LAUNCH=1, CDP port 9365, and a throwawayHOME,XDG_CONFIG_HOMEand user-data dir:kitty.confand the includedcurrent-theme.conf.Iosevka Term, size 15, cursorbar, blink off, opacity 0.92 and padding 10/6. The colors went into the active (light) slot.~/dotfiles/kitty/kitty.conffollowed its siblingincludeand reportedgenincludeas unsupported. The native dialog was stubbed through the main-process inspector.One Opus sub-agent. I fixed every finding:
globincludeno longer crashes;ENOENTincludes are skipped quietly;Codex (
gpt-6.1-sol, xhigh) finished after the first push. I fixed:*regex could backtrack exponentially. It is now a linear*/?matcher, and bracket globs are reported as unsupported;XDG_CONFIG_DIRSconfig could shadow the user's own config. Discovery now applies Kitty's writable-directory check;postscript_name=andfull_name=font selectors were imported as family names. They are now reported as unsupported.Not changed: Kitty's point sizes are copied 1:1 into Orca's px sizes. This matches the existing Ghostty import and macOS's 1pt = 1px. See tradeoffs.
Perf
statcalls for discovery, stopping at the first hit;readdirperglobinclude, capped at 1,000 entries;statcalls for the auto-theme files.