Troubleshooting

Whatever the symptom, these checks resolve most problems. Work down the list. Each one is quick, and none of them lose your work:

1. Wait for the model to finish downloading. Cotypist can't suggest anything until its AI model is in place. The menu bar icon shows download progress while a model is being fetched.
2. Check that Cotypist is enabled for this app. Click the small Cotypist icon next to the text field, or open App Settings, and make sure the current app isn't switched off.
3. Confirm Accessibility permission is granted. Cotypist can't work without it. Check System Settings > Privacy & Security > Accessibility and make sure Cotypist is listed and enabled.
4. Try the force-activate completions shortcut. Press Ctrl+` (Ctrl plus the key above Tab) while in the text field. If completions appear, the issue was auto-activation, not Cotypist itself. This shortcut may be unassigned on some keyboard layouts, so you can set it in Shortcuts settings.
5. Restart Cotypist. Quit it from its menu bar icon and open it again.
6. Restart your Mac. This clears up a surprising number of permission and state issues.
7. Check whether the app is supported. A few apps can't be supported at all (for example the Ghostty and cmux terminals), and others (such as Google Docs) need a one-time setup step. The compatibility page shows what to expect for each.
8. Turn on "Improve Compatibility With This App." In App Settings, under Troubleshooting, this option often gets completions working in apps where they otherwise wouldn't.

If you're not seeing any suggestions, work through the first steps above. Beyond those, the cause usually falls into one of these cases:

It happens in one specific app

Completions work elsewhere but not in one app:

• Make sure that app isn't disabled in App Settings (or via the Cotypist icon next to the text field).
• Turn on App Settings > Troubleshooting > Improve Compatibility With This App. This is the single most effective fix for apps that don't show completions, and it's especially worth trying in Electron-based apps (e.g. some chat and AI tools).
• Restart the app, then Cotypist. In a few apps (notably Slack and Chrome), completions can occasionally stop appearing on their own, and restarting the affected app usually brings them back.
• Some apps simply can't work with Cotypist at all. See Specific Apps & Websites below.

It's a small text field, or a terminal

Cotypist intentionally stays idle in small text fields (search boxes, single-line form fields, and the like) so it doesn't get in the way when you're quickly tabbing through a form. Press the force-activate completions shortcut (Ctrl+` by default) to turn suggestions on for that field.

In the terminal, Cotypist supports Terminal.app and iTerm2 only, and it activates automatically just for AI-agent prompts like Claude Code and Codex. For ordinary command-line typing it stays idle, though pressing the force-activate shortcut may bring up completions there too.

You pressed Escape

Esc dismisses the current suggestion and briefly pauses completions in that field. By default they come back on their own after a few seconds, or as soon as you keep typing. If you’ve set Esc to turn completions off until you switch apps (in Shortcuts settings), bring them back by switching apps and returning, or by pressing the force-activate shortcut.

It stopped working after an update

If completions worked before and stopped after updating, first restart your Mac. If they still don't come back, send us a support request so we can take a look.

It only happens in full-screen

A few apps expose their text differently in full-screen mode, which can stop completions. Try the force-activate shortcut, or use the app in a regular window to confirm that's the cause, and let us know which app it is so we can look into it.

For the full list of shortcuts and how to customize them, see the Shortcuts guide. The most common shortcut problems:

Tab interferes with moving between fields or indenting

Cotypist uses Tab to accept the next word, which can collide with using Tab to move between form fields or to indent. You have several options:

• Option+Tab (or Option-click the Cotypist icon next to the field) sends a normal Tab through, even when a suggestion is showing, so you jump to the next field.
• Esc, then Tab: press Esc to dismiss the current suggestion (completions briefly pause), then Tab behaves normally.
• Disable the Tab shortcut for specific apps (from the Cotypist icon next to the field) or globally (in Shortcuts settings), while keeping the key-above-Tab shortcut for full completions.

A shortcut does nothing, or the wrong key is shown

• The "accept full completion" and force-activate shortcuts default to the key above Tab (`, §, or ^). On some layouts that key is unassigned by default, so set your own in Shortcuts settings.
• On non-US keyboard layouts, the shortcut recorder can show a different key label than expected, and some layouts use keys like the backtick as a "dead key" for accents. What matters is that you press the same physical key when recording and when triggering. The shortcut will work even if the displayed label looks off. If a key won't record at all, pick a different one.

Another tool is intercepting the key

If a shortcut works in some apps but not others, another tool may be grabbing the same key first. Grammarly also uses Tab for its suggestions, and tools like Karabiner-Elements or TextExpander can intercept keys before Cotypist sees them. Changing one side's shortcut to a different key usually resolves the conflict.

Your full-completion key stops working in every app (Secure Input)

If your full-completion key (the one above Tab — often ^, `, or §) suddenly does nothing in every app, while Tab still works to accept completions one word at a time, another app has most likely turned on macOS Secure Input. This is a privacy feature for password fields that stops other apps from seeing your keystrokes. Normally it switches off the moment you leave the password field, but if an app turns it on and forgets to turn it back off (after a crash, for example), it stays on and quietly blocks single-key shortcuts system-wide. Tab and any shortcut that uses a modifier key (like ⌘ or ⌃) keep working.

