From d2664b570446d65e8860a0ceb44bbb9f15255fbb Mon Sep 17 00:00:00 2001
From: Leah Amelia Chen <hi@pluie.me>
Date: Tue, 18 Nov 2025 22:07:15 +0800
Subject: [PATCH] docs: add Synchronized Output help page

---
 docs/help/index.mdx               |  1 +
 docs/help/synchronized-output.mdx | 57 +++++++++++++++++++++++++++++++
 docs/nav.json                     |  5 +++
 3 files changed, 63 insertions(+)
 create mode 100644 docs/help/synchronized-output.mdx

diff --git a/docs/help/index.mdx b/docs/help/index.mdx
index dcd56062..1dfb21ba 100644
--- a/docs/help/index.mdx
+++ b/docs/help/index.mdx
@@ -19,6 +19,7 @@ we try to document as many common issues and solutions as possible.
 | Ghostty has slow startup or high memory usage on Linux.                    | [GTK Single Instance](/docs/help/gtk-single-instance)       |
 | "Unable to acquire OpenGL context" error on Linux                          | [GTK OpenGL Context](/docs/help/gtk-opengl-context)         |
 | macOS defaults to login shells                                             | [macOS Login Shells](/docs/help/macos-login-shells)         |
+| CLI tools like Claude Code, Docker, etc. repeatedly flash or flicker       | [Synchronized Output](/docs/help/synchronized-output)       |
 
 ## Seeking Help
 
diff --git a/docs/help/synchronized-output.mdx b/docs/help/synchronized-output.mdx
new file mode 100644
index 00000000..0de61714
--- /dev/null
+++ b/docs/help/synchronized-output.mdx
@@ -0,0 +1,57 @@
+---
+title: Synchronized Output
+description: |-
+  Command-line programs that update large swaths of the visible screen might
+  show screen tearing on fast terminals like Ghostty, when synchronized
+  output is not enabled.
+---
+
+On some systems, command-line programs that frequently update large swaths of
+the visible screen might repeatedly flicker or exhibit severe screen tearing
+when using Ghostty, which does not occur with other terminal emulators.
+**This is usually not a bug with Ghostty, but rather a bug with the programs
+themselves.**
+
+Often the reason behind this is that Ghostty is rendering **too quickly**,
+and the programs that are redrawing the screen are not updating the cells
+on the screen fast enough to catch up with the renderer — hence, tearing.
+
+There's not much Ghostty can do here without compromising performance, and
+therefore we **highly encourage** users of affected programs to file issues
+to upstream developers with a link to the ["For developers"](#for-developers)
+section of this page, so that they know how to fix the underlying problem.
+
+Programs known to be affected by this include:
+
+- Claude Code ([#8176], [#8285])
+- Docker CLI ([#5493], [#5657], [#8162])
+- Ollama ([#4048])
+- Grok ([#9618])
+
+[#4048]: https://github.com/ghostty-org/ghostty/discussions/4048
+[#5493]: https://github.com/ghostty-org/ghostty/discussions/5493
+[#5657]: https://github.com/ghostty-org/ghostty/discussions/5657
+[#8162]: https://github.com/ghostty-org/ghostty/discussions/8162
+[#8176]: https://github.com/ghostty-org/ghostty/discussions/8176
+[#8285]: https://github.com/ghostty-org/ghostty/discussions/8285
+[#9618]: https://github.com/ghostty-org/ghostty/discussions/9618
+
+## For developers
+
+If you're a developer of a CLI or TUI-based app that has this issue, you
+need to implement the [Synchronized Output] protocol which signals Ghostty
+(and other modern, performant terminal emulators) when the screen has been
+fully updated, and it is safe to render the next frame.
+
+However, as a best practice we also recommend **only updating the cells that
+absolutely need to be updated**, and avoid erasing whole rows or the entirety
+of the active screen before updating new cells. Instead, you can reset the
+cursor to the part to be updated by using [Cursor Position (CUP)], update the
+cells, and erase the rest of the line using [Erase in Line (EL)]. This not
+only ameliorates the screen tearing on terminals that may not support the
+Synchronized Output protocol, but can also greatly increase performance by
+reducing needless updates and the amount of data sent to the terminal.
+
+[Synchronized Output]: https://github.com/contour-terminal/vt-extensions/blob/1a9fde53d80c4a60b1be44c5a4492d86ec9f9cce/synchronized-output.md
+[Cursor Position (CUP)]: /docs/vt/csi/cup
+[Erase in Line (EL)]: /docs/vt/csi/el
diff --git a/docs/nav.json b/docs/nav.json
index 2eb134a1..926ea96b 100644
--- a/docs/nav.json
+++ b/docs/nav.json
@@ -471,6 +471,11 @@
           "type": "link",
           "path": "/macos-login-shells",
           "title": "macOS Login Shells"
+        },
+        {
+          "type": "link",
+          "path": "/synchronized-output",
+          "title": "Synchronized Output"
         }
       ]
     }