bug: Amazon Q CLI Significantly degrades ZSH performance

[sammcj]

Checks

• I have searched github.com/aws/amazon-q-developer-cli/issues and there are no duplicates of my issue
• I have run q doctor in the affected terminal session
• I have run q restart and replicated the issue again

Operating system

macOS 15.3.2

Expected behaviour

Amazon Q CLI not to slow down terminal initialisation or impact runtime performance.

Actual behaviour

Q CLI Analysis

The Amazon Q CLI significantly slows down the loading of new terminal sessions on macOS when integrated with zsh. Profiling and analysis reveal that the primary causes are double initialisation and a slow pre-command hook.

Environment:

• Shell: zsh
• Operating System: macOS 15.3.2
• Amazon Q CLI Installation Method: The latest official Amazon Q installer

Problem Summary:

After Amazon Q CLI makes changes to add itself into both ~/.zshrc and ~/.zprofile, the startup time of new terminal sessions increased dramatically. Furthermore, the shell felt generally sluggish, with a noticeable delay before each prompt appeared.

Detailed Findings:

1. Double Initialisation: The Amazon Q CLI initialisation script (q init zsh pre) is executed twice during shell startup: once from ~/.zprofile and again from ~/.zshrc. The scripts generated for pre are identical for both files. This leads to redundant operations and significantly increases the initial load time.

   • Evidence: zsh profiling (zprof) and tracing (set -x) clearly show the repeated execution of the initialisation logic.

2. Slow q _ pre-cmd: The q _ pre-cmd command, which is executed before every prompt via a precmd hook, introduces a significant delay. This delay is the primary cause of the perceived sluggishness of the shell after the initial load.

   • Evidence: Timing measurements using the time command show that q _ pre-cmd takes approximately 11ms to complete:

     time $HOME/.local/bin/q _ pre-cmd --alias "$(\alias)"

     Output:

     $HOME/.local/bin/q _ pre-cmd --alias "$(\alias)"  0.00s user 0.00s system 85% cpu 0.011 total

     This 11ms delay is added to every command execution, making the shell feel unresponsive.

3. q _ should-figterm-launch Contributes to Startup Delay: The q _ should-figterm-launch command, executed during initialisation, also contributes to the initial startup delay.

   • Evidence: Timing measurements:

     time $HOME/.local/bin/q _ should-figterm-launch

     Output:

     ❌ zsh (qterm) |  (46360) <- ✅ zsh (46368)
     🟡 Falling back to old mechanism since on macOS
     $HOME/.local/bin/q _ should-figterm-launch  0.01s user 0.01s system 93% cpu 0.013 total

     This adds 13ms to the startup time.

4. qterm is not being launched: The output from q _ should-figterm-launch indicates it is falling back to an "old mechanism".

Steps to Reproduce:

1. Profile zsh without Q
2. Install the Amazon Q CLI.
3. Integrate the CLI into zsh by adding the recommended lines to ~/.zshrc and ~/.zprofile.
4. Profile zsh with Q
5. Open a new terminal session and observe the slow startup time.
6. Type commands and observe the delay before each prompt.

---

Proposed Solutions/Workarounds

1. Prevent Double Initialisation: Modified .zprofile to include a guard variable, preventing the initialisation block from running in .zshrc:

   # In ~/.zprofile:
   if [[ -z "$AMAZON_Q_INITIALIZED" ]]; then
       if [[ -f '$HOME/Library/Application Support/amazon-q/shell/zprofile.pre.zsh' ]]; then
         source '$HOME/Library/Application Support/amazon-q/shell/zprofile.pre.zsh'
       fi
   
       if [[ -f '$HOME/Library/Application Support/amazon-q/shell/zprofile.post.zsh' ]]; then
         source '$HOME/Library/Application Support/amazon-q/shell/zprofile.post.zsh'
       fi
       export AMAZON_Q_INITIALIZED=1
   fi

   Removed the entire Amazon Q block from ~/.zshrc. This significantly reduced the initial startup time.

2. Disable q _ pre-cmd: Commented out the call to q _ pre-cmd within the fig_precmd function and also the call outside the function definition, in $HOME/Library/Application Support/amazon-q/shell/zprofile.post.zsh. This dramatically improved the responsiveness of the shell after startup, eliminating the per-prompt delay.

     fig_precmd() {
       # ... (other code) ...
   
       # if command -v q >/dev/null 2>&1; then
       #   (command q _ pre-cmd --alias "$(\alias)" > /dev/null 2>&1 &) >/dev/null 2>&1
       # fi
     }
   
     fig_reset_hooks
     if [[ -n "${PROCESS_LAUNCHED_BY_Q:-}" ]]; then
       fig_osc DoneSourcing
     fi
   
     # fi # <- this was already commented out
   
     #(command q _ pre-cmd --alias "$(\alias)" > /dev/null 2>&1 &) >/dev/null 2>&1 # comment this out.

