Using Kol with coding agents

The kol CLI was built to be driven by agents as well as people:

• every command takes --json and prints one JSON object with ok, and on failure error and hint;
• exit codes say what happened: 0 ok, 1 error, 2 not signed in;
• nothing asks questions; sign-in can be split in two steps an agent can handle;
• kol mcp (or kol-mcp) is an MCP server with the same operations as tools.

Every project made by kol init contains:

File	For
AGENTS.md	The workflow and the rules, for any agent (Codex and others read it)
CLAUDE.md	Points Claude Code to AGENTS.md
.claude/skills/kol/SKILL.md	A Claude Code skill: "build, test and publish this Kol AI"
.mcp.json	Starts the kol MCP server for agents that read it (Claude Code, Cursor)

Claude Code

Inside a project, the MCP server and skill are picked up automatically (Claude Code asks once to allow the project's MCP server). Then just ask:

claude "Make this a language tutor for beginner Italian. Add a phrase list and tests. Publish it when the tests pass."

Outside a project (for example to start one), add the server for yourself:

claude mcp add kol -- kol mcp

Codex

Add the server to ~/.codex/config.toml:

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

Codex reads AGENTS.md in the project. Without MCP it can use the CLI directly; AGENTS.md tells it to use --json.

Cursor

Cursor reads .mcp.json-style config from .cursor/mcp.json. Copy it there:

mkdir -p .cursor && cp .mcp.json .cursor/mcp.json

Signing in from an agent

The agent can't approve the code for you; you do it on your phone:

1. The agent calls kol_login_start (or kol login --no-wait --json) and shows you a 6-character code.
2. You open Kol → Companions → Creator portal and enter it.
3. The agent calls kol_login_finish (or kol login --code … --device … --json), which waits until you approve.

The sign-in is saved on your computer for 90 days, for you and every agent you use.

What a good agent session looks like

1. kol_whoami: signed in? Has an AI key?
2. kol_init (or edit the existing project).
3. Write persona.md, knowledge/, tests/.
4. kol_validate until ok.
5. kol_prompt to read what the AI will be told.
6. kol_try a few times; kol_test until everything passes.
7. kol_push, and ask you to try it by voice.
8. kol_publish only when you asked for it.

All tools: MCP reference.

Keep agents safe

• Projects never contain secrets, so agents never need your token or AI key.
• Ask agents to publish only on your say-so; the templates' AGENTS.md already says this.
• Try-outs and tests use your AI key. An agent looping on kol_test spends a little each time; Kol limits try-outs to 120 an hour.