Docs
kelve.aiGitHub

Your agent’s tools

kelve mcp gives your agent eleven tools over the Model Context Protocol, and instructions on when to use them. It speaks MCP versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.

open

open opens kelve for you on what you asked to see, in a new browser tab. It starts kelve if it isn’t running. It says how many files there are, and how many need reading. It also gives your agent the number of what it opened, to take its jobs by.

InputWhat it is
whatNeeded. change: what isn’t committed, a branch against a base, or one commit. worktree: everything in its worktree since it left its base, committed or not. folder: a folder, or the whole repository. files: some files. file: one file.
pathThe folder or file, from the root. For a change or a worktree, the folder your agent is working in.
pathsFor files: each file, from the root.
baseFor a change or a worktree: the branch it’s read against, such as main. Left out for what isn’t committed.
commitFor a change: one commit.
titleWhat it is, in a few words, at most 80 characters.
saidWhat it is, or what changed and why, at most 200 characters.
modelThe model your agent runs on, as it names it.

When you ask what it did, your agent shows only what’s new since it last showed you. When it hands work over, by committing, pushing or opening a pull request, it shows you that too, without being asked.

next_job

next_job takes the next piece of kelve’s work. A job is one of these:

  • finding a way in
  • reading files
  • tracing an idea down
  • writing or fixing an entry
  • saying plainly what part of your work does
  • doing a note
  • writing a lesson

Each job has its instructions, its material, and the shape its answer must fit. next_job says so when there’s no more.

InputWhat it is
forThe number of something open in kelve. Only its jobs come. open gives the number, and so does what kelve gives you to say for one tab, “(number 12)”. Left out, any job.
haveThe instructions and answer shapes your agent already has in full in this conversation, by name, such as read@10 and shape:1a2b3c4d. A job following one of those comes with its name alone.
modelThe model your agent runs on. It goes to the shared graph with what it writes.

hand_in

hand_in hands in an answer to a job. kelve checks the answer’s shape at once. An answer that doesn’t fit comes back with why, to hand in again. When kelve takes the answer, the next job comes with it.

InputWhat it is
jobNeeded. The job’s number, as next_job gave it.
answerNeeded. The answer, in the job’s shape.
morefalse for the last job your agent will take. No next job comes, and your agent is told how many are left.
for, have, modelAs for next_job.

kept

kept lists kelve’s work waiting for your agent, the most wanted first, as you see it on its list. No inputs.

notes

notes gives the notes you left your agent in kelve that are waiting, for the project it’s working in. Each note comes with:

  • its id and version
  • what it asks
  • the file and lines it’s on, as they are now
  • other notes on the same lines
  • the ideas on those lines

For a note done before, notes also gives what it said then, what was done, and what’s been added since. No inputs.

note_done

note_done marks a note done, with a line on what your agent did. Then your agent opens what it changed, so you see it beside your note.

InputWhat it is
noteNeeded. The note’s id, as notes gave it.
versionNeeded. The note’s version, as notes gave it. A note changed since isn’t marked done.
didNeeded. What your agent did, at most 300 characters.

lessons

lessons gives what other people’s agents learned using the same ideas, from the shared graph. Each lesson comes with how far it’s confirmed, and a check to make first when it isn’t. Lessons says more.

InputWhat it is
problemWhat failed, as the tool said it. kelve takes your work’s own names out before it looks.
ideasThe ideas, libraries or tools your agent is using, by name, such as pytest. Left out, what this work uses: the libraries its files import and the tools run here.
writetrue keeps a job for what your agent learned itself, to take with next_job.

held

held says what came of a lesson kelve gave your agent. A lesson that doesn’t apply is kelve’s miss, and never counts against the lesson. Only the lesson and what came of it go to the shared graph.

InputWhat it is
lessonNeeded. The lesson’s id, as kelve gave it.
heldWhether it held, where it applied.
appliesfalse when it doesn’t apply here at all.
whyWhy it didn’t hold or apply, in a line, at most 200 characters, with nothing from the work.

marks

marks reads what kelve marks for you:

  • how much overall
  • how well you know each area
  • ideas always and never marked
  • anything in your words
  • whether files read as code or plainly

No inputs.

set_marks

set_marks writes what kelve marks for you, in place of what was there. Your agent uses it only when you ask it to. Then your agent tells you what it wrote.

InputWhat it is
markNeeded. How much to mark anywhere not named in areas: new (every idea), learning (all but the basics), working (advanced and specialist ideas) or deep (specialist ideas only).
readHow code files read: code or plainly.
areasNeeded. How well you know each area. Each has an area, such as rust, and a level. A language also has its own read.
alwaysNeeded. Ideas to always mark, by name.
neverNeeded. Ideas never to mark, by name.
wordsNeeded. Anything else, in your words.

update

update updates kelve to its newest version, as kelve update does. It restarts kelve if it’s running, and says what it did in a sentence. Its description tells your agent to call it only once you’ve said yes. No inputs.

When your agent uses them

kelve’s instructions tell your agent to use these tools:

  • when you ask to see something in kelve
  • when you ask it to do kelve’s work
  • when you’ve left it notes

Your agent checks notes before it starts anything you ask. When you ask it to do what’s waiting for you in kelve, it takes jobs with the number you give. Without a number, it takes any job. When something fails and it doesn’t know why, it asks lessons. It says with held whether a lesson it was given held. With a dozen files or more to read, it shares the jobs among subagents, if it can. Each subagent uses the same for.

When a newer kelve is out, kelve tells your agent once, with your next message or at the end of a tool’s answer. Your agent asks you whether to update, and calls update only if you say yes.