Project files

kol.json

The definition of your AI. kol init writes it with a $schema line, so editors check it as you type.

Field	Required	Allowed	Description
name	yes	text, up to 24 characters	What people call it. Short: the app shows 16 characters in calls.
kind	yes	companion, service	companion: people get it and talk to their own copy. service: a public AI with its own Kol ID that anyone can call; you pay for its calls. Fixed after the first push.
tagline	yes	text, up to 80 characters	One line for the marketplace card.
description		text, up to 400 characters	A few sentences for its page (optional).
persona		string	File with its instructions: who it is, how it talks, what it knows and won't do (20–2000 characters). Default persona.md.
greeting		text, up to 200 characters	First words. {owner} = the name of who it talks to. Empty: a default.
icon	yes	sparkles, chatbubbles, restaurant, school, fitness, heart, musical-notes, book, briefcase, leaf, rocket, happy
color	yes	#3B5BDB, #E8590C, #2F9E44, #C2255C, #7048E8, #0C8599, #E67700, #495057
voice	yes	marin, cedar, coral, sage, ash, verse, ballad, alloy
price		0, 0.99, 1.99, 2.99, 4.99	USD a month for a companion; 0 = free. Nobody is charged yet.
answersForOwner		boolean	Companions only: it may answer calls for its owner when they cannot, and take a message.
requests		object or null	It takes requests (orders, bookings) and sends them to you after the caller confirms.

Other files

Path	What it is
persona.md	Its instructions (or the file persona names). 20 to 2,000 characters.
knowledge/*.md, knowledge/*.txt	What it knows. Each file is one item, titled by its file name. 40,000 characters in total.
knowledge/urls.txt	Public web pages, one per line (# starts a comment). Read when you push.
tests/*.json	Scripted conversations, see below.
.kol/	Which AI this folder is on each host, and kol try sessions. Keep it out of git.

Tests

Each file in tests/ is one conversation:

{
  "name": "orders",
  "as": "owner",
  "turns": [
    {
      "user": "Hi! Can I order a pizza?",
      "expect": {
        "includesAny": [
          "pizza"
        ],
        "maxWords": 60
      }
    },
    {
      "user": "Yes, please send it.",
      "expect": {
        "tool": "send_request"
      }
    }
  ]
}

as is owner (default) or standIn (it answers a call for its owner). Each turn can check:

Check	Passes when
includesAny	The reply contains at least one of these (any case).
includesAll	The reply contains every one of these.
excludes	The reply contains none of these.
matches	The reply matches this regular expression (case-insensitive).
tool	The AI used this tool in this turn, e.g. send_request.
noTool	The AI used no tool in this turn.
maxWords	The reply has at most this many words.