feat(cli): add Sublime Text and Emacs Client editors, improve error messages and documentation by alberti42 · Pull Request #21090 · google-gemini/gemini-cli

alberti42 · 2026-03-04T10:32:34Z

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:

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

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

Emacs Client:

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

Graceful error for unrecognized preferredEditor:

Set "preferredEditor": "emacsclient -nw" in ~/.gemini/settings.json
Press CTRL-X in Gemini CLI
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.
Expected: no crash, no unhandled promise rejection

Graceful error for missing $VISUAL/$EDITOR command:

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

Pre-Merge Checklist

gemini-code-assist · 2026-03-04T10:36:44Z

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.

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 · 2026-03-04T17:29:21Z

        default: undefined as string | undefined,
-        description: 'The preferred editor to open files in.',
+        description:
+          'The preferred editor to open files in. Must be one of the built-in supported identifiers — run /editor in the CLI for the full list. Power users who need an editor not in this list can leave this unset and configure $VISUAL or $EDITOR in their shell environment instead.',


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

Thanks for reviewing it. I shortened the description.

See commit 15bda94

jacob314 · 2026-03-04T17:30:37Z

@@ -41,8 +41,8 @@
      "properties": {
        "preferredEditor": {
          "title": "Preferred Editor",
-          "description": "The preferred editor to open files in.",
-          "markdownDescription": "The preferred editor to open files in.\n\n- Category: `General`\n- Requires restart: `no`",
+          "description": "The preferred editor to open files in. Must be one of the built-in supported identifiers — run /editor in the CLI for the full list. Power users who need an editor not in this list can leave this unset and configure $VISUAL or $EDITOR in their shell environment instead.",


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

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.

jacob314 requested a shorter description to fit the TUI. This was already addressed in PR google-gemini#21090 via settingsSchema.ts. Regenerate schema from source of truth and restore the accepted-values table in configuration.md.

alberti42 · 2026-03-06T23:18:36Z

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 · 2026-03-09T23:33:14Z

    "node_modules/@octokit/core": {
      "version": "7.0.5",
      "resolved": "https://registry.npmjs.org/@octokit/core/-/core-7.0.5.tgz",
      "integrity": "sha512-t54CUOsFMappY1Jbzb7fetWeO0n6K0k/4+/ZpkS+3Joz8I4VcvY9OiEBFRYISqaI2fq5sCiPtAjRDOzVYG8m+Q==",


revert changes to this file

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

jacob314 · 2026-03-09T23:35:03Z

+          or leave unset to use $VISUAL/$EDITOR.
+        `,
        showInDialog: false,
+        options: [


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

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

jacob314 · 2026-03-09T23:35:33Z

+      } else {
+        // Heuristic fallback for commands not in the registry
+        const lower = envCommand.toLowerCase();
+        const isGui = ['code', 'cursor', 'subl', 'zed', 'atom'].some((g) =>


add these to a const rather than including them here

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

jacob314 · 2026-03-09T23:36:05Z

-            'error',
-            '[editorUtils] external editor spawn error',
-            err,
+          const spawnErr = err as NodeJS.ErrnoException;


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

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

jacob314 · 2026-03-09T23:36:51Z

+const editorExtraArgs: Partial<Record<EditorType, string[]>> = {
+  emacsclient: ['-nw'], // Force terminal (no-window) mode
+  vscode: ['--new-window'], // Force a new window to open the file directly
+  vscodium: ['--new-window'],


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.

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

jacob314

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

jacob314 requested a shorter description to fit the TUI. This was already addressed in PR google-gemini#21090 via settingsSchema.ts. Regenerate schema from source of truth and restore the accepted-values table in configuration.md.

alberti42

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

alberti42 · 2026-03-11T05:54:36Z

+          or leave unset to use $VISUAL/$EDITOR.
+        `,
        showInDialog: false,
+        options: [


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

alberti42 · 2026-03-11T06:03:58Z

+      } else {
+        // Heuristic fallback for commands not in the registry
+        const lower = envCommand.toLowerCase();
+        const isGui = ['code', 'cursor', 'subl', 'zed', 'atom'].some((g) =>


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

alberti42 · 2026-03-11T06:09:55Z

-            'error',
-            '[editorUtils] external editor spawn error',
-            err,
+          const spawnErr = err as NodeJS.ErrnoException;


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

alberti42 · 2026-03-11T06:41:07Z

+const editorExtraArgs: Partial<Record<EditorType, string[]>> = {
+  emacsclient: ['-nw'], // Force terminal (no-window) mode
+  vscode: ['--new-window'], // Force a new window to open the file directly
+  vscodium: ['--new-window'],


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

jacob314 requested a shorter description to fit the TUI. This was already addressed in PR google-gemini#21090 via settingsSchema.ts. Regenerate schema from source of truth and restore the accepted-values table in configuration.md.

alberti42 · 2026-04-10T19:26:11Z

@cocosheng-g Thanks for following up. The code is now ready for being re-reviewed.

1. Added 'sublime' to GUI_EDITORS 2. Added sublime: 'Sublime Text' to EDITOR_DISPLAY_NAMES 3. Added sublime: { win32: ['subl'], default: ['subl'] } to editorCommands 4. Added a case 'sublime' in getDiffCommand with ['--wait', oldPath] (Sublime doesn't support --diff) And in editor.test.ts: added sublime to the hasValidEditorCommand, getDiffCommand, openDiff, and allowEditorTypeInSandbox test suites.

packages/core/src/utils/editor.ts: - Added 'emacsclient' to TERMINAL_EDITORS - Added emacsclient: 'Emacs Client' to EDITOR_DISPLAY_NAMES - Added emacsclient: { win32: ['emacsclient'], default: ['emacsclient'] } to editorCommands - Added case 'emacsclient' in getDiffCommand using emacsclient -nw --eval "(ediff ...)" packages/cli/src/ui/utils/editorUtils.ts: - Added -nw flag injection for emacsclient when opening a file (equivalent to the -i NONE treatment for vim) packages/core/src/utils/editor.test.ts: - Added emacsclient to hasValidEditorCommand, getDiffCommand, openDiff, and allowEditorTypeInSandbox test suites

Instead of crashing with an unhandled promise rejection, users now get a clear message whether their preferredEditor setting is invalid or their $VISUAL/$EDITOR command can't be found.

… documentation

jacob314 requested a shorter description to fit the TUI. This was already addressed in PR google-gemini#21090 via settingsSchema.ts. Regenerate schema from source of truth and restore the accepted-values table in configuration.md.

Change preferredEditor type to 'enum' and add options so the schema generator permanently emits the accepted values list in configuration.md and the enum array in settings.schema.json without manual edits.

…-buffer

… EditorSettingsDialog

alberti42 · 2026-04-24T10:36:51Z

Dear Jacob (@jacob314),

I wanted to check with you what you think the status of this PR is. You had reviewed it before, and I believe I took care of all your comments. Please let us know if you need more time and/or need to have a more thorough review of the code.

Thanks!
Andrea

PS I just rebased it, and luckily there were no conflicts.

alberti42 requested review from a team as code owners March 4, 2026 10:32

gemini-code-assist Bot reviewed Mar 4, 2026

View reviewed changes

Comment thread packages/core/src/utils/editor.test.ts Outdated

gemini-cli Bot added the area/core Issues related to User Interface, OS Support, Core Functionality label Mar 4, 2026

alberti42 force-pushed the extra-editors branch from 68d003f to 777ec30 Compare March 4, 2026 10:54

jacob314 reviewed Mar 4, 2026

View reviewed changes

jacob314 enabled auto-merge March 4, 2026 17:31

gemini-cli Bot added priority/p2 Important but can be addressed in a future release. help wanted We will accept PRs from all issues marked as "help wanted". Thanks for your support! labels Mar 4, 2026

auto-merge was automatically disabled March 5, 2026 08:55
Head branch was pushed to by a user without write access

This was referenced Mar 6, 2026

External editor support: unclear error messages, missing editors, incomplete documentation #21084

Closed

fix(editor): improve external editor (Ctrl-X) UX #21377

Closed

alberti42 force-pushed the extra-editors branch from 15bda94 to 722cffc Compare March 6, 2026 21:58

alberti42 requested a review from a team as a code owner March 6, 2026 23:04

jacob314 reviewed Mar 9, 2026

View reviewed changes

github-actions Bot mentioned this pull request Mar 10, 2026

📊 AI CLI Tools Digest 2026-03-10 duanyytop/agents-radar#118

Closed

alberti42 force-pushed the extra-editors branch 2 times, most recently from 19b1f71 to 1fcb713 Compare March 11, 2026 06:37

alberti42 commented Mar 11, 2026

View reviewed changes

alberti42 force-pushed the extra-editors branch from 1fcb713 to d4ec629 Compare March 11, 2026 06:47

alberti42 force-pushed the extra-editors branch from 3ab2c79 to b47ae45 Compare April 10, 2026 19:23

alberti42 and others added 23 commits April 24, 2026 12:30

fix(cli): gracefully handle unrecognized or missing editor commands

b111ef1

Instead of crashing with an unhandled promise rejection, users now get a clear message whether their preferredEditor setting is invalid or their $VISUAL/$EDITOR command can't be found.

fix(cli): address code review issues raised by gemini-code-assist

54b16bd

docs(cli): improve preferredEditor description in settings schema and…

506d788

… documentation

fix(cli): address code review issues raised by gemini-code-assist

3111928

fix(cli): address code review issues raised by @jacob314

30b1388

fix(editor): shows descriptive errors when error command fails

eaa5e1d

fix(editor): removes emitFeedback from EditorSettingsDialog render body

ed4b51c

fix(editor): add --new-window flag for VS Code-family editors

289f6e3

docs(editor): document preferredEditor accepted values and env fallback

f7ad24d

fix(editor): applies editor-specific args when using /

c413b48

fix(cli): generate preferredEditor enum from settingsSchema.ts

20387f9

Change preferredEditor type to 'enum' and add options so the schema generator permanently emits the accepted values list in configuration.md and the enum array in settings.schema.json without manual edits.

refactor: derive preferredEditor options from EDITOR_OPTIONS

abe02e4

refactor: extract HEURISTIC_GUI_COMMANDS const

2e9f8b3

fix: replace throw with emitFeedback in openFileInEditor

e962f07

fix: replace unsafe EditorType cast with isValidEditorType

ecb9f0e

feat: guard --new-window behind openEditorInNewWindow setting

a221647

docs: add comment explaining HEURISTIC_GUI_COMMANDS

9c4d506

fix: add antigravity to NEW_WINDOW_EDITORS and HEURISTIC_GUI_COMMANDS

1760479

refactor: read openEditorInNewWindow directly via useSettings in text…

14f7249

…-buffer

refactor(cli): remove unused coreEvents and cleanup type assertion in…

ec05450

… EditorSettingsDialog

alberti42 force-pushed the extra-editors branch from b47ae45 to ec05450 Compare April 24, 2026 10:31

gemini-cli Bot added the priority/p3 Backlog - a good idea but not currently a priority. label May 9, 2026

github-actions Bot mentioned this pull request May 10, 2026

📊 AI CLI 工具社区动态日报 2026-05-10 ivanweng2077/big_model_radar#20

Open

Conversation

alberti42 commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Details

Related Issues

Note for maintainers: enum constraint in the JSON schema

How to Validate

Pre-Merge Checklist

Uh oh!

gemini-code-assist Bot commented Mar 4, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alberti42 commented Mar 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jacob314 Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jacob314 left a comment

Choose a reason for hiding this comment

Uh oh!

alberti42 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alberti42 commented Apr 10, 2026

Uh oh!

alberti42 commented Apr 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

alberti42 commented Mar 4, 2026 •

edited

Loading

jacob314 Mar 9, 2026 •

edited

Loading