feat(cli): add Sublime Text and Emacs Client editors, improve error messages and documentation

[alberti42]

Summary

Addresses #21084 by improving external editor support across three areas: adds
Sublime Text and Emacs Client to the built-in editor list, emits clear
error messages when editor configuration is invalid or a command is missing, and
extends the documentation and JSON schema for preferredEditor.

Details

New editors (packages/core/src/utils/editor.ts):

• Sublime Text (sublime): added as a GUI editor using the subl command.
  Opens files with --wait. Diff view opens the new file only, as subl does
  not support a --diff flag.
• Emacs Client (emacsclient): added as a terminal editor. Automatically
  injects -nw (terminal mode) when opening a file. Diff view uses
  emacsclient -nw --eval "(ediff ...)", consistent with the existing emacs
  implementation.

Error handling (packages/cli/src/ui/utils/editorUtils.ts):

Two cases that previously produced a cryptic internal error are now handled
gracefully:

1. Unrecognized preferredEditor: validates the editor type before use and
   emits a user-friendly message instead of a generic error. For example,
   setting "preferredEditor": "nvim" (the binary name) instead of the
   supported identifier "neovim" previously produced:

   ✕ [useTextBuffer] external editor error
   

   It now produces:

   ✕ Editor 'nvim' is not recognized or not installed. Run /editor to pick a
     supported editor, or set $VISUAL/$EDITOR in your shell to your preferred
     editor.
   

2. Missing $VISUAL/$EDITOR command: detects ENOENT on spawn and emits
   a clear message pointing the user to check their environment variable.

Note: $VISUAL/$EDITOR continue to accept any editor command, not just the
built-in supported types, preserving full flexibility for power users.

Documentation (docs/reference/configuration.md,
schemas/settings.schema.json, packages/cli/src/config/settingsSchema.ts):

• The description field for preferredEditor in settingsSchema.ts has been
  updated to explain the built-in identifier requirement, the /editor command
  as the canonical way to discover supported values, and the $VISUAL/$EDITOR
  escape hatch for power users. Both docs/reference/configuration.md and
  schemas/settings.schema.json are regenerated from this source and updated
  accordingly.

Related Issues

Closes #21084

Note for maintainers: enum constraint in the JSON schema

The current implementation leaves preferredEditor typed as a plain string in
settingsSchema.ts, so the JSON schema carries no enum constraint and IDEs
offer no autocomplete for valid editor identifiers.

A cleaner solution would be to change the definition to type: 'enum' and list
the supported values via options, mirroring how defaultApprovalMode is
defined. This would cause the generation script to emit an enum array in the
JSON schema and a Values: line in the documentation automatically, and would
keep everything in sync with the code. For example:

preferredEditor: {
  type: 'enum',
  label: 'Preferred Editor',
  category: 'General',
  requiresRestart: false,
  default: undefined as EditorType | undefined,
  description: '...',
  showInDialog: false,
  options: (EDITORS as readonly EditorType[]).map((e) => ({
    value: e,
    label: EDITOR_DISPLAY_NAMES[e],
  })),
},

This is a slightly more invasive change (it touches the settings type system and
may affect dialog rendering), so I have left it out of this PR. I am happy to
implement it based on your feedback.

How to Validate

Sublime Text:

1. Set "preferredEditor": "sublime" in ~/.gemini/settings.json
2. Open Gemini CLI and press CTRL-X to open the external editor
3. Sublime Text should open the buffer file and wait until it is closed

Emacs Client:

1. Start an Emacs daemon: emacs --daemon
2. Set "preferredEditor": "emacsclient" in ~/.gemini/settings.json
3. Open Gemini CLI and press CTRL-X to open the external editor
4. Emacs Client should open in terminal mode (-nw) and wait until the buffer
   is closed

Graceful error for unrecognized preferredEditor:

1. Set "preferredEditor": "emacsclient -nw" in ~/.gemini/settings.json
2. Press CTRL-X in Gemini CLI
3. Expected:
   Editor 'emacsclient -nw' is not recognized or not installed. Run /editor to pick a supported editor, or set $VISUAL/$EDITOR in your shell to your preferred editor.
4. Expected: no crash, no unhandled promise rejection

Graceful error for missing $VISUAL/$EDITOR command:

1. Run export EDITOR="nonexistent-editor" in your shell
2. Remove preferredEditor from settings.json
3. Press CTRL-X in Gemini CLI
4. Expected:
   Could not find editor 'nonexistent-editor'. Check your $VISUAL/$EDITOR setting.
