- 🔴 Account hacked or locked out? — Start here.
- Lost your 2FA device? — Find other ways to sign in.
- Suspicious account activity? — Check recent activity and devices.
- Prevent account lockout — Secure your recovery options ahead of time.
- Browse Gmail solutions — Compare official help and open-source tools.
- Use Gmail Doctor — Check Gmail settings on your Mac.
- Suggest a solution or feature — Help improve this project.
Gmail problems can be stressful, and useful answers are scattered across Google's help pages and open-source projects. We collected a problem-based list of existing solutions. We also built Gmail Doctor to help people review Gmail settings when they can still sign in.
You can use the guides without installing anything.
Can't sign in, or think someone took over your account?
- Go to Google Account Recovery.
- Use a device and location you've signed in from before. Follow Google's instructions.
- If you still have another signed-in device or backup sign-in method, try it.
Gmail Doctor cannot unlock accounts, bypass 2FA, or guarantee recovery. Avoid anyone asking for your password or verification codes to “recover” your account.
If your phone or verification device is lost, select “Try another way” during Google sign-in. Google may accept an existing backup code, another signed-in phone, a registered security key or a passkey on another device.
If nothing works, use Google Account Recovery. A recovery attempt can take time and might not succeed.
Official Google guides: Account recovery · Compromised account · 2FA problems
Do these before losing access:
- Set up 2-Step Verification and a second independent way to sign in.
- Save backup codes somewhere safe, outside Gmail. Never share them.
- Confirm your recovery email and phone are still yours.
- Review recent activity and signed-in devices using Google Security Checkup.
- Check Gmail forwarding and filters for changes you did not make.
- Protect your devices against malware and suspicious browser extensions.
Open Google Security Checkup · Learn about backup codes
Gmail Doctor is a free, local-first command-line tool that helps you review settings in Gmail accounts you can still access.
- Emergency Help — explains where to go for account problems, no Google connection needed.
- Gmail settings scan — checks filters, forwarding and other available settings.
- Review before changes — you choose any filters to delete and must explicitly confirm.
It cannot check your Google sign-in sessions or 2FA status automatically. A clean Gmail settings scan does not mean your entire Google account is safe.
Requirements: Mac with Node.js 20 or newer. No Google login is needed to read Emergency Help.
git clone https://github.com/hkalbertkim/gmail-doctor.git
cd gmail-doctor
npm ci
npm link
# Start interactive Gmail Doctor; select Emergency Help from the menu:
gmail-doctor
# Try a safe synthetic Gmail settings scan:
gmail-doctor scan --demo
# Optional: print Emergency Help directly without connecting an account:
gmail-doctor triageAdvanced: connect a real Gmail account (developer preview)
Public Google OAuth verification is pending. There is currently no one-click public sign-in. To use Gmail Doctor with a real account you need your own Google Cloud Desktop OAuth client, Gmail API enabled and approved test-user access.
- Open Google Cloud Console and create or choose a project.
- Enable the Gmail API; configure OAuth consent and register yourself as a test user if in Testing mode.
- Create a Desktop app OAuth client. Save its downloaded JSON outside this repository.
- In your own terminal, run:
gmail-doctor setup --client ~/Downloads/your-desktop-oauth.json
gmail-doctor account add --account you@gmail.com
gmail-doctor scan --allGoogle handles sign-in and consent. Do not enter your Google password, backup codes or recovery codes into Gmail Doctor.
gmail-doctor Current interactive menu
gmail-doctor triage Emergency guidance (also inside the app)
gmail-doctor scan --demo Offline fictional demo
gmail-doctor scan --all Scan connected Gmail accounts
gmail-doctor scan --account EMAIL Scan a specific account
gmail-doctor scan --account EMAIL --json Machine-readable scan
gmail-doctor account add --account EMAIL Connect an account
gmail-doctor account list List accounts
gmail-doctor repair --account EMAIL --dry-run Preview possible changes
gmail-doctor repair --account EMAIL Interactive, explicitly approved deletion
gmail-doctor baseline save --account EMAIL Save reviewed trusted filter baseline
gmail-doctor baseline check --account EMAIL Check filter configuration drift
gmail-doctor logout --account EMAIL Remove local token
| Feature | Available? |
|---|---|
| Explain official recovery and prevention pathways | Yes — guidance |
| Audit Gmail filters, forwarding rules, aliases and available settings | Yes — with account authorization |
| Audit multiple connected accounts | Yes |
| Detect changes against a previously reviewed filter baseline | Yes |
| Preview filter deletions and save a local settings backup | Yes |
| Delete individually selected filters | Yes — only after typing REPAIR |
| Automatically undo deleted filters | No |
| Read Google login sessions, 2FA or recovery configuration through Gmail API | No |
| Recover locked accounts, bypass 2FA or prove an account is safe | No |
Scans are not proof of compromise. Legitimate rules may look unusual. Conversely, a clean Gmail settings scan does not rule out account takeover.
The tool only deletes explicitly selected Gmail filters after review and confirmation. It rescans before deleting and saves a local settings backup. Backups do not currently provide automatic rollback. Do not delete an unfamiliar rule until you understand its purpose.
The requested Gmail OAuth scope is gmail.settings.basic, which can change settings; it is not read-only. Normal scans do not intentionally change Gmail settings.
Developer notes: terminal interface
The current default interactive experience is a menu-based CLI with Emergency Help available from its main menu. Work on a Codex-inspired Rust terminal UI is isolated under experiments/codex-tui-spike and is not yet production-ready. We will not claim Codex visual or behavioral parity until real macOS Terminal testing succeeds. Scanning and repair logic are preserved during this work.
For technical context see TUI acceptance gates and real user problem reports.
Did the index help you find the right next step? If a useful official page or trustworthy open-source project is missing, or Gmail Doctor lacks a feature you need, open an issue. Include the situation and the resource or feature you are suggesting, not your email address, login details, recovery codes or tokens.
Corrections and pull requests are welcome. We review suggestions but cannot guarantee recovery outcomes or commit to implementing every request.
- Gmail message bodies and attachments are not read; this is a settings auditor.
- Sign-in occurs through Google OAuth, not through Gmail Doctor's own password form.
- OAuth refresh tokens are stored locally in macOS Keychain. Local configuration, account identifiers, baselines and backups remain on the device.
- No Gmail Doctor-hosted mailbox backend is required, though Google's OAuth and Gmail API endpoints are contacted.
- Do not post personal account data, tokens or backup codes in public issues.
Privacy Policy · Terms of Use · MIT License
npm test
npm run checkThis independent project is not affiliated with, sponsored by, or endorsed by Google. Gmail is a trademark of Google LLC.