Troubleshooting

Installing

Windows says "Windows protected your PC"

The Windows installer isn't code-signed yet. Choose More info → Run anyway. Some antivirus tools are also wary of unsigned apps; you may need to allow ThreadGrid there.

There's no build for my computer

The beta runs on Apple Silicon Macs (macOS 13 or later) and Windows 10 or 11 on x64. There's no Intel Mac, Windows on ARM or Linux build yet.

Agents

"The claude CLI isn't on your PATH." (or codex, or opencode)

ThreadGrid couldn't find the tool. Check that it runs in a new terminal window:

claude --version
codex --version
opencode --version

If it works in a terminal but ThreadGrid can't find it, quit and reopen ThreadGrid so it picks up your PATH. ThreadGrid also looks in the usual install folders: Homebrew, ~/.local/bin, npm, Bun and each tool's own installer on a Mac; npm, pnpm, WinGet, Scoop and Bun on Windows.

The Grid page says "Not signed in"

Sign in to the tool in a terminal (⌘J or Ctrl+J opens one in ThreadGrid), then click Refresh on the Grid page:

claude auth login
codex login
opencode auth login

Claude's capacity shows nothing

Claude reports its usage while it runs, so the reading appears after its first job. OpenCode's capacity is always unknown: it doesn't report limits.

Claude on Windows doesn't start

The claude CLI needs Git for Windows. Install it and reopen ThreadGrid.

Threads and jobs

"Compare needs a git project" (or the Orchestrator)

Each attempt or worker gets its own git worktree, so the folder has to be a repository. Run git init in it (and make a first commit), then try again. Plain threads work in any folder.

My work is going to the wrong agent, or queued

Open the thread to see why ThreadGrid picked that agent. An agent low on capacity may be preserved by Capacity Protection (Grid page). If every agent is preserved and the setting is Queue, work waits for the earliest reset. You can start a queued run now, or pin an agent in the composer: a pinned agent always runs.

Fusion skipped the Test stage

ThreadGrid didn't find a test command. Set one in Settings → Projects, in the project's Tests field.

"ThreadGrid: this push wasn't approved."

An agent tried to push and the approval was denied, or ThreadGrid wasn't running to ask you. Pushes always need your approval, however the agent runs git. On Windows, the check needs Git for Windows.

Where are my thread's changes?

By default each thread works on a new branch in its own worktree, not in your checkout. Find the worktrees in Settings → Worktrees → Show. To work in your checkout instead, choose Current checkout in the composer's workspace menu.

Computers and pairing

"No other computers online"

Both computers must be signed in to the same ThreadGrid account, with ThreadGrid open. Check Settings → Account on each. On Windows, ThreadGrid may be running in the tray.

"… is offline. Is ThreadGrid open on it?"

Open ThreadGrid on the other computer. To keep it reachable, turn on Keep this PC awake (or Mac) in its Settings → Power.

"Runs a different version of ThreadGrid" or "Update ThreadGrid on both computers"

Update both computers to the same version (see Updates, below), then pair again.

"ThreadGrid was reinstalled there, so its key changed."

Choose Remove for that computer, then pair again.

Updates

ThreadGrid checks for updates when it starts and every four hours, downloads them in the background, and installs when you quit. When one is ready, Settings → About shows Restart to update.

Where ThreadGrid keeps things

• Mac: ~/Library/Application Support/ThreadGrid/
• Windows: %APPDATA%\ThreadGrid\

That folder holds the thread history (threadgrid.db), the worktrees and the app log (logs/threadgrid.log). It's kept when you uninstall.

Report a problem

Go to Settings → About → Export diagnostics and choose Export…. It saves a text file with versions, agent states and the app log, with secrets removed. No prompts, code or tokens, and nothing is sent anywhere. Email it to [email protected] with a line about what you were doing.