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
| Symptom | Cause | Fix |
|---|---|---|
| My agent does not know about Blume | The 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 finish | The 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 unreachable | The 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 app | The 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:
- Open Plugin and choose Update on the agent.
- To keep it updated, open the agent’s menu and turn Automatic updates on.
- 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:
- Check the agent on the Plugin page.
- Open Settings, then Projects, then Project choices, and set the project to Use Blume or Ask first.
- Start a new conversation and ask the agent to track the work in Blume.
Conversations do not show
| Symptom | Cause | Fix |
|---|---|---|
| No conversations from a project | The 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 late | Check for activity is set to an interval. | In Settings > Projects, set Check for activity to As it happens. |
| Older conversations are missing | With 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 show | Blume 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 offers | Cause | Fix |
|---|---|---|
| How to connect | Claude Code or Codex is not installed or not signed in on this computer | Run claude auth login or codex login in a terminal, complete the sign-in, then refresh Usage |
| Grant access | Claude Code is signed in, but macOS did not let Blume read its credential | Follow Make Claude usage work on Mac |
| Connect Cursor | Blume has no Cursor session | Sign in at cursor.com, copy the WorkosCursorSessionToken cookie from your browser’s developer tools, paste it in and choose Connect |
| What happened | Blume could not read the plan | Read the reason, then choose Try again |
Pi and Oh My Pi do not expose usage to Blume.
GitHub facts are missing
| Symptom | Cause | Fix |
|---|---|---|
| A delivery shows no checks, reviews or deployments | GitHub 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 delivery | A 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 stale | Blume 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.