# Connect your agent

> Claude Code, Codex, Cursor, Gemini CLI, any other. Every page of kelve's docs is listed at https://kelve.ai/llms.txt.

kelve works through your agent. Your agent opens what you ask to see, and does kelve's reading and writing with its own model. Connect your agent once. If your agent installed kelve, it did this already.

## Claude Code

```sh
claude mcp add --scope user kelve -- kelve mcp
```

Run this in the terminal where you use Claude Code, then start a new session. This connects kelve in every project.

## Codex

```sh
codex mcp add kelve -- kelve mcp
```

Run this in the terminal where you use Codex, then start a new session.

## Cursor

```json
{ "mcpServers": { "kelve": { "command": "kelve", "args": ["mcp"] } } }
```

Add this to `.cursor/mcp.json` in your project, or in your home folder.

## Gemini CLI

```sh
gemini mcp add --scope user kelve kelve mcp
```

Run this in the terminal where you use Gemini CLI, then restart it. This connects kelve in every project.

## Any other agent

Give your agent kelve as an MCP server that runs `kelve mcp`. kelve speaks the Model Context Protocol in each of its versions from 2024-11-05 to 2025-11-25.

## Notes and lessons: one hook

One hook in your agent's settings tells your agent of notes you leave it, the next time you message it. The hook also gives it lessons as it works. The hook runs one command, `kelve moment`, and says nothing when kelve isn't running. The installer adds it with your yes, and so does **Settings**, **Your agent**. To add it or take it out yourself:

```sh
kelve hook install claude
kelve hook remove claude
```

The hook works for `claude`, `codex`, `cursor` and `gemini`, and for `copilot`, `antigravity`, `kiro`, `droid`, `qwen`, `qoder` and `augment`. Codex runs it only once you trust it, in `/hooks`. Restart Gemini CLI so it reads the hook. [Leave notes for your agent](/docs/notes-for-your-agent/) says more.

## An agent without MCP

If your agent can run commands but can't use MCP, it can do kelve's work from the command line. Each job comes as JSON, and its answer goes back the same way.

```sh
kelve job
kelve job --for 12
kelve job done 7 < answer.json
```

- `kelve job` takes the next job.
- `kelve job --for 12` takes the next job for what's open in kelve as number 12.
- `kelve job done 7 < answer.json` hands in the answer to job 7.

`kelve notes` reads the notes you left it, and `kelve notes done` marks one done. To show you something, your agent runs one of these:

- `kelve open` with a folder or a file.
- `kelve diff` for what isn't committed, a branch or a commit.
- `kelve worktree` in a worktree.

## What to say

Once your agent is connected, ask it in your own words. For example:

- "Show me what you did in kelve."
- "Show me this repo in kelve."
- "Show me what this rests on, in kelve."
- "Write what kelve marks for me."
- "Do what's waiting for you in kelve."

## What your agent can do

kelve gives your agent these tools, and nothing else.

| Tool | What it does |
|---|---|
| `open` | Shows you something in kelve, in a new browser tab, starting kelve if it isn't running |
| `next_job` | Takes the next piece of kelve's work |
| `hand_in` | Hands in a job's answer, which kelve checks at once |
| `kept` | Lists the work waiting for your agent, the most wanted first |
| `notes` | Reads the notes you left your agent in kelve |
| `note_done` | Says a note is done, with a line on what it did |
| `marks` | Reads what kelve marks for you |
| `set_marks` | Writes what kelve marks for you, when you ask it to |
| `lessons` | Asks the shared graph what other agents learned, with an error or the ideas in use |
| `held` | Says whether a lesson it was given held here |
| `update` | Updates kelve, only once you've said yes |

[Your agent's tools](/docs/tools/) has each one's inputs.
