Troubleshooting
Start here when something isn't moving or won't start. Most problems come down to Claude Code not being found or signed in, or a task waiting on something it tells you about.
Why is my task waiting?
A task that isn't running always says why, on its work block and on its task page. The reason comes with the time it started and, where there is one, when it'll resume. Here's what each one means and what to do.
| What it says | What it means | What to do |
|---|---|---|
| Waiting for approval | A plan or a ship is waiting at a gate you set. | Open the decision card and choose Approve plan or Ship it, or Send back with a note. Change the gates in Settings → Autonomy & gates. |
| Needs you | A question, or a failure the team can't fix alone. | Read the card in the thread or in Needs you, then Answer or Retry. The card says what went wrong. |
| Waiting for PAIR-14 | Another task has to finish first. If that task is stuck too, its key is named here. | Open the named task and sort that out; this one starts by itself afterwards. If you cancel the other task, this one drops it and carries on. Use Unblock to start anyway. |
| Waiting for a free slot | The project already has as many teammates working, or as many pieces of work in progress, as it's allowed at once. | Nothing; it starts when one finishes. To run more at once, raise Parallel agents or Work in progress in Settings → Autonomy & gates. |
| Usage limit, resumes 3:40 PM | Your Claude account reached its usage limit. | Nothing; it resumes at the time shown. To keep going sooner, add a second Claude or Codex account in Settings → Accounts. |
| Paused | The project, or the whole app, is paused. | Resume the project from its menu, or turn off Pause everything in the menu bar. |
| Budget reached | A daily or per-task limit you set in Usage & limits was reached. | Daily limits reset at midnight. For a per-task limit, choose Raise limit or Stop here on the card. See Usage and limits. |
| Retrying at 3:12 PM | A run failed for a passing reason, such as the network or a crash, and will try again. | Nothing, usually. Press Retry to try now. If it keeps failing, it moves to Needs you. |
| Queued | It's ready and next in line. | Nothing; it starts in moments. |
Waiting tasks are also checked in the background. A step that stops responding is restarted on its own, so a task never stays stuck without saying so.
Claude Code isn't found
ThreadGrid looks for claude in these places:
~/.claude/local~/.local/bin/opt/homebrew/bin/usr/local/bin
If yours is somewhere else, run which claude in Terminal and paste the path into Claude Code location in Settings → App. Then press Check again in the first-launch check, or Run a test in Settings → App.
Claude says I'm not signed in
Open Terminal, run claude, and type /login. Then press Test Claude in ThreadGrid.
Everything stopped at once
That's usually a usage limit on your Claude plan. Every waiting task says when it resumes, and so does the engine status at the bottom of the sidebar. There's nothing to fix: work picks up by itself. If you've added more than one account, ThreadGrid has already switched; see Usage and limits.
A ship failed
If it failed before the merge, nothing changed: read the reason in Needs you, fix it (often a dirty base checkout or a merge conflict) and press Retry. If it failed after the merge, the change is already in your base branch and the team has opened an urgent fix task. See Shipping targets.
The checks keep failing
The team runs your project's check commands (tests, typecheck, lint) before anything ships. If they fail on your base branch too, every task will fail verify. Run them yourself in the project folder; fix them or ask the team to in a thread ("the tests on main are failing, please fix them first"). You can change the commands in Settings → Project.
Logs
ThreadGrid keeps logs in ~/Library/Application Support/ai.threadgrid.desktop/logs. Include them when you report a problem.
Still stuck?
Email [email protected] with what you expected, what happened and the logs.
Something unclear or out of date? Email [email protected].