diff --git a/README.md b/README.md
index 5a8993d8..0fb7c14b 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,15 @@ $ npm run pack
 
 After that, you'll see the binary in the `./dist` folder!
 
+### pty.js issues
+
+If after building during development you get an alert dialog related to `pty.js` issues,
+make sure its build process is working correctly by running `npm rebuild` manually inside 
+the `app` directory.
+
+If you're on macOS, this typically is related to Xcode issues (like not having agreed
+to the Terms of Service by running `sudo xcodebuild` after a fresh Xcode installation).
+
 ## Related Repositories
 
 - [Art](https://github.com/zeit/art/tree/master/hyper)