---

Quantitative Performance Impact

The following table summarizes the relevant key differences in execution times of zsh functions during startup, as measured by zprof, with and without Amazon Q CLI integration.

Note: These timings only reflect the initial shell startup, and do not include the ongoing overhead of the precmd hook (which adds ~11ms to every command, as detailed separately).

Function	Without Q (ms)	With Q (ms)	Difference (ms)	Notes
Amazon Q Initialisation	0	~1860	+~1860	This is a significant difference. This represents the time spent in the Amazon Q initialisation blocks (running q init and evaling the result), derived from earlier set -x tracing.
TOTAL (Approximate)	~125	~1940	+~1815	Total is estimated based on zprof times and tracing, showing a difference close to the 2 seconds noted in the earlier set -x tracing. This highlights the massive impact of the Amazon Q initialisation.

Key Observations

• Overall Startup Increase: The total startup time increases by approximately 1.8 seconds with the Amazon Q CLI enabled, before considering the precmd hook overhead (~11ms per command).
• Amazon Q Initialisation Dominates: The vast majority of the increased startup time is directly attributable to the Amazon Q initialisation process. The other functions are comparatively minor.

This table clearly demonstrates the significant negative impact of the Amazon Q CLI on shell startup time, providing quantitative evidence to support the qualitative observation of a slower terminal. The dominant factor is the Amazon Q initialisation itself.

---

Methodology

I performed analysis of the scripts that Amazon Q CLI injects into the shell, and used zsh's profiling (zprof) and tracing (set -x) to identify the key performance bottlenecks.

The scripts are generated from the following four commands that I exported to files for analysis:

${HOME}/.local/bin/q init zsh pre --rcfile zprofile > q_init_pre_zprofile.zsh
${HOME}/.local/bin/q init zsh pre --rcfile zshrc > q_init_pre_zshrc.zsh
${HOME}/.local/bin/q init zsh post --rcfile zprofile > q_init_post_zprofile.zsh
${HOME}/.local/bin/q init zsh post --rcfile zshrc > q_init_post_zshrc.zsh

Detailed Q Scripts Analysis

