Troubleshooting

Causes and fixes for the common problems: an agent that is not connected, an outdated plugin, conversations that do not show, and missing usage.

Find your symptom below. Each entry gives the cause and the fix. Start on the Plugin page: its Overview shows, for each agent, whether Blume is installed, up to date and connected.

After any fix, start a new agent conversation. A conversation that was already open keeps its old state.

The agent is not connected

SymptomCauseFix
My agent does not know about BlumeThe plugin is not installed in that agent, or the conversation was open before you installed it.Open Plugin. If the agent’s tile says Install, choose it. Then start a new conversation.
The app says an agent “is not reaching Blume: its key was refused”The agent’s key was revoked or is no longer valid. Nothing from that agent reaches Blume.Choose Reconnect in the warning at the top of the app, or on the agent’s tile. Then start a new conversation.
The agent’s tile says “Not found”The agent is not installed on this computer, or Blume could not find its command.Install the agent, then choose Check again.
The install did not finishThe Plugin page shows the reason under Blume could not be installed. Nothing else on your computer was changed.Choose Try again. If it fails again, open the agent’s menu, choose Copy install command, and run it in a terminal where your agent runs.
The agent says Blume is unreachableThe plugin could not reach your workspace. Nothing is saved.Check your network connection and that you are signed in to the Blume app, then ask the agent to try again.
Blume stopped working in an agent after I moved or removed the appThe plugin runs its scripts with the Blume app. Without it, the plugin falls back to node on your PATH, which may be missing or too old.Open Plugin, open the agent’s menu and choose Reinstall.

The plugin is outdated

Cause: Blume updates the plugin in Claude Code and Codex only for installs the app made, and only while Automatic updates is on for that agent.

Fix:

  1. Open Plugin and choose Update on the agent.
  2. To keep it updated, open the agent’s menu and turn Automatic updates on.
  3. Start a new conversation. An open one keeps the version it started with.

No deliveries appear

Cause: Agents create deliveries. None shows up when the plugin is not installed, when you answered No or Never in this project to “Track this work in Blume?”, or when the project is set to Skip.

Fix:

  1. Check the agent on the Plugin page.
  2. Open Settings, then Projects, then Project choices, and set the project to Use Blume or Ask first.
  3. Start a new conversation and ask the agent to track the work in Blume.

Conversations do not show

SymptomCauseFix
No conversations from a projectThe project is set to Skip, or Show is set to Projects that use Blume.In Settings > Projects, set Show to All projects, or change the project’s choice under Project choices.
Recent work is missing or lateCheck for activity is set to an interval.In Settings > Projects, set Check for activity to As it happens.
Older conversations are missingWith All projects, Blume reads the last day first, then older history a day at a time while the computer is quiet.Wait. The same settings page shows how far the history has got.
Conversations from one agent never showBlume reads conversations from Claude Code, Codex, Cursor, Pi and Oh My Pi only.See Supported agents.

Usage is missing

Open Usage and look at the plan’s card. It offers the fix that matches the cause.

The card offersCauseFix
How to connectClaude Code or Codex is not installed or not signed in on this computerRun claude auth login or codex login in a terminal, complete the sign-in, then refresh Usage
Grant accessClaude Code is signed in, but macOS did not let Blume read its credentialFollow Make Claude usage work on Mac
Connect CursorBlume has no Cursor sessionSign in at cursor.com, copy the WorkosCursorSessionToken cookie from your browser’s developer tools, paste it in and choose Connect
What happenedBlume could not read the planRead the reason, then choose Try again

Pi and Oh My Pi do not expose usage to Blume.

GitHub facts are missing

SymptomCauseFix
A delivery shows no checks, reviews or deploymentsGitHub is not connected, or Blume was not given the repository.Open Settings, then GitHub. Connect, then choose the repositories. See GitHub.
A pull request is not on its deliveryA pull request joins a delivery through a link the agent records, or through the branch the agent reported.Ask the agent to link the pull request to the delivery.
GitHub facts are staleBlume checks linked pull requests about once a minute while the app is open. It pauses when your GitHub request quota runs low.Open the delivery to make Blume read it again. Settings > GitHub shows the last sync and, when paused, the time it resumes.

FAQ

My agent keeps asking whether to track the work. How do I stop that?

Answer Always in this project or Never in this project, or set the project’s choice in Settings > Projects > Project choices.

I set a project to Skip by mistake. Are its conversations gone?

Skip removes the conversations Blume stored for that project on this computer. The agent’s own session files are not touched. Change the choice back and Blume reads them again.