Quickstart: your first AI companion in 5 minutes

You'll make Kitchen Buddy, a companion that helps people while they cook, test it, and publish it.

Before you start

• Node.js 22 or newer (node --version).
• The Kol app on your phone, to approve your sign-in and to talk to your AI by voice.
• An AI key, to try your AI in text and to run tests. In the app: Companions → Your AI key (an OpenAI key). Kol never shows it again, and it's never stored in your project.

1. Install

npm install -g kol-cli
kol --version

Preview

Until launch, kol-cli isn't on npm. Install it from the repository instead:

git clone https://github.com/royeeshemesh/kol-cli.git
cd kol-cli
npm install
npm run build
npm link -w cli

During the preview the Kol team gives you a host address. Set it once per terminal: export KOL_HOST=<the address>.

2. Sign in

kol login

It shows a 6-character code. On your phone, open Kol, go to Companions → Creator portal, enter the code and tap Sign in. The terminal says Signed in as ….

3. Make a project

kol init kitchen-buddy --name "Kitchen Buddy"
cd kitchen-buddy

You get:

kol.json        name, look, voice, greeting…
persona.md      who it is and how it talks (a template to rewrite)
knowledge/      what it knows
tests/          conversations with checks
AGENTS.md       instructions for coding agents (plus a Claude Code skill and .mcp.json)

4. Write the persona

Replace everything in persona.md (the template's TODO lines must go, or kol validate will refuse it):

You are Kitchen Buddy, a calm and cheerful home cook who helps people while they cook.
Give one step at a time, then wait until they say they're ready.
Say quantities and times plainly. Offer a simple swap when they're missing something.
Food safety comes first.

Give it something to know. Create knowledge/kitchen-notes.md:

Salt pasta water well: about 10 grams of salt per litre of water.
For a runny yolk, boil eggs for 6 minutes. For a firm yolk, 9 to 10 minutes.
Cooked chicken must reach an inside temperature of 74 °C (165 °F).

And in kol.json, pick a matching look:

"icon": "restaurant",
"color": "#E8590C",
"voice": "cedar"

5. Check it and talk to it

kol validate
kol try "How long do I boil an egg for a runny yolk?"

You'll get something like:

For a runny yolk, six minutes. Then cool it in cold water so it stops cooking.

Want to see everything the AI is told, including Kol's own rules? kol prompt. Keep a conversation going with kol try --session s1 "...".

6. Add a test

Create tests/eggs.json:

{
  "name": "eggs",
  "turns": [
    { "user": "How long do I boil an egg for a runny yolk?", "expect": { "includesAny": ["6", "six"] } },
    { "user": "Are you a real person?", "expect": { "includesAny": ["AI"] } }
  ]
}

kol test

✓ basics
✓ eggs
2 passed, 0 failed

7. Save it and talk to it by voice

kol push

It's now a draft: only you can see it. Open Kol on your phone, go to Companions, and talk to Kitchen Buddy: hold the button, ask a question, let go.

8. Publish

kol publish

Kitchen Buddy is in the Kol marketplace. See how it's doing with kol status. Changed something? Edit the files, kol test, then kol publish again.

The same thing with a coding agent

Every project from kol init already has AGENTS.md, a Claude Code skill and .mcp.json, so an agent knows the workflow and gets the kol tools.

Claude Code: open the folder and ask:

cd kitchen-buddy
claude "Make this a cooking companion that teaches French basics. Test it, then publish it."

Codex: add the MCP server once in ~/.codex/config.toml, then ask the same thing:

[mcp_servers.kol]
command = "kol"
args = ["mcp"]

The agent signs you in by showing you a code to approve in the app, writes the persona, knowledge and tests, runs validate, try and test until everything passes, and publishes when you said so. More in Coding agents.

Next

• Concepts: companions and services, how calls work, the rules every AI follows.
• Testing and Publishing & versions.
• Examples: a cooking helper, a Spanish tutor, a standup note-taker.