Skip to content

Documentation

Every command

Commands starting with / are typed in Kaivo’s message box. The others run from your terminal. Each example shows what you’ll see; projects, files and e-mail addresses in them are made up. Type /help in Kaivo for the full list.

Conversation

/new

also /clear

Starts a new, empty conversation. The previous one is saved and can be reopened with /sessions.

kaivo · example

› /new

New conversation. The previous one stays in /sessions.

/sessions

also /resume

Opens the list of your saved conversations so you can resume one, with its whole history.

kaivo · example

› /resume

Pick a session:

› Fix the mobile cart (yesterday)

Add e-mail sign-in (Monday)

/rename

Renames the current conversation so you can find it easily.

kaivo · example

› /rename Mobile cart fix

Session renamed: Mobile cart fix

/export

Writes the conversation to a Markdown file (automatic name, or the one you give).

kaivo · example

› /export notes.md

Conversation exported to notes.md

/copy

Copies Kaivo's last answer to the clipboard.

kaivo · example

› /copy

Last answer copied to the clipboard.

/recap

Asks Kaivo for a short recap: what was done, what is left, the decisions made.

kaivo · example

› /recap

Done: the “Add to cart” button reacts to touch.

Left: add a test for the empty cart.

Decision: keep onClick rather than onPointerDown.

/compact

Summarises the conversation and continues in a new session that starts from that summary, to free up room without losing the thread. Kaivo also does it on its own near the limit.

kaivo · example

› /compact

Summarising the current session…

New session created from the summary.

/quick

also /rapide

Quick chat for small scripts (Python, Lua/Luau for Roblox, Bash…). Kaivo answers without tools: it neither reads nor changes your project. A QUICK badge shows in the status bar; /quick again to go back to normal mode.

kaivo · example

› /quick a Lua script that spins a Part

local part = script.Parent

game:GetService("RunService").Heartbeat:Connect(function(dt)

part.CFrame *= CFrame.Angles(0, dt, 0)

end)

Working on the project

/init

Kaivo analyses the project and writes Kaivo.md: test commands, code style, conventions. It reads it again at every launch.

kaivo · example

› /init

● ls .

● view package.json

● write Kaivo.md

Kaivo.md created: npm commands, folder structure, conventions.

/plan

Asks for a detailed plan before acting. Kaivo reads the project but changes nothing and runs no command that changes anything.

kaivo · example

› /plan add e-mail sign-in

● glob src/**/auth*

● view src/lib/session.ts

1. Create the /api/login route

2. Add the form in login.tsx

3. Test with an existing account

Risk: current sessions will be invalidated.

/goal

Give a goal: Kaivo splits it into short steps, does them one by one and asks for your approval before each change.

kaivo · example

› /goal add a dark mode

Step 1/3: colour variables in globals.css

● edit src/app/globals.css

Allow the change? [Allow] [For this session] [Deny]

/explain

Explains a file, a function or a folder in plain words: what it's for, how it works, the tricky parts. Changes nothing.

kaivo · example

› /explain src/lib/session.ts

● view src/lib/session.ts

This file creates and checks the user's session. Tricky part: the token expires after one hour.

/fix

Describe a problem: Kaivo looks for the cause by reading the code, explains it in one sentence, then proposes the smallest possible fix.

kaivo · example

› /fix the button doesn't respond on mobile

● grep "onMouseDown" src/components

● view src/components/AddToCart.tsx

Cause: the button listens to onMouseDown, which doesn't fire on touch.

● edit src/components/AddToCart.tsx -onMouseDown +onClick

/commit

Kaivo looks at your changes, proposes a clear commit message and only commits if you agree.

kaivo · example

› /commit

● bash git status

● bash git diff

Proposed message: “Fix the cart button on mobile”

Commit? [Allow] [Deny]

/todo

Finds every TODO, FIXME and HACK in the project and lists them by file, with a suggested priority.

kaivo · example

› /todo

● grep "TODO|FIXME|HACK" .

src/api/pay.ts FIXME handle partial refunds (high priority)

src/ui/Menu.tsx TODO close on outside click (low priority)

