Troubleshooting
What kelve says when something’s wrong, and what to do. Start with kelve status. It says whether kelve is running, where, and on which version.
kelve isn’t found
Your shell can’t find the kelve command. Open a new terminal. If it still isn’t found, add the folder the installer named to your PATH. On macOS and Linux, that’s ~/.local/bin.
The installer stops
| It says | What to do |
|---|---|
| “kelve has no build for … yet.” | Your system isn’t one kelve has a build for. Install it from source. |
| “The download doesn’t match the release’s checksum, so it wasn’t installed. Try again.” | Something changed the download on its way. Run the installer again. |
“kelve is running, so it couldn’t be replaced. Run kelve stop, then try again.” | On Windows: run kelve stop, then the installer again. |
Setting it up
| It says | What to do |
|---|---|
| “No agent kelve knows is installed here. …” | Give your agent kelve as an MCP server that runs kelve mcp, as Connect your agent says, then run kelve setup again. |
| “kelve couldn’t connect … itself. Run this where you use it: …” | Run the line it gives, in the terminal where you use your agent. |
| “kelve has hooks for … .” | kelve has no hook for the agent you named. Check its name against the list. An agent without a hook checks for notes, and asks for lessons, as kelve’s instructions ask. |
kelve doesn’t start or open
| It says | What to do |
|---|---|
| “kelve didn’t start. What went wrong is at the end of its log, …” | Read the end of the log it names, kelve.log in kelve’s data folder. |
| ”… isn’t valid: …” | A setting in the environment can’t be used. Change it as it says. Environment variables has each one. |
“kelve’s data was made by a newer kelve than this one, so this one can’t read it. Run kelve update, then start kelve again.” | Run kelve update, then kelve open. |
| “kelve couldn’t copy its data aside before updating it, to …” | Make room on the disk, then run kelve open again. |
“kelve couldn’t open a browser. Run kelve serve in a terminal instead: it shows a link there.” | Run kelve serve, and open the link it shows. |
“kelve didn’t say whether it opened. Check it’s running with kelve status.” | Run kelve status. If it’s running, open the address it gives. |
“kelve isn’t running. Start it with kelve serve.” | Run kelve open, or kelve serve to run it in that terminal. |
“kelve didn’t answer in time. Check it’s running with kelve status.” | Run kelve status. If it isn’t running, kelve open starts it. |
| “kelve can’t open a pull request by its address yet. …” | Check the pull request’s branch out, then run kelve diff main. |
| “kelve couldn’t show a picker here. …” | Open it from a terminal instead, with kelve open and its path. |
A sign-in link works once, within a minute. For a new one, run kelve open.
The secret
| It says | What to do |
|---|---|
“There’s no secret yet. Run kelve open once; starting kelve makes the secret this command uses.” | Run kelve open once. |
”… can be read by other people on this computer. Make it yours alone with chmod 600 …, then start kelve again.” | Run the chmod it gives, then kelve open. |
Your agent doesn’t have kelve’s tools
Start a new session with your agent after you connect it. Agents load their tools when a session starts. Check the line you added, on Connect your agent.
Nothing’s being read
If your agent’s list says “Waiting for you to ask Claude Code”, nothing’s taking the work waiting there. Your agent stopped, or is busy with something else. Use Copy what to say, then paste it to your agent. It says what’s waiting, for what that tab has open.
Updating
| It says | What to do |
|---|---|
| “kelve couldn’t find its newest release. Check you’re online, then try again.” | Check you’re online, then run kelve update again. |
| “kelve couldn’t download its newest release. …” | The same. |
| “kelve …‘s release has no build for this computer yet. Try again later.” | A new release can take a while to have every build. Try again later. |
| “kelve couldn’t put the new version in …” | Run kelve update as someone who can write to that folder, or install kelve again. |
“kelve is updated to …, but the kelve running didn’t stop. Run kelve stop, then kelve open.” | Run kelve stop, then kelve open. |
| “KELVE_UPDATES isn’t valid: …” | Set KELVE_UPDATES to off, or to an http or https address, or unset it. |
The shared graph
| It says | What to do |
|---|---|
| “kelve couldn’t reach the shared graph. Try again in a moment.” | Check you’re online, then try again. |
| “The shared graph doesn’t know this kelve any more. Sign in to it again.” | Sign in again, in Settings, The shared graph. |
| “This kelve’s graph key is set where it runs (KELVE_GRAPH_KEY), and that one wins. …” | Change or remove KELVE_GRAPH_KEY where kelve runs, then run kelve stop. |
| “This kelve has no shared graph to sign in to.” | KELVE_GRAPH_URL is off. Unset it to use the shared graph. |
Entries wait until tomorrow
The shared graph takes only so much from an account a day. kelve sends the rest when its day begins again, at midnight UTC. Settings, The shared graph, Sent today says when.
A lesson hasn’t gone
A lesson your agent learns waits a day before it goes, so you can stop it. Settings, Lessons says when each leaves.
Something went wrong in kelve
kelve keeps a short report when it stops unexpectedly, or when its page meets an error. The report holds no secrets, no file names and nothing you opened. Settings, What’s shared shows each report. You can choose Report it on GitHub, where you read it again before it’s posted. Or you can forget it.
Still stuck
Report a problem on GitHub, with what kelve said and what you ran. Leave out anything from your work you don’t want public.