5. Expected: no crash, no unhandled promise rejection

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the external editor integration for the CLI, making it more robust and user-friendly. It expands the range of supported editors, provides more informative feedback for common configuration issues, and updates all relevant documentation to guide users effectively.

Highlights

• New Editor Support: Added Sublime Text and Emacs Client to the list of built-in supported external editors.
• Improved Error Handling: Implemented clearer and more user-friendly error messages for unrecognized preferredEditor configurations and missing editor commands.
• Enhanced Documentation: Updated documentation and JSON schema for preferredEditor to provide better guidance on configuration and supported values.

Changelog

• docs/reference/configuration.md
  • Updated the description for general.preferredEditor to clarify supported identifiers and the use of $VISUAL/$EDITOR.
• packages/cli/src/config/settingsSchema.ts
  • Modified the description for preferredEditor to include guidance on built-in identifiers and environment variables.
• packages/cli/src/ui/utils/editorUtils.ts
  • Imported isEditorAvailable for editor validation.
  • Added logic to check preferredEditorType availability and emit a user-friendly error if unrecognized.
  • Introduced handleEditorError function to provide specific error messages for ENOENT (command not found) and general editor errors.
  • Injected -nw argument for emacsclient when opening files in terminal mode.
• packages/core/src/utils/editor.test.ts
  • Added test cases for sublime and emacsclient in getEditorCommands.
  • Included new tests for getDiffCommand specifically for emacsclient (with escaped paths) and sublime.
  • Updated guiEditors and terminalEditors lists for sandbox mode tests to include sublime and emacsclient respectively.
  • Added tests for allowEditorTypeInSandbox for emacsclient.
• packages/core/src/utils/editor.ts
  • Added sublime to GUI_EDITORS and emacsclient to TERMINAL_EDITORS.
  • Updated EDITOR_DISPLAY_NAMES to include 'Emacs Client' and 'Sublime Text'.
  • Added command definitions for emacsclient and sublime in editorCommands.
  • Modified getDiffCommand to handle sublime (opening only the new file) and emacsclient (with -nw and ediff eval).
• schemas/settings.schema.json
  • Updated the description and markdownDescription for preferredEditor to match the new guidance.

Activity

• No human activity has been recorded on this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds support for Sublime Text and Emacs Client as external editors and enhances error handling for editor configurations, along with clear documentation updates. However, a critical command injection vulnerability was identified in packages/cli/src/ui/utils/editorUtils.ts due to the unsafe handling of VISUAL and EDITOR environment variables, potentially leading to Remote Code Execution. Additionally, one issue in the new test code requires attention for correctness.

[jacob314]

This descript is too long. Descriptions need to fit in the UI.

[alberti42]

Thanks for reviewing it. I shortened the description.

[alberti42]

See commit 15bda94

[jacob314]

Tweak so you can specify a separate longer markdown description from the short description suitable for the TUI.

[alberti42]

I shortened the description in 15bda94.

The file schemas/settings.schema.json is automatically generated by npm run docs:settings.

The new commit already contains the newly generated one.

[alberti42]

Update: I've integrated the work from the duplicate PR #21377 by @AnanthKini1 into this branch. His commits have been cherry-picked on top of mine with authorship preserved.

His additions beyond what was already in this PR:

• Fixed an infinite re-render loop in EditorSettingsDialog (emitFeedback called inside render body)
• Added --new-window flag for VS Code-family editors (Cursor, Windsurf, VSCodium) so the editor opens directly to the file instead of the Welcome screen
• Fixed maxItemsToShow so all editors are visible in the /editor picker
• Expanded editor support: Lapce, Nova, BBEdit, Micro, Sublimetext (renamed from sublime)
• Smarter $VISUAL/$EDITOR handling: extra args and wait flags now apply even when the editor is set via environment variable

I also fixed a documentation issue: schemas/settings.schema.json and docs/reference/configuration.md are auto-generated from settingsSchema.ts, so I moved the enum values there to make them permanent.

[jacob314]

revert changes to this file

[alberti42]

Done: I removed the package-lock.json changes from the commit history.

[jacob314]

these duplicate options in editor.ts. Please Refactor so they don't have to be duplicated or remove this. Including these entries here isn't crucial as this is hidden from the settings dialog but would be nice to have so it ends up in settings.schema.json

[alberti42]

Done. The fix is in commit "refactor: derive preferredEditor options from EDITOR_OPTIONS"

[jacob314]

add these to a const rather than including them here

[alberti42]