/memory

Shows Kaivo.md, the project's memory, or offers to create it if it doesn't exist.

kaivo · example

› /memory

● view Kaivo.md

Tests: npm test · Lint: npm run lint · Style: short functions, no default export.

/skills

Lists the installed skills (in the project's .kaivo/skills and in ~/.kaivo/skills) and reminds you how to add some. Each skill also runs with /skill-name.

kaivo · example

› /skills

/api-review [project] Review a REST API and flag weaknesses

/go-tests [global] Write table-driven Go tests

/create-skill

You describe what the skill should do, Kaivo writes its folder and SKILL.md. Add --global so it works in all your projects.

kaivo · example

› /create-skill review a REST API and flag security mistakes

● write .kaivo/skills/api-review/SKILL.md

Skill “api-review” created. Run it with /api-review.

/add-skill

Installs an existing skill from a folder, a SKILL.md file or a link (GitHub links work). Add --global to keep it for all your projects.

kaivo · example

› /add-skill https://github.com/you/skills/blob/main/api-review/SKILL.md

Skill “api-review” added. Use it with /api-review

/image

Attaches the image in your clipboard to your message (screenshot, mock-up, error). Shortcut: alt+v. You can also drop an image file into the terminal. Requests with an image go through a free model that can read images.

kaivo · example

› /image

Image-1.png attached

› rebuild this mock-up in HTML and CSS

/files

Opens the file picker to attach an image to your message.

kaivo · example

› /files

Pick a file to attach:

› error-screenshot.png

Review and check

/diff

Kaivo runs git status and git diff, then summarises the current changes file by file.

kaivo · example

› /diff

● bash git status

● bash git diff

AddToCart.tsx: the button now listens to onClick.

AddToCart.test.tsx: new test for touch.

/review

also /code-review

Reviews your current changes and flags likely bugs, things forgotten and improvements, most important first. Changes nothing.

kaivo · example

› /review

● bash git diff

1. pay.ts: the amount isn't validated before sending.

2. Menu.tsx: the click listener is never removed.

3. Variable name `d` is unclear.

/security-review

Security review: hard-coded secrets, injections, unchecked input, risky dependencies, wrong permissions. Ranked by severity, with a fix for each problem.

kaivo · example

› /security-review

● grep "API_KEY|SECRET" src

High: a key is hard-coded in config.js, line 12.

Medium: the SQL query in search.ts concatenates user input.

/simplify

Reviews recently changed code and simplifies it without changing what it does: dead code, repetition. You see the changes before they're applied.

kaivo · example

› /simplify

● view src/lib/format.ts

Two functions do the same thing: I'll merge them.

Allow the change? [Allow] [Deny]

/verify

Finds and runs the build, lint and test commands, then summarises what passes, what fails and the likely cause of each failure.

kaivo · example

› /verify

● bash npm run lint ✓

● bash npm run build ✓

● bash npm test ✗ 1 test fails

Failure: cart.test.ts expects 2 items, it gets 1.

/run

Finds out how to start the project, starts it, then tells you what shows up and whether everything seems to work.

kaivo · example

› /run

● bash npm run dev

The server starts on http://localhost:3000, with no error.

Model and permissions

/mcp

also /plugin, /plugins

Connects Kaivo to other tools through MCP servers: Roblox Studio, a browser, library documentation… /mcp add roblox installs it in one command (Node.js required). Restart kaivo after adding one; every tool of a plugin asks for your approval.

kaivo · example

› /mcp add roblox

Plugin “roblox” added. Restart kaivo to enable it.

› /mcp

roblox [ready] npx -y robloxstudio-mcp@latest

/model

Opens the model picker. With your Kaivo account the model is chosen for you; if you set your own keys (OpenAI, Anthropic…), you choose here.

kaivo · example

› /model

Pick a model:

› Kaivo Code

/theme

Opens the terminal colour theme picker.

kaivo · example

› /theme

Pick a theme:

› kaivo

dracula

/readonly

Turns read-only on or off during the session: no more changes or commands. Accepts on or off; without an argument, it toggles.

kaivo · example

› /readonly on

Read-only on: no more changes or commands.

› Fix this bug

✗ edit src/app.ts — denied: read-only mode

/custom-key

Adds your own API key: OpenAI, Anthropic, Gemini, Groq, OpenRouter, xAI, Mistral, DeepSeek, or any OpenAI-compatible API. When the Kaivo model reaches its limit or is overloaded, Kaivo retries the request with your key, on its own. The key stays on your computer (~/.kaivo/keys.json); requests are billed by your provider.

kaivo · example

› /custom-key

Add your own API key

› OpenAI gpt-4.1

Anthropic (Claude) claude-sonnet-4-20250514

Google Gemini gemini-2.0-flash

Custom provider any OpenAI-compatible API

OpenAI API key: ••••••••••••••••

Key “openai” saved. Kaivo will use it when the Kaivo model reaches its limit.

/bypass

No human approves anything any more: Kaivo changes your files and runs commands without asking. A red BYPASS badge stays in the bottom bar. Keep it for a project under Git. /bypass off to go back; turning it on leaves read-only.

kaivo · example

› /bypass on

⚠ Bypass mode on

No human approves anything any more.

Be in a project under Git, so you can undo everything.

› Add a test for the empty cart

● write src/cart.test.ts (without asking)

● bash npm test (without asking)

/permissions

Opens a window that explains the three modes (normal, read-only, bypass) and marks the active one.

kaivo · example

› /permissions

Permissions

Current mode: normal (it asks before acting)

→ Normal: Kaivo asks before changing a file or running a command.

Read-only (/readonly): it reads your project but can't change or run anything.

Bypass (/bypass): no approval, it acts on its own.

Account and maintenance

/status

Opens a window with the session status: version, signed-in account, model, permission mode, working folder and context used.

kaivo · example

› /status

Kaivo 1.15.0 · you@example.com · model kaivo.code · read and write · C:\projects\shop

/stats

Opens a dashboard of your activity: sessions, messages, tokens, active days, current and best streak, with an activity calendar. It also shows on the home screen. The numbers come from your sessions saved on this computer.

kaivo · example

› /stats

Sessions 12 Messages 148 Total tokens 312,400

Active days 9 Current streak 3 days Best streak 5 days

■ ■ ■ ■ ■ ■ ■ ■ activity calendar, one square per day

/usage

also /cost, /context

Opens a window right away: your account, your usage limits (one bar for the 5-hour session and one for the week, with the reset time), the cost of the conversation, the context used and your project's activity.

kaivo · example

› /usage

Usage

Account

you@example.com · FREE plan

Usage limits

Current session (5 h)

▰▰▰▰▰▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱ 20 % · resets in 3 h 40

This week

▰▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱ 4 % · resets in 5 d 2 h

This conversation

Cost: free (the Kaivo model costs nothing)

Context: ▰▰▰▰▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱▱ 20 %

41,200 / 200,000 tokens · /compact to free up room

/doctor

Runs the installation check and opens the full report in a window: running program, sign-in, network, tools.

kaivo · example

› /doctor

Check: 9 ok · 5 to watch · 0 problem(s). Details: kaivo doctor

/update

Looks for and installs the latest version, then asks you to quit and restart kaivo to use it.

kaivo · example

› /update

Kaivo 1.16.0 is installed. Quit and restart kaivo.

/version

Shows the installed version of Kaivo CLI.

kaivo · example

› /version

Kaivo CLI 1.15.0

/config

Opens a window that shows where the configuration files, the project memory and your session are.

kaivo · example

› /config

Configuration

Files

~/.kaivo.json settings for everywhere

./.kaivo.json settings for this project

Kaivo.md project memory

/login

Opens your browser to sign in to your Kaivo account.

kaivo · example

› /login

Signed in as you@example.com. Restart kaivo to use this account.

/signup

Opens your browser on the Kaivo sign-up page, then signs you in.

kaivo · example

› /signup

Signed in as you@example.com. Restart kaivo to use this account.

/logout

Deletes the session saved on this computer.

kaivo · example

› /logout

Signed out. Restart kaivo to sign in again.

/whoami

Shows the signed-in Kaivo account.

kaivo · example

› /whoami

Signed in as you@example.com

Help and links

/help

also /?, /commands

Opens the list of every command (the palette), including your custom commands. Pick one to run it.

kaivo · example

› /help

Commands:

› /new New conversation

/plan Prepare a plan without changing anything

/review Review the changes

/docs

Opens the Kaivo CLI documentation in your browser.

kaivo · example

› /docs

Opened in your browser: https://kaivoia.site/docs/kaivo-code

/feedback

also /bug

Prepares an e-mail to the team, with the Kaivo version in the subject. Tell us what works and what doesn't.

kaivo · example

› /feedback

Opened in your browser: mailto:kaivo-support@kaivoia.site

/logs

Opens the application logs, useful to understand unexpected behaviour.

kaivo · example

› /logs

Application logs (Esc to go back)

/quit

also /exit

Quits Kaivo CLI, after confirmation.

kaivo · example

› /quit

Quit Kaivo? [Yes] [No]

Terminal

kaivo

Starts Kaivo CLI in the current folder. If you aren't signed in, a screen offers to sign in or create an account.

kaivo · example

$ kaivo

Welcome to Kaivo CLI

› Sign in

Create an account

Quit

kaivo login

Opens the sign-in screen: Sign in or Create an account, then finish in the browser.

kaivo · example

$ kaivo login

Your browser opened. Finish signing in, then come back here.

Signed in as you@example.com.

kaivo signup

Opens the sign-up page directly in your browser.

kaivo · example

$ kaivo signup

Signing in to Kaivo: opening your browser...

Signed in as you@example.com.

kaivo logout

Deletes the session saved on this computer.

kaivo · example

$ kaivo logout

Signed out.

kaivo whoami

Shows the e-mail address of the signed-in account.

kaivo · example

$ kaivo whoami

you@example.com

kaivo -p

Headless mode: one question, one answer, then the program stops. Every permission is accepted automatically: add --read-only if you want it to change nothing.

kaivo · example

$ kaivo -p "Explain what main.go does"

main.go starts the HTTP server and wires up the API routes.

kaivo -p -f json

Same thing, with JSON output for your scripts.

kaivo · example

$ kaivo -p "List the config files" -f json

{ "response": "package.json, tsconfig.json, .env.example" }

kaivo --bypass

Starts Kaivo straight in bypass mode: no approval requests. Same precautions as /bypass (project under Git, right folder).

kaivo · example

$ kaivo --bypass

(Kaivo opens with the BYPASS badge at the bottom)

kaivo --read-only

Read-only: Kaivo reads and analyses your project but can neither change a file nor run a command, even with -p. Ideal to audit a project or in a script.

kaivo · example

$ kaivo -p "Audit this project" --read-only

● grep "password" src

✗ edit src/config.js — denied: read-only mode

A password is hard-coded in src/config.js. I changed nothing.

kaivo doctor

Checks the installation: conflicting command in the PATH, sign-in, access to the site, tools and language servers found. Exits with an error code if it finds a real problem.

kaivo · example

$ kaivo doctor

Installation

✓ the “kaivo” command in the PATH is this program

Account

✓ signed in: you@example.com · FREE plan

Tools

! rg not found: fast code search (optional)

kaivo -update

Updates Kaivo automatically: downloads the latest version, checks its SHA-256 fingerprint and replaces the program. Same as kaivo update; add --check to only check.

kaivo · example

$ kaivo -update

New version: 1.16.0 (installed: 1.15.0)

Downloading...

Kaivo 1.16.0 is installed.

kaivo -c

Starts Kaivo CLI in another folder.

kaivo · example

$ kaivo -c ./my-project

kaivo -d

Turns on debug logs.

kaivo · example

$ kaivo -d

kaivo -v

Shows the installed version.

kaivo · example

$ kaivo -v

1.15.0

Missing a command? Tell us on the contact page: your feedback decides what comes next.

In the CLI, type / to see them all.
Every Kaivo CLI command