• q_init_pre_zprofile.zsh and q_init_pre_zshrc.zsh (Identical): These two files are identical, which immediately confirms the double-initialisation problem. This is the primary cause of the initial slowdown. The script does the following:
  • Sets up PATH: Adds ~/.local/bin to the PATH if it exists and isn't already there. This is generally good practice, but not a major performance concern.
  • Q_NEW_SESSION Handling: Unsets some QTERM related variables if Q_NEW_SESSION is set. This suggests some session management, but it's unlikely to be a significant slowdown on its own.
  • Q_SET_PARENT_CHECK Handling: Deals with parent process IDs. Again, not likely to be a major performance bottleneck.
  • SHOULD_QTERM_LAUNCH Check: This is a crucial part. It calls q _ should-figterm-launch and stores the exit code. This is a likely source of slowdown, as it's an external call to the q command. We'll need to investigate q _ should-figterm-launch.
  • The qterm Launch Logic: The large if block checks several conditions before potentially launching qterm:
    • [[ -t 1 ]]: Checks if standard output is connected to a terminal (i.e., it's an interactive shell).
    • [[ -z "${PROCESS_LAUNCHED_BY_Q:-}" ]]: Checks if the process was launched by Q. This prevents nested invocations.
    • command -v qterm 1>/dev/null 2>&1: Checks if the qterm command exists. This is a repeated check (it also happens inside q _ should-figterm-launch, very likely).
    • The complex SHOULD_QTERM_LAUNCH and Q_TERM, Q_TERM_TMUX, TMUX checks.
    • If all conditions are met, it determines the Q_TERM_NAME and Q_TERM_PATH, and then uses exec -a "${Q_TERM_NAME}" "${Q_TERM_PATH}" to replace the current shell process with qterm. The -a option sets the name that qterm sees as its own process name (argv[0]).
  • Reading Initial Text: The while read -rt 0 loop attempts to read initial text from standard input. This is likely related to how qterm interacts with the terminal, but it's only executed if qterm is launched. The timeout (-t 0) means it won't block, but it's still a bit of extra work.
• q_init_post_zprofile.zsh and q_init_post_zshrc.zsh (Identical): These files are also identical, and they are responsible for setting up the preexec and precmd hooks.
  • fig_osc Function: Defines a function to send OSC (Operating System Command) escape sequences to the terminal. This is used for communication between Q and the terminal emulator. The function itself is fast.
  • fig_preexec and fig_precmd: These are the hook functions. They are called before every command (preexec) and before every prompt (precmd).
    • Prompt Restoration (in fig_preexec): Restores the user's original prompt settings. This is important because Q modifies the prompt.
    • OSC Messages (in both): Sends a series of fig_osc calls to communicate with qterm. This includes sending the current directory, shell, PID, exit code, etc. This is the ongoing overhead that will affect every command.
    • Prompt Modification (in fig_precmd): This is the core of how Q integrates. It saves the user's prompt settings (PS1, PS2, etc.) and then wraps them with START_PROMPT and END_PROMPT markers. These markers are OSC escape sequences (\033]697;...). This allows qterm to identify the prompt and inject its own output.
    • q _ pre-cmd Call: At the end of fig_precmd, it calls (command q _ pre-cmd --alias "$(\alias)" > /dev/null 2>&1 &) >/dev/null 2>&1. This runs q _ pre-cmd in the background before every prompt. This is another likely source of ongoing slowdown, and we need to investigate what q _ pre-cmd does. The --alias "$(\alias)" part is passing a list of defined aliases to the command.

Key Findings and Confirmed Problems

1. Double Initialisation (Confirmed): The pre scripts are identical and run twice, causing unnecessary work and likely doubling the startup time.
2. q _ should-figterm-launch (Likely Slowdown): This external call is made in the pre script and is a prime suspect.
3. qterm Launch (Potential Slowdown): The conditions for launching qterm are complex, and qterm itself is an unknown quantity.
4. preexec/precmd Hooks (Ongoing Overhead): These hooks add overhead to every command and prompt, making the terminal feel sluggish. The fig_osc calls and the q _ pre-cmd call are the main contributors to this overhead.
5. q _ pre-cmd called before every prompt: (Likely Slowdown).

---

Requests for Amazon Q CLI Developers

1. Address Double Initialisation: Modify the installation/integration process to prevent the initialisation script from running multiple times. A simple check for an environment variable (like the AMAZON_Q_INITIALIZED example above) would suffice.
2. Optimise or Eliminate q _ pre-cmd: The 11ms delay introduced by q _ pre-cmd is unacceptable for a pre-command hook. This command needs to be significantly optimised, or its functionality should be achieved through a different mechanism that doesn't impact prompt responsiveness. Ideally, provide an option to disable this hook if the user doesn't require its functionality.
3. Investigate q _ should-figterm-launch: While less critical than q _ pre-cmd, the 13ms delay of q _ should-figterm-launch still contributes to startup time.
4. Consider a Shell Script for q (Optional): If feasible, consider providing at least parts of the q functionality as a shell script (rather than a compiled binary). This would allow users to more easily debug performance issues and potentially contribute improvements.
5. Provide Clear Documentation: The documentation should clearly state which parts are run at start-up and which are run before every prompt.

The current implementation significantly degrades the user experience, making the shell feel sluggish and unresponsive.

The workarounds described above improve the situation, but they require manual intervention and may disable some Amazon Q functionality.

A proper fix within the Amazon Q CLI is needed and indicates the need for more robust testing and optimisation of the CLI's shell integration.

Steps to reproduce

No response

Environment

q diagnostic

[q-details]
version = "1.7.1"
hash = "7d766a2d0580db62fae5a4bc2e6eb63946d4d08e"
date = "2025-03-14T22:08:03.470338Z (3d ago)"
variant = "full"

[system-info]
os = "macOS 15.3.2 (24D81)"
chip = "Apple M2 Max"
total-cores = 12
memory = "96.00 GB"

[environment]
cwd = "/Users/USER/Downloads/q-cli-slow"
cli-path = "/Users/USER/Downloads/q-cli-slow"
os = "Mac"
shell-path = "/opt/homebrew/Cellar/zsh/5.9/bin/zsh"
shell-version = "5.9"
terminal = "iTerm 2"
install-method = "unknown"

[env-vars]
QTERM_SESSION_ID = "afa917ee9dcf47bda9d32585f8425880"
Q_SET_PARENT_CHECK = "1"
Q_TERM = "1.7.1"
SHELL = "/opt/homebrew/bin/zsh"
TERM = "xterm-256color"
__CFBundleIdentifier = "com.googlecode.iterm2"

[jsamuel1]

Thank you Sam for the detailed analysis.

[sammcj]

Hello, did this ever go anywhere? I put quite a bit of effort into debugging it for you.

[brandonskiser]

@sammcj thank you so much for the detailed analysis! It's incredibly helpful for sure, and will be useful in triaging areas to focus on.

Yes, we're trying to address this issue. I think one problem is that the qterm and autocomplete feature will inherently have some amount of overhead such that hyper-optimizing each portion (launch detection, hooks, etc.) will provide only a marginal benefit. If you check the implementation of these, I doubt you'll find anything that could drastically negate the cost of spawning new processes, querying the process hierarchy, etc. We're already using an optimized rust client, but the syscalls we need to make are just expensive much of the time. Undoubtedly there's improvements to be made (I believe telemetry is a potential culprit here, just need to investigate further), but we just need some more dedicated time to fleshing out the profiling aspect of our application.

The best move forward we can do is update the installation + distribution to support only providing the q binary (and thus, the most requested feature by far being q chat) without being coupled to autocomplete and qterm, as this is something that needs to be done regardless. We will likely prioritize this decoupling and then follow up on optimizing our very poor shell startup time using your suggestions.

[sammcj]

Thanks for the update Brandon,

I like the idea of the install (by default) only providing the q binary, with an option to add the env setup if the user wants it.

One other band-aid in the short term might be have the environmentals loaded into the terminal session when those features are used for the first time in that session, would mean a delay for the tool to respond the first time, but would prevent the slowdowns on every terminal spawn.

[sammcj]

Any update on this?

It looks like Qs MCP tool configuration fails unless you have the aforementioned slowdown scripts in your shell profile:

✗ github has failed to load:
- Operation timed out: recv for initialize
- run with Q_LOG_LEVEL=trace and see $TMPDIR/qlog for detail
✗ brave_search has failed to load:
- Operation timed out: recv for initialize
- run with Q_LOG_LEVEL=trace and see $TMPDIR/qlog for detail
✗ fetch has failed to load:
- Operation timed out: recv for initialize
- run with Q_LOG_LEVEL=trace and see $TMPDIR/qlog for detail
✗ context_7_mcp has failed to load:
- Operation timed out: recv for initialize
- run with Q_LOG_LEVEL=trace and see $TMPDIR/qlog for detail
✗ firecrawl has failed to load:
- Operation timed out: recv for initialize
- run with Q_LOG_LEVEL=trace and see $TMPDIR/qlog for detail
✗ 1 of 6 mcp servers initialized

cat $TMPDIR/qlog/fig_desktop.log
2025-05-05T11:28:07.537341Z ERROR fig_desktop::install: 381: Failed installing shell integration bash pre post into .bashrc err=Integration not installed: /Users/samm/.bashrc does not source pre integration
2025-05-05T11:28:07.538085Z ERROR fig_desktop::install: 381: Failed installing shell integration bash pre post into .profile err=File does not exist: /Users/samm/.profile
2025-05-05T11:28:07.583566Z ERROR fig_desktop::install: 381: Failed installing shell integration zsh pre post into .zshrc err=Integration not installed: /Users/samm/.zshrc does not source pre integration
2025-05-05T11:28:07.584090Z ERROR fig_desktop::install: 381: Failed installing shell integration zsh pre post into .zprofile err=Integration not installed: /Users/samm/.zprofile does not source pre integration
2025-05-05T11:28:07.957298Z ERROR fig_desktop::install: 122: No update found
2025-05-05T11:28:09.294959Z ERROR fig_desktop::install: 158: Failed installing vscode integration for variant Cursor Nightly err=IO Error: No such file or directory (os error 2)
2025-05-05T11:28:09.751779Z ERROR fig_desktop::install: 158: Failed installing vscode integration for variant Trae err=IO Error: No such file or directory (os error 2)
2025-05-05T11:28:09.968166Z ERROR fig_desktop::file_watcher: 74: failed to watch midway dir err=No path was found. about ["/Users/samm/.midway"]

[sammcj]

Any update on this @aws? Been quite a while and it's still slows down users terminal sessions to the point where they uninstall it.

[sammcj]

How's this one going @aws?

[brandonskiser]

Hey @sammcj we're in the middle of creating a standalone binary for q chat that will be distributed outside of the context of autocomplete.

[Vlaaaaaaad]

@brandonskiser any ETA for that? Any issues or PRs tracking that?

[sammcj]

Hello, any updates on this? Is Amazon Q CLI still a priority for AWS? At present we cannot recommend it due to the terrible performance impacts.

[asingh332dhl]

Yes, its very slow now days.

[Yuiham]

Hey @sammcj we're in the middle of creating a standalone binary for q chat that will be distributed outside of the context of autocomplete.嘿 @sammcj，我们正在创建一个独立的二进制文件，用于 q chat，将在自动完成的上下文之外分发。

Hello @brandonskiser, any updates on the standalone q chat binary? Is there an ETA or another tracking PR we can follow? The standalone q chat binary will be super helpful for mac users.

[pedroyan]

I'm about to uninstall it. It is quie annoying how much it is hanging my environment lately

[dna-oliv]

These random freezes and slowdowns are really ANNOYING. If it was only related to q chat, that would be okay, but it makes any command slow and hang at random.