done → changes are in commit "refactor: extract HEURISTIC_GUI_COMMANDS const"

[jacob314]

emitFeedback is preferred to throwing an exception. why this change?

[alberti42]

done: see commit "fix: replace throw with emitFeedback in openFileInEditor"

[jacob314]

addubg new window will be frustrating for some users. If I have a project open in vscode why do I want a new window? Would suggest protecting this behind a setting.

[alberti42]

done: see commit → "feat: guard --new-window behind openEditorInNewWindow setting"

[jacob314]

Added some comments. once these are addressed this can be approved.

[alberti42]

I split the resolution of concerns into different commits for easier review/understanding. If needed, we can squash things at the end.

[alberti42]

Done. The fix is in commit "refactor: derive preferredEditor options from EDITOR_OPTIONS"

[alberti42]

done → changes are in commit "refactor: extract HEURISTIC_GUI_COMMANDS const"

[alberti42]

done: see commit "fix: replace throw with emitFeedback in openFileInEditor"

[alberti42]

done: see commit → "feat: guard --new-window behind openEditorInNewWindow setting"

[alberti42]

Looks like we have failing tests and lint. Please update and I will review right away.

@scidomino Thanks for looking into it. I rebased and force-pushed. Luckily, there were no conflicts to resolve.

I also added two commits:

• 8af6a6c to resolve the failing tests you mentioned.
• b3f6642 to fix a lint issue in EditorSettingsDialog.tsx

[scidomino]

We have some test failures. please make sure that npm run preflight passes and is not OS specific.

[alberti42]

Thanks for reviewing it. Indeed, I had only run tests on macOS. I just pushed two new commits:

• e509136: pins process.platform to linux in the emacs test related to getDiffCommand. This fix follows the same pattern used in several other tests in the file.
• e8a0acc: fixes resolveEditorTypeFromCommand so it recognizes editor commands across all platforms. The function previously only checked the current OS's command list, which meant Windows-only command aliases (e.g. code.cmd) and non-Windows aliases typical of other platforms (e.g. code) were not recognized.

Regarding e8a0acc, this change was triggered by two tests failing on Windows:

    it('should resolve known command names to their editor type', () => {
      expect(resolveEditorTypeFromCommand('cursor')).toBe('cursor');
      expect(resolveEditorTypeFromCommand('code')).toBe('vscode');
      expect(resolveEditorTypeFromCommand('codium')).toBe('vscodium');
      expect(resolveEditorTypeFromCommand('vim')).toBe('vim');
    });

    it('should be case-insensitive', () => {
      expect(resolveEditorTypeFromCommand('Cursor')).toBe('cursor');
      expect(resolveEditorTypeFromCommand('CODE')).toBe('vscode');
    });

Both the function resolveEditorTypeFromCommand and these two tests are new in this PR, originally written by the other co-contributor, @AnanthKini1, and cherry-picked into this branch by myself. The tests were written without pinning process.platform because the substring matcher being replaced was already cross-platform, so the expectation was that the new lookup would behave the same way. The bug was that the lookup ended up implemented as platform-specific.

There were two ways to make these tests pass: pin process.platform to Linux in the two tests (like I did for the Emacs test), or fix resolveEditorTypeFromCommand so it recognizes commands from both the default and win32 lists. I chose the second one for the reason explained below:

Even without e8a0acc, a Windows user with $EDITOR=code would still be able to launch VS Code: there is a heuristic fallback in editorUtils.ts that catches code (and cursor, subl, etc.) and applies --wait. So EDITOR=code keeps working on Windows either way. What is lost on the heuristic fallback path is getEditorExtraArgs - in particular the new --new-window flag this PR introduces alongside the openEditorInNewWindow setting. The result would be an asymmetry: a macOS or Linux user with $EDITOR=code and openEditorInNewWindow: true would correctly get --new-window applied, while a Windows user with the same settings would silently not, even though code would be a recognized command.

Pinning the tests to Linux would have left this asymmetry in place, and routing a recognized command through the heuristic fallback on purpose did not feel like something anyone would actually want. With the commit e8a0acc, I am now fixing the function so the new openEditorInNewWindow setting behaves consistently across platforms; this seemed like the cleaner approach, unless I am missing something else. Let me know if you think there is anything we should revisit or if you have other design preferences.

PS: After I finished composing this reply, I saw the PR was moved into the queue for merge. Thank you! I'm leaving the explanation above as a record for anyone who later looks at e8a0acc. Perhaps there will be minor fixes/corrections to this PR in the future, and it would then be useful to reconstruct the reasoning.