diff --git a/layers/+tools/shell/packages.el b/layers/+tools/shell/packages.el
index 983d30a75..26612e274 100644
--- a/layers/+tools/shell/packages.el
+++ b/layers/+tools/shell/packages.el
@@ -83,6 +83,12 @@
       (add-hook 'eshell-mode-hook 'spacemacs/disable-hl-line-mode))
     :config
     (progn
+
+      ;; Work around bug in eshell's preoutput-filter code.
+      ;; Eshell doesn't call preoutput-filter functions in the context of the eshell
+      ;; buffer. This breaks the xterm color filtering when the eshell buffer is updated
+      ;; when it's not currently focused.
+      ;; To remove if/when fixed upstream.
       (define-advice eshell-output-filter (:around (fn process string) with-buffer)
         (let ((proc-buf (if process (process-buffer process)
                           (current-buffer))))