Troubleshooting

Fixes for the problems that actually come up: the CLI isn't found, a session won't start, auth looks fine but every turn fails.

"Claude CLI — not found on this machine"

The claude binary isn't installed, or isn't where Foreman looked.

Run the setup wizard and use Install Claude Code, which runs the official installer and puts the binary in ~/.local/bin. If you'd rather install it yourself, do that and re-run the check.

"Found at … but not on shell PATH"

The binary exists but your shell can't see it, which means Foreman can't reliably spawn it either.

Use Add to ~/.zshenv in the wizard. It appends an export line for the binary's directory, guarded so repeated runs don't pile up duplicates. Re-run the check afterwards.

Auth says I'm signed in, but every turn fails with 401

This is the confusing one, and it has a real cause.

claude auth status reads credentials from disk and never contacts the network. An OAuth login whose refresh token has expired still reports a valid-looking email and plan — so a machine that fails every single turn can pass a naive check with a green tick.

Foreman guards against this by exercising the credential with a small real turn before showing you a healthy state. If you're seeing the contradiction anyway:

Re-run the setup check and let it verify rather than trusting a cached verdict.
If it still fails, run claude auth login and sign in again.
Re-run the check once more. The stale "couldn't authenticate" banner clears once auth has been verified healthy, not merely re-read.

If the session is set to Run on: API key, a 401 is about the key, not your subscription — no CLI sign-in will fix it. Check the key instead.

A session won't start

The reason is on the session card. Foreman does not leave you with a silent spinner, so read the card before anything else.

Common causes:

Concurrency gate. Every launch passes through a shared gate that caps how many sessions start at once and backs off when a rate-limit signal arrives. A queued session is waiting, not broken.
Rate limit. If your account is being throttled, the gate pauses launches rather than hammering. It resumes on its own.
Free plan cap. Free allows any number of open sessions but three running a turn at once. Overflow queues rather than failing.

Fan-out says it needs a git repository

Fan-out gives each lane its own isolated worktree, and worktrees require git. Initialise the repo, or run the task as a single session instead.

A scheduled task didn't run

Scheduled runs need the app to be running. If your Mac was closed at the scheduled time, the run fires the next time you open Foreman and is marked ran late so you can tell a catch-up from an on-time run.

Runs that find nothing to do finish silently by design. You're notified when there's a change to review, or when a run failed — with the reason.

An MCP server or plugin change isn't taking effect

A session binds its MCP servers and plugins when it spawns. Signing in to a server after that doesn't reach a session already running.

Restart the session. There is no way around this — it's a property of how the CLI loads them at start.

Foreman is billing my API key when I expected the subscription

Check the session's Run on setting. Interactive sessions default to the subscription; scheduled, bulk and fan-out runs default to the API key, because unattended bursts on a subscription are the fastest route to a throttle.

The auth row on the context meter shows which credential a session is actually using, which is the fastest way to confirm what happened rather than what you intended.

Still stuck

Email [email protected]. Include what the session card said — that message is usually the whole diagnosis.