feat(cli): support Ctrl-Z suspension by brtkwr · Pull Request #17630 · google-gemini/gemini-cli

brtkwr · 2026-01-27T06:07:04Z

Restores Ctrl+Z functionality to suspend the CLI process.
Resolves keybinding conflicts and refines suspend behavior.

Fixes #5018

Summary

Details

Related Issues

How to Validate

Pre-Merge Checklist

gemini-code-assist · 2026-01-27T06:07:20Z

Summary of Changes

Hello @brtkwr, 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 CLI's usability by enabling the standard Ctrl+Z shortcut for process suspension. It ensures that the terminal's state is correctly preserved and restored when the application is backgrounded and subsequently brought back to the foreground, providing a more integrated and familiar experience for users accustomed to typical shell interactions.

Highlights

Ctrl+Z Suspension: Introduced functionality to suspend the CLI process using the Ctrl+Z key combination, allowing users to temporarily background the application.
Terminal State Management: Implemented robust handling of terminal state during suspension and resumption, including managing raw mode, cursor visibility, mouse events, and Kitty keyboard protocol to ensure a seamless user experience.
Keybinding Configuration: Added a new SUSPEND command to the CLI's keybinding configuration, mapping it to Ctrl+Z and updating relevant command descriptions and categories.
Testing and Documentation: Included a new dedicated test file to validate the suspend and resume behavior, and updated the keyboard shortcuts documentation to reflect the new Ctrl+Z functionality.

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 introduces support for suspending the CLI process using Ctrl+Z. While the overall implementation is robust, a high-severity code review comment has been raised regarding a type assertion in AppContainer.tsx that bypasses TypeScript's type safety, suggesting a more robust typing approach.

gemini-code-assist · 2026-01-27T06:09:02Z

packages/cli/src/ui/AppContainer.tsx

      enableMouseEvents();
      disableLineWrapping();
-      app.rerender();
+      (app as unknown as { rerender: () => void }).rerender();


The type assertion (app as unknown as { rerender: () => void }).rerender(); is used here to call the rerender method. While functional, this bypasses TypeScript's type safety. It would be more robust to ensure that the app object returned by useApp() is correctly typed to include the rerender method, or to import useApp from a version that includes it. This helps maintain type safety and code clarity.

brtkwr · 2026-01-28T08:37:33Z

Just rebased the PR and ran all the tests locally which appear to be passing.

scidomino

This will probably create a giant trap for users if they are already used to hitting ctrl+z to undo. What I suggest is that do this in stages.

First, we support ctrl+z but you have to hit it twice and after you hit it the first time we pop up a message saying something like press "ctrl-Z again to suspend, use CMD-Z to undo". Then after running with that for a couple weeks we can remove the toast and just suspend on the first ctrl+z.

scidomino · 2026-01-28T19:34:11Z

packages/cli/src/ui/AppContainer.tsx

        setCtrlDPressCount((prev) => prev + 1);
        return true;
