Troubleshooting

import { Aside } from ‘@astrojs/starlight/components’;

Installation Issues

”The Terminal” is damaged and can’t be opened

This is a macOS Gatekeeper message. The Terminal is Apple Notarized, so this shouldn’t happen, but if it does:

1. Right-click the app in Applications
2. Select Open from the context menu
3. Click Open in the dialog

Alternatively, run:

xattr -cr /Applications/The\ Terminal.app

App doesn’t launch

Check Console.app for crash logs:

open -g /Applications/Utilities/Console.app

Look for entries from “The Terminal” in the crash reporter.

Terminal Issues

Shell not loading properly

The Terminal uses your login shell by default. If your shell isn’t loading:

1. Check your default shell: echo $SHELL
2. Verify the shell path exists: which zsh or which bash
3. Check Settings > Terminal > Default Shell

Colors look wrong

If ANSI colors don’t match your expectations:

1. Verify your TERM environment variable: echo $TERM
2. Try changing the theme in Settings > Appearance
3. Check if your .zshrc/.bashrc forces a specific TERM value

Slow terminal performance

If the terminal feels sluggish:

1. Reduce scrollback buffer: Settings > Terminal > Scrollback Lines (try 5000)
2. Check for processes producing excessive output (top or htop)
3. Close unused terminal panels

Browser Issues

Browser panel shows blank page

1. Check the URL bar — make sure the URL is correct
2. Try navigating to a known-working URL like https://example.com
3. If local dev server: verify the server is running and the port is correct

DevTools API not connecting

If Gee-Code can’t connect to the browser panel:

1. Check if the config file exists: cat ~/.the-terminal/devtools.json
2. Verify the port is accessible: curl http://localhost:9876
3. Restart The Terminal — the DevTools server starts on launch

The DevTools API only starts when a browser panel is open. If you don't have a browser panel in your workspace, the API won't be available.

Web app not updating after code changes

If hot reload isn’t reflected in the browser panel:

1. Click the reload button in the browser panel
2. Check the dev server terminal for errors
3. Hard refresh: hold Shift and click reload

File Navigator Issues

Files not showing

1. Check if dotfiles are hidden: Settings > File Navigator > Show Dotfiles
2. Verify the directory path is correct
3. Check file permissions

Git status not updating

The file navigator polls for git status changes. If colors seem stale:

1. Wait a few seconds for the next poll
2. Click another directory and back to force a refresh
3. Check that the directory is inside a git repository

Performance Issues

High memory usage

If The Terminal is using more than expected memory:

1. Close unused panels (especially multiple browser panels)
2. Reduce terminal scrollback buffer
3. Close unused Spaces
4. Restart The Terminal to clear any accumulated state

High CPU usage

1. Check for runaway processes in terminal panels
2. Disable background git fetch if not needed
3. Close the Observability panel if monitoring is intensive

Updating

Auto-update not working

1. Check Settings > Workspace > Auto-Update is enabled
2. Verify network connectivity
3. Manually download the latest DMG from the website

Getting Help

If you’re stuck:

1. Check the Gee-Code community for known issues
2. Include your Terminal version, macOS version, and steps to reproduce

Next Steps

• System Requirements — verify your setup
• Settings — adjust configuration