Skip to content

feat(settings): import Kitty configs through a shared terminal config import pipeline - #37375

Merged
nwparker merged 6 commits into
mainfrom
nwparker/theme-kitty-import
Nov 2, 2026
Merged

nwparker merged 6 commits into
mainfrom
nwparker/theme-kitty-import

Conversation

@nwparker

@nwparker nwparker commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor
Files Added Deleted Net
Test 4 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​143 $\color{#cf222e}{\Huge{\mathbf{−}}}$​44 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​99
Prod 27 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​892 $\color{#cf222e}{\Huge{\mathbf{−}}}$​265 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​627

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 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.

  • Mapping:

    Kitty Orca
    font_family, including the family="…" spec form Font family
    font_size Font size
    foreground, background, cursor, cursor_text_color, selection_*, color0–color15 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.

Closes #18354

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 before dark after dark
Section, light before light after light

Kitty preview, with the included theme file listed and unsupported keys reported:

Dark Light
kitty dark kitty 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.

Perf

@nwparker
nwparker force-pushed the nwparker/theme-kitty-import branch from 6cec7e8 to 91837c0 Compare November 2, 2026 06:45
@nwparker
nwparker force-pushed the nwparker/theme-ghostty-theme-pairs branch from bec3d72 to ce5696c Compare November 2, 2026 08:13
@nwparker
nwparker force-pushed the nwparker/theme-kitty-import branch from 91837c0 to a612c9f Compare November 2, 2026 08:15
@nwparker
nwparker changed the base branch from nwparker/theme-ghostty-theme-pairs to main November 2, 2026 08:32
@nwparker
nwparker force-pushed the nwparker/theme-kitty-import branch from 6803b30 to 485d481 Compare November 2, 2026 08:32
@coderabbitai

coderabbitai Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review.

Recent review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Repository UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 4123f4b3-595a-40bc-acbb-37032becd051
Commits

Reviewing files that changed from the base of the PR and between 485d481 and 408afd1.

Files selected for processing: 6
  • src/main/ghostty/index.ts
  • src/renderer/src/components/onboarding/ThemeStep.tsx
  • src/renderer/src/components/settings/TerminalConfigImportModal.tsx
  • src/renderer/src/components/settings/useTerminalConfigImport.ts
  • src/renderer/src/i18n/locales/en.json
  • src/shared/terminal-config-import-preview.ts
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: Passed 3 · Failed 2

Failed Failed checks: 2 warnings

Check name Status Explanation Resolution
Linked Issues check Warning [#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 Warning 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 Passed checks: 3 passed
Check name Status Explanation
Title check Passed The title clearly and concisely describes the main change: adding Kitty config import through a shared terminal config pipeline.
Description check Passed 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 Passed 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.

Share

Comment on lines +11 to +31
export function getKittyConfigPaths(): string[] {
const home = homedir()
const explicitDir = process.env.KITTY_CONFIG_DIRECTORY
if (explicitDir) {
return [path.join(expandHome(explicitDir, home), 'kitty.conf')]
}
const plat = platform()
if (plat === 'win32') {
return []
}
const roots = [
process.env.XDG_CONFIG_HOME,
...(process.env.XDG_CONFIG_DIRS ?? '').split(':'),
'~/.config',
...(plat === 'darwin' ? ['~/Library/Preferences'] : [])
]
const dirs = roots
.filter((root): root is string => Boolean(root))
.map((root) => path.posix.join(expandHome(root, home), 'kitty'))
return [...new Set(dirs)].map((dir) => path.posix.join(dir, 'kitty.conf'))
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Functional Correctness · Quick win

Supported by static analysis

Web query:

Kitty terminal configuration file search order XDG_CONFIG_HOME XDG_CONFIG_DIRS ~/.config kitty.conf official documentation

Result:

Sources consulted:
- kitty.conf - kitty — https://sw.kovidgoyal.net/kitty/conf/
- The kitty command line interface - kitty — https://sw.kovidgoyal.net/kitty/invocation/
- kitty/docs/conf.rst at master · kovidgoyal/kitty · GitHub — https://github.com/kovidgoyal/kitty/blob/master/docs/conf.rst
- Selecting files, fast - kitty — https://sw.kovidgoyal.net/kitty/kittens/choose-files/
- Glossary - kitty — https://sw.kovidgoyal.net/kitty/glossary/
- …and 19 more

Script executed:

set -eu
printf '%s\n' '--- src/main/kitty/discovery.ts ---'
nl -ba src/main/kitty/discovery.ts | sed -n '1,110p'
printf '%s\n' '--- direct references ---'
rg -n -F --glob '*.ts' -e 'findKittyConfigPaths' -e 'getKittyConfigPaths' src/main src/shared src/renderer || test "$?" -eq 1
printf '%s\n' '--- automatic import caller ---'
nl -ba src/main/terminal-config-import/preview.ts | sed -n '45,95p'
printf '%s\n' '--- Kitty import entrypoint ---'
nl -ba src/main/kitty/index.ts | sed -n '1,60p'

Repository: stablyai/orca

Length of output: 5930


Preserve Kitty’s configuration precedence.

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.

Suggested fix
  const roots = [
    process.env.XDG_CONFIG_HOME,
-   ...(process.env.XDG_CONFIG_DIRS ?? '').split(':'),
    '~/.config',
+   ...(process.env.XDG_CONFIG_DIRS ?? '').split(':'),
    ...(plat === 'darwin' ? ['~/Library/Preferences'] : [])
  ]
Committable suggestion

IMPORTANT
Review the replacement and indentation, then test before committing.

Suggested change
export function getKittyConfigPaths(): string[] {
const home = homedir()
const explicitDir = process.env.KITTY_CONFIG_DIRECTORY
if (explicitDir) {
return [path.join(expandHome(explicitDir, home), 'kitty.conf')]
}
const plat = platform()
if (plat === 'win32') {
return []
}
const roots = [
process.env.XDG_CONFIG_HOME,
...(process.env.XDG_CONFIG_DIRS ?? '').split(':'),
'~/.config',
...(plat === 'darwin' ? ['~/Library/Preferences'] : [])
]
const dirs = roots
.filter((root): root is string => Boolean(root))
.map((root) => path.posix.join(expandHome(root, home), 'kitty'))
return [...new Set(dirs)].map((dir) => path.posix.join(dir, 'kitty.conf'))
}
export function getKittyConfigPaths(): string[] {
const home = homedir()
const explicitDir = process.env.KITTY_CONFIG_DIRECTORY
if (explicitDir) {
return [path.join(expandHome(explicitDir, home), 'kitty.conf')]
}
const plat = platform()
if (plat === 'win32') {
return []
}
const roots = [
process.env.XDG_CONFIG_HOME,
'~/.config',
...(process.env.XDG_CONFIG_DIRS ?? '').split(':'),
...(plat === 'darwin' ? ['~/Library/Preferences'] : [])
]
const dirs = roots
.filter((root): root is string => Boolean(root))
.map((root) => path.posix.join(expandHome(root, home), 'kitty'))
return [...new Set(dirs)].map((dir) => path.posix.join(dir, 'kitty.conf'))
}

Comment on lines +33 to +47
/** Kitty reads a single kitty.conf: the first location that has one in a writable directory. */
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]
}
} catch {
// Unreadable candidates must not prevent probing the remaining locations.
}
}
return []
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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. */
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]
}
} catch {
// Unreadable candidates must not prevent probing the remaining locations.
}
}
return []
}
/** Kitty reads a single kitty.conf: the first location that has one. */
export async function findKittyConfigPaths(): Promise<string[]> {
for (const configPath of getKittyConfigPaths()) {
try {
if ((await stat(configPath)).isFile()) {
return [configPath]
}
} catch {
// Unreadable candidates must not prevent probing the remaining locations.
}
}
return []
}

Comment thread src/main/kitty/parser.ts
}
return
}
totalBytes += read.content.length

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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.

Suggested change
totalBytes += read.content.length
totalBytes += Buffer.byteLength(read.content, 'utf8')

Source: Learnings

@nwparker
nwparker force-pushed the nwparker/theme-kitty-import branch from 485d481 to 408afd1 Compare November 2, 2026 08:53
@nwparker
nwparker merged commit 2541edc into main Nov 2, 2026
57 checks passed
@nwparker
nwparker deleted the nwparker/theme-kitty-import branch November 2, 2026 09:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Kitty config one-click import (parity with Ghostty, partial mapping to orca-terminal)

1 participant