+      } else if (keyMatchers[Command.SUSPEND](key)) {
+        if (process.platform !== 'win32') {


AppContainer is gigantic. Please move this into another file. Have Gemini do a thorough search to see if there are any files it makes sense to move this code to before deciding to create a new one.

fixed - moved suspend behavior into a dedicated useSuspend hook to keep AppContainer smaller.

scidomino · 2026-01-28T19:35:20Z

packages/cli/src/ui/contexts/KeypressContext.tsx

 }

-const MAC_ALT_KEY_CHARACTER_MAP: Record<string, string> = {
+const MAC_ALT_KEY_CHARACTER_MAP: Record<


I've broken this part out into a separate PR. Let's merge mine first and then you won't even have to touch this file #17800

Thanks for the update, scidomino! That sounds like a good plan. If your PR is merged first, then @brtkwr can rebase this branch to remove these changes from packages/cli/src/ui/contexts/KeypressContext.tsx.

Amazing thanks for doing that!

updated - rebased and synced with upstream so this PR no longer carries the extra keypress-context changes from before #17800.

scidomino · 2026-01-28T20:45:33Z

Actually, I will make the toast message part of my PR so hold off till that is merged.

scidomino · 2026-01-29T00:01:04Z

I merged my changes. Sorry if it's a pain but it should make your PR smaller ultimately. You just need to impl the "press ctrl+z twice" logic and the actual suspension. ping my handle in a comment when you are ready for review.

brtkwr · 2026-02-02T22:10:05Z

I merged my changes. Sorry if it's a pain but it should make your PR smaller ultimately. You just need to impl the "press ctrl+z twice" logic and the actual suspension. ping my handle in a comment when you are ready for review.

I've addressed the changes that you requested.

brtkwr · 2026-02-02T22:10:50Z

Unfortunately, it has made the PR slightly larger, not smaller 🙃

scidomino

Sorry for the delay. I left some comments.

scidomino · 2026-02-09T23:19:25Z

packages/cli/src/ui/hooks/useSuspend.ts

+    }
+    if (ctrlZPressCount > 1) {
+      setCtrlZPressCount(0);
+      if (process.platform !== 'win32') {


Why do we only clean up if we're not in windows?

good point - i added an explicit windows guard with a warning so cleanup/suspend logic only runs on supported platforms.

scidomino · 2026-02-09T23:20:21Z

packages/cli/src/ui/hooks/useSuspend.ts

+    if (ctrlZPressCount > 1) {
+      setCtrlZPressCount(0);
+      if (process.platform !== 'win32') {
+        // Cleanup before suspend


we have a private cleanupOnExit method in TerminalCapabilityManager, make it an exported function and call it here. If you need to add the "Show cursor" command to it, do it.

fixed - exported terminal cleanup (cleanupTerminalOnExit) from TerminalCapabilityManager and reused it from suspend handling.

scidomino · 2026-02-09T23:21:29Z

packages/cli/src/ui/hooks/useSuspend.ts

+          }
+          setRawMode(true);
+
+          terminalCapabilityManager.enableKittyProtocol();


use terminalCapabilityManager.enableSupportedModes(). We don't want to enable this if it's not supported.

fixed - resume path now calls terminalCapabilityManager.enableSupportedModes().

scidomino · 2026-02-09T23:22:13Z

packages/cli/src/ui/utils/terminalCapabilityManager.ts

    }
  }

+  disableKittyProtocol() {


Remove these unless you have a good reason not to use enableSupportedModes

done - removed the dedicated kitty enable/disable helpers and switched to enableSupportedModes on resume.

scidomino · 2026-02-09T23:23:25Z

packages/cli/src/ui/AppContainer.suspend.test.tsx

@@ -0,0 +1,460 @@
+/**


There is nothing GCLI loves more than introducing new test files for classes that already have test files :D

Can you move this test into AppContainer.test.tsx? Only keep it separate if it leads to less overall code

fixed - moved suspend coverage into AppContainer.test.tsx and removed the separate AppContainer.suspend.test.tsx file.

scidomino · 2026-02-09T23:25:32Z

packages/core/src/code_assist/setup.test.ts


  beforeEach(() => {
    vi.resetAllMocks();
+    vi.stubEnv('GOOGLE_CLOUD_PROJECT_ID', '');


Are these changes necessary? I can run the tests just fine without them.

removed - dropped those setup-test env stubs to keep this PR scoped to suspend behavior.

scidomino · 2026-02-09T23:26:33Z

When you've addressed these ping me by name with the @ symbol so I get to it right away.

brtkwr · 2026-02-10T08:15:37Z

@scidomino i addressed all open review comments and pushed updates to this PR. ready for another pass when you have a minute.

scidomino · 2026-02-10T17:34:15Z

I see there are merge conflicts. I will attempt to resolve them for you.

scidomino · 2026-02-10T18:02:56Z

Looks like you beat me to it.

brtkwr · 2026-02-10T18:07:05Z

Looks like you beat me to it.

👯‍♂️

scidomino

When I suspend it, it doesn't clear the screen, and it leaves me in kitty mode (if it was enabled). And when I unsuspend it, it doesn't repaint the whole screen

after suspending:

After unsuspending:

this is happening on both ghostty and mac terminal.

scidomino

see above

scidomino · 2026-02-10T18:48:31Z

Heads up: #18670 is about to be merged which duplicates some of the work you did here. I think it may have also solve some of the issues here because it has protections against registering the same listener more than once.

brtkwr · 2026-02-11T16:58:12Z

@scidomino addressed the suspend/resume issues from your latest review in 822bfe1:

exit alternate screen + re-enable line wrapping before SIGTSTP, and clear screen
do synchronous terminal mode cleanup before suspend so kitty/modifyOtherKeys are disabled
on SIGCONT, re-enter alternate screen, restore supported modes, and force a full repaint
added focused coverage in useSuspend.test.ts for suspend/resume + windows guard

please take another look when you get a chance.

brtkwr · 2026-02-11T17:18:02Z

Collaborator

When I suspend it, it doesn't clear the screen, and it leaves me in kitty mode (if it was enabled). And when I unsuspend it, it doesn't repaint the whole screen

after suspending:

After unsuspending:

this is happening on both ghostty and mac terminal.

I see the same behaviour in other terminal based coding agents. why does it need to clear the screen on suspend?

scidomino · 2026-02-11T19:14:22Z

Ok. Approved. I will attempt to resolve the branch conflicts

scidomino · 2026-02-11T19:33:49Z

I don't seem to have permission to push to your fork so you will have to resolve the merge conflicts. Sorry.

brtkwr · 2026-02-11T22:22:58Z

@scidomino rebased

scidomino · 2026-02-12T17:12:53Z

Uhg. More conflicts. Ok. I am going to clone this and see if I can merge it myself. Sorry for all these delays.

scidomino · 2026-02-12T17:42:29Z

duplicated to #18931

scidomino · 2026-02-12T18:51:56Z

merged as part of #18931

brtkwr requested review from a team as code owners January 27, 2026 06:07

gemini-code-assist bot reviewed Jan 27, 2026

View reviewed changes

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 Jan 27, 2026

brtkwr force-pushed the main branch 2 times, most recently from 1778767 to 254426d Compare January 27, 2026 10:06

bdmorgan added the area/core Issues related to User Interface, OS Support, Core Functionality label Jan 27, 2026

brtkwr force-pushed the main branch from 254426d to 756cf81 Compare January 28, 2026 08:36

gemini-cli bot added the 🔒 maintainer only ⛔ Do not contribute. Internal roadmap item. label Jan 28, 2026

scidomino reviewed Jan 28, 2026

View reviewed changes

brtkwr force-pushed the main branch 2 times, most recently from fedb3ae to f0b1e13 Compare February 2, 2026 22:06

brtkwr force-pushed the main branch 11 times, most recently from 18c4cf0 to 71af62c Compare February 2, 2026 23:00

brtkwr requested a review from scidomino February 7, 2026 08:42

scidomino reviewed Feb 9, 2026

View reviewed changes

brtkwr force-pushed the main branch 3 times, most recently from 53e738d to be3e79e Compare February 10, 2026 08:35

scidomino approved these changes Feb 10, 2026

View reviewed changes

brtkwr force-pushed the main branch from be3e79e to d7f79f7 Compare February 10, 2026 18:00

scidomino reviewed Feb 10, 2026

View reviewed changes

scidomino requested changes Feb 10, 2026

View reviewed changes

brtkwr force-pushed the main branch from 822bfe1 to a336890 Compare February 11, 2026 17:08

scidomino approved these changes Feb 11, 2026

View reviewed changes

brtkwr force-pushed the main branch from a336890 to df29ef6 Compare February 11, 2026 22:05

feat(cli): support Ctrl-Z suspension

4657ce7

brtkwr force-pushed the main branch from df29ef6 to 4657ce7 Compare February 12, 2026 09:03

scidomino mentioned this pull request Feb 12, 2026

feat(cli): support Ctrl-Z suspension #18931

Merged

18 tasks

scidomino closed this Feb 12, 2026

Conversation

brtkwr commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Details

Related Issues

How to Validate

Pre-Merge Checklist

Uh oh!

gemini-code-assist bot commented Jan 27, 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!

gemini-code-assist bot Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brtkwr commented Jan 28, 2026

Uh oh!

scidomino 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!

gemini-code-assist bot Jan 28, 2026

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!

scidomino commented Jan 28, 2026

Uh oh!

scidomino commented Jan 29, 2026

Uh oh!

brtkwr commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

brtkwr commented Feb 2, 2026

Uh oh!

scidomino 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!

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!

scidomino commented Feb 9, 2026

Uh oh!

brtkwr commented Feb 10, 2026

brtkwr commented Jan 27, 2026 •

edited

Loading

brtkwr commented Feb 2, 2026 •

edited

Loading