When this happens, Cotypist adds a note to its menu and shows a banner in Shortcuts settings telling you which key is affected. (macOS doesn't reliably reveal which app is responsible, so Cotypist no longer tries to guess — naming the wrong app only sends you chasing the wrong thing.) To get going again:

• Press Tab in the meantime — it still accepts completions a word at a time, so you're not stuck while you track down the cause.
• Quit your recently-used apps one at a time, checking after each. Password managers (and their browser extensions) are the most common cause, so quit them fully, not just the browser tab. Browsers left on a password field and screen-sharing tools are frequent culprits too.
• If you use Terminal or iTerm, check that Secure Keyboard Entry is turned off in its menu.
• As a last resort, log out and back in, or restart your Mac; this always clears Secure Input. Restarting Cotypist alone won't help, because the lock is held by another app.

Cotypist works in most Mac apps out of the box. A few need a setup step, and some can't work at all. The full list lives on the compatibility page; here are the cases support hears about most:

• Google Docs needs Accessibility mode turned on. Cotypist usually offers a button to enable it when you start editing; if not, turn on both "screen reader support" and "braille support" under Tools > Accessibility (the braille one is easy to miss). See Google Docs setup.
• Arc & Dia need a one-time setting so suggestions can appear inline; Firefox and Zen Browser can only show suggestions in a mirror window. See Arc & Dia setup.
• Terminals: Terminal.app and iTerm both work. Cotypist activates automatically for AI-agent prompts (Claude Code, Codex, etc.), and you can force-activate for regular commands. Ghostty, cmux, and Warp are not yet supported. See Terminal support.
• Code editors (VS Code, Cursor, Windsurf): Cotypist activates automatically in the sidebar AI-chat panels, where you type natural-language prompts to coding agents like Claude Code, Codex, or Copilot. It deliberately stays out of the main editor, where your editor's own code completions belong, and the force-activate shortcut won't change that. If suggestions don't appear automatically in a chat panel, try the force-activate shortcut there and let us know, so we can enable it by default for that field. See Code editors.
• Electron-based apps have limited accessibility support. Often App Settings > Troubleshooting > Improve Compatibility With This App, plus the force-activate shortcut, is enough to get completions working.

Some apps can't work with Cotypist

Cotypist relies on the macOS Accessibility API to read the text field you're typing in and insert completions. Some apps don't support that API well enough for Cotypist to function. That includes Sublime Text, OneNote, and Anki, plus apps running inside a virtual machine or remote desktop (Parallels, Citrix). In these cases there's no workaround on our end; the app's developer would need to add the missing support. The compatibility page has the current status for each app.

Cotypist requires Accessibility permission to function, and uses Screen Recording (optional) to read surrounding on-screen context. If a permission prompt keeps reappearing even after you've granted it, or completions don't work despite the permission looking enabled, reset the permission:

1. Open System Settings > Privacy & Security.
2. Under Accessibility and again under Screen Recording, select Cotypist in the list and click the − button to remove it.
3. Restart your Mac.
4. Launch Cotypist and grant the permissions again when prompted.

If accepting a completion inserts the text twice, there are probably two copies of Cotypist running at once, interfering with each other. To fix it:

1. Check your menu bar, or open Activity Monitor, for more than one Cotypist instance.
2. Quit all of them (from the menu bar icon, and force-quit any leftover in Activity Monitor).
3. Launch Cotypist once, fresh, from your Applications folder.

If typing and mouse clicks feel laggy across your entire Mac — not just in one app — and it slowly gets worse over days but feels fine again right after a restart, a background app is most likely to blame. This is not caused by Cotypist, but Cotypist can often spot it, so it shows you a “Mac feeling slow?” note in its menu when it does.

Every app can register “event taps” with macOS to watch your keyboard and mouse. A well-behaved app removes its taps when it’s done. A few apps have a bug where they leave old, dead taps behind — a handful more every time your Mac sleeps and wakes. Over days these pile up into the hundreds or thousands, and macOS has to route every keystroke and click past all of them, which slows the whole system down. Cotypist itself doesn’t leak taps; it only detects the pile-up and points at the app responsible.

The apps we most often see doing this are:

• Karabiner-Elements (version 16.1.0 and earlier)
• Mos (version 4.2.x and earlier)

Other keyboard, mouse, and macro utilities can have the same bug. To get back to normal:

• Quit and reopen the app that’s responsible. That clears its leaked taps immediately, without a full restart. (For Karabiner-Elements, whose helper runs in the background, quitting from Terminal with sudo pkill -f Karabiner-Core-Service, or simply restarting your Mac, does the job.)
• Update it to the latest version, and if the problem keeps coming back, let that app’s developer know — the real fix has to happen in their app.
• Restarting your Mac always clears the backlog, which is why the slowdown resets after a reboot — but it’ll build up again until the underlying app is fixed.

If none of the above resolves your issue, please reach out, and include as much detail as you can. A short screen recording or screenshot of the problem is often worth a long description.

You can send us a support request or use the website contact form.