When Reeve isn't working as it should

Your assistant doesn't have Reeve's tools#

• Check the setup against the Connect your AI to Reeve card on Reeve's page: the node and cli.ts paths must be this PC's, and the server's name reeve. Restart the assistant after any change.
• Run the command yourself to see whether it starts: node %USERPROFILE%\.reeve\app\src\cli.ts mcp. It waits quietly for an assistant on stdin; an error means Reeve's install needs repairing: run Castellan's setup again, with Install again what's installed already ticked. See Install Castellan.
• Some assistants load MCP tools only when asked. The reminders, turned on with hooks on, tell such an assistant how to load Reeve's.

Your assistant has the tools but doesn't use them#

Put the line from Connect your AI coding assistant to Reeve in its instructions file, and turn on the reminders if your assistant takes them. The ai-use job's alert says which it is: setup (the sessions never had Reeve connected), the assistant (it had Reeve and forgot him: correct it), or a gap in Reeve. For a gap, send us the report: node %USERPROFILE%\.reeve\app\src\cli.ts ai-use --report.

A call times out#

The first search in a big repository builds its index, the first upgrades reads every changelog, and lint_docs runs the project's TypeScript: each can take minutes. Raise your assistant's tool timeout (to 600 seconds, say). To build a repository's index ahead of time:

node $HOME\.reeve\app\src\cli.ts index C:\Projects\YourRepo

Search says it ranked by keywords#

No embedding model could be had: the local AI isn't set up on this PC, or every accelerator serving embeddings has failed. Run Castellan's Set up local AI, or the Smith's Set up. A failed accelerator is tried again after 10 minutes. See Where Reeve's work runs.

Model answers are slow#

Model work takes turns with every other agent's, one request at a time on the NPU. A long input is split into chunks, about 10 seconds per 120 lines. Accelerators, on Reeve's page, shows who holds each and who's waiting. If a GPU is held back, a game may be using it. Prefer the tools that use no model (outline, refs, changes, history): they answer at once.

A job says it needs approval#

Its script is new, or an update changed it. Reeve runs only scripts you've approved, by their exact fingerprint. Under Needs you on Reeve's page: View the script, then Approve (or Approve all read-only jobs).

A job that changes repositories does nothing#

• It's off. fast-forward, repo-sync, worktree-tidy and project-branches are off on a new install: Turn on under Jobs.
• Its first run after turning on is a dry run. Its result starts "Dry run", and says what it would do. It acts from the next run.
• It's paused, or Reeve is off duty: Resume, or Start on Reeve's card in Castellan.

A checkout wasn't fast-forwarded#

fast-forward names each checkout it left alone, and why: it has local commits, uncommitted changes, a merge or rebase under way, another git command running there, or a file marked assume-unchanged or skip-worktree. Only main, master, release branches and origin's default branch are ever moved, and never a detached HEAD. Commit or push what's there, and the next round moves it.

A clone left on a work branch goes back to the default branch only once everything on that branch is in origin's default branch and the clone hasn't been touched for a day. One with commits of its own stays where it is.

A worktree wasn't removed#

worktree-tidy keeps a worktree with anything changed or untracked, a commit only on this PC, a git-ignored file that isn't build output (a .env, a local database), or one touched in the last 2 days (7 when it's only pushed). Its result names each one kept, with the files.

A repository is missing, or shouldn't be there#

See Your repositories in Reeve: add a folder to Search folders or the repository to Other repositories, or Leave alone one you don't want touched. Scan again looks now, rather than after the 10 minutes the list is kept.

Pull requests, checks or security alerts are missing#

They come from GitHub through gh. Install it and sign in (gh auth login); without it, ci and pr say so, pull requests aren't shown, and dependency health has no security alerts.

Reeve's page won't open#

Reeve's page is http://reeve.localhost:18383/. Open on its card in Castellan starts it if it's down. It starts at sign-in from the scheduled task \Reeve\Home page, and every round starts it again if it has stopped. If its port is taken, Castellan says so in Needs you.

Still stuck?#

Write to us at support@castellan-software.com with Reeve's version (on its card in Castellan), what you asked, and what it said. A job's log is linked from its row under Jobs: look it over before you send it, as it holds paths on your PC.