Kirak for AI Coding Agents

A Kirak project is mostly JSON: models, kirak.json, agent files. A coding agent (Claude Code, Codex, Cursor and others) that edits them needs facts it cannot guess reliably – which modules exist, what a provider’s settings and secrets are called, which keys a file accepts – and needs to know whether its edit is valid before the app is started. The kirak CLI answers both, for the Kirak version the project actually has installed.

The rule for an agent: ask the CLI instead of guessing, and validate after every edit.

Set up a project for an agent

kirak new my-api          # a new directory
kirak new --here          # or the directory the agent already has open

Besides the project files, kirak new writes what an agent and an editor use:

AGENTS.md – short instructions most coding agents read on start: run the project’s own kirak, get facts with --json, validate after every edit, review migration SQL before applying it, and build Kirak first (data only through the facade and kirak.graphql(), providers before integration code, settings in kirak.json). Edit it freely; kirak new --here keeps an existing one.
.kirak/*.schema.json – the JSON Schemas of the installed Kirak, and a "$schema" key in kirak.json and models/posts.json pointing to them.
.vscode/settings.json – maps kirak.json, models/*.json and agents/*.json to those schemas.
.env.example – the secrets the project’s kirak.json needs, generated from the same data as kirak env.

For an existing project, kirak schema writes .kirak/, and kirak info warns when the schemas there are from another Kirak version.

Use the project’s `kirak`

Facts depend on the installed version and its extras, so the agent should run the kirak of the project’s virtual environment (.venv/bin/kirak, on Windows .venv\Scripts\kirak.exe), not one installed elsewhere. Commands work from any directory inside the project; --dir points at another one.

Install the Kirak plugin

AGENTS.md gives every agent the facts and the rules. The Kirak plugin adds what facts cannot: skills that teach model design, access rules, modules and providers, migrations, custom logic, AI agents and frontend clients; hooks that validate every edit of a Kirak file, remind about migrations and ask before destructive kirak db commands; and a review command. It never holds a copy of a Kirak fact – it asks the project’s own kirak.

The plugin lives in kirak-agent-kit:

Tool	Install
Claude Code	`/plugin marketplace add kirak-io/kirak-agent-kit`, then `/plugin install kirak@kirak`
Codex	`codex plugin marketplace add kirak-io/kirak-agent-kit`, then install `kirak`; trust its hooks in `/hooks`
Cursor	Cursor Marketplace, or add the repository as a plugin source
GitHub Copilot (VS Code, CLI)	“Chat: Install Plugin From Source” with the repository URL, or the Copilot CLI marketplace
Google Antigravity	copy `plugins/kirak-antigravity/` into `.agents/plugins/` (project) or `~/.gemini/config/plugins/`

Facts

Every facts command prints text by default and one JSON document with --json:

Command	Answers
`kirak info`	Project root, manifest, enabled modules, models, agents, migrations, schemas
`kirak modules [NAME]`	Kirak’s modules, or one module in full: settings schema, operations with their typed parameters, hook events, provider kinds
`kirak providers MODULE [TYPE]`	A module’s providers, or one in full: settings, secrets and their environment variables, pip extra, capabilities, a `kirak.json` example
`kirak catalog`	All of the above in one document, plus social login providers and AI model providers
`kirak env`	The environment variables the project needs and whether each is set – names only, never values
`kirak schema --print NAME`	The JSON Schema of `models`, `model`, `manifest`, `agent`, `mcp` or `tools` files
`kirak db status`	Migrations applied, pending or modified
`kirak db makemigrations --dry-run`	The SQL the next migration would contain; nothing written, no database needed

The JSON envelope is the same for all of them:

{"kirak_version": "0.1.1", "command": "info", "ok": true, "data": {...}, "problems": []}

Exit code 0 means no errors (warnings may be present), 1 means problems has errors, 2 means the command was used wrongly (for example outside a project). Each problem has a stable code – see Problem Codes. No command prints a secret value: values from .env and the environment are masked in every output. See the CLI reference for every option.

The modules the catalog describes:

Module	Install	Summary
`auth`	always on	Registration, login (password, OTP, social, MFA), JWT and API keys, email verification and password reset. Always enabled.
`ai`	`pip install "kirak[ai]"`	LLM prompts and agents (defined in agents/*.json) with native Kirak tools, conversations, cost caps and review loops, on pydantic-ai.
`mcp`	`pip install "kirak[mcp]"`	MCP servers for AI agents, one JSON file each in mcp/: the Kirak operations each server offers as tools, who may connect, and a rate limit. Served at /mcp// over Streamable HTTP.
`monitoring`	`pip install "kirak[monitoring]"`	Request metrics, slow requests, captured logs, audit and AI run records in a local SQLite file, with retention and read endpoints for dashboards.
`notifications`	an extra per provider	Email, SMS, push, instant messages and outgoing webhooks through named provider instances, plus an in-app inbox and per-user channel preferences.
`payments`	an extra per provider	Payments through named provider instances: checkout, webhooks with signature checks, refunds, subscriptions, saved payment methods, marketplace payouts.
`scheduler`	an extra per provider	Background jobs and recurring tasks: enqueue, delay, retry with backoff, several queues and queue backends.
`storage`	`pip install "kirak[storage]"`	Image and file uploads through named provider instances, with type and size limits, compression, resizing and thumbnails.
`vector`	an extra per provider	Vector stores and embeddings for retrieval (RAG): indexes, upsert, delete, fetch, search and embed. No HTTP endpoints; call it from your own routes, hooks and agent tools.

Validate after every edit

kirak validate --json                                  # the whole project
kirak validate models --file draft.json --json         # a draft, before writing it
kirak validate --override model:comments=c.json --json # one model file replaced by a draft

kirak validate reports every problem at once: structure (against the same schemas), references between files (a relationship to a model that does not exist, two agents with the same name, a missing instructions file), providers (unknown or missing settings, secrets written in kirak.json, extras not installed) and unset environment variables (warnings). Startup runs the same checks, so a project that validates does not fail startup on its config files.

After a model change, show the SQL before generating the migration:

kirak db makemigrations --dry-run --json
kirak db makemigrations add-status-field
kirak db migrate

The running app’s API

The commands above describe the project and the installed Kirak. For the API a running app serves – the endpoints, request and response shapes and access rules an agent calls, for example from a frontend in another repository – read GET /docs on that app (curl http://localhost:8000/docs), or /openapi.json for typed clients. See API Docs Endpoint.

Dev MCP server

The same facts and checks are also available as MCP tools, for coding tools that prefer tools over shell commands. kirak dev mcp is a small MCP server that the coding tool starts itself, as a child process, and talks to over stdin/stdout. It opens no port and needs no credentials; it runs only while the coding session does.

It is not the MCP server an app serves to its own users (the mcp module): this one runs on your machine, for the agent writing your project.

Install it in the project’s environment:

pip install "kirak[dev-mcp]"

Tools (all read-only; each returns the same JSON as the matching command’s --json):

Tool	Same as
`kirak_project_info`	`kirak info`
`kirak_catalog`	`kirak modules [NAME]`, `kirak providers MODULE [TYPE]`; with `listing`, the social login or AI model providers from `kirak catalog`
`kirak_schema`	`kirak schema --print NAME`
`kirak_validate`	`kirak validate`; drafts are passed as JSON, nothing is written
`kirak_env`	`kirak env`
`kirak_migration_status`	`kirak db status`
`kirak_migration_preview`	`kirak db makemigrations --dry-run`

Live tools report what the project’s app has been doing, from the files it writes – so they also answer after the app has stopped or crashed:

Tool	Returns	Reads
`kirak_recent_errors`	Recent errors with tracebacks and the request that failed	Monitoring store, else `kirak.log`
`kirak_recent_requests`	Recent requests: method, path, status, duration; filter by status (`5xx`, `404`), route, or slowest first	Monitoring store
`kirak_request_trace`	One request: its steps (hooks, database and provider calls with timings), errors and logs	Monitoring store, else `kirak.log`
`kirak_recent_agent_runs`	Recent AI agent runs (model, tokens, cost, status) with their tool calls	Monitoring store
`kirak_api_docs`	The running app’s `GET /docs`	HTTP, localhost only

The monitoring store is written by the monitoring module (pip install "kirak[monitoring]"). Turn it on in development only, with kirak.local.json – lists there replace the ones in kirak.json, so repeat your modules:

{ "modules": ["payments", "storage", "monitoring"] }

Without it, errors and request traces come from kirak.log (the result says so), and the request and agent-run tools report that monitoring is off. The tools find both files where kirak.json puts them (monitoring.db_path, log_path).

Starting it from a coding tool

The command must run the project’s own Kirak. With uv: uv run kirak dev mcp. Otherwise the venv’s Python: .venv/bin/python -m kirak dev mcp (Windows: .venv\Scripts\python.exe -m kirak dev mcp). The coding tool starts it in the workspace folder, which is where it looks for the project.

Claude Code, .mcp.json in the project:

{ "mcpServers": { "kirak": { "command": "uv", "args": ["run", "kirak", "dev", "mcp"] } } }

Codex, .codex/config.toml in the project (trusted projects):

[mcp_servers.kirak]
command = "uv"
args = ["run", "kirak", "dev", "mcp"]

VS Code (Copilot), .vscode/mcp.json:

{ "servers": { "kirak": { "type": "stdio", "command": "uv", "args": ["run", "kirak", "dev", "mcp"] } } }

Other tools take the same command and arguments in their own config format.

A project created during the session. The coding tool starts its MCP servers when the session opens. If Kirak is not installed yet at that moment (a brand-new project), the start fails and the tool does not retry it. After installing Kirak, reconnect the server once: in Claude Code, /mcp and reconnect kirak; in other tools, reload the MCP servers or start a new session. An existing project never needs this.

Tools that are not in the project

A tool that manages projects from outside – a hosted builder, a CI job – can run the same commands against a project checkout with --dir, using a Kirak installed for the tool itself. Two options let it describe a runtime it does not share:

--extras ai,payments-stripe – the extras installed where the project will run, instead of the ones installed alongside the tool.
--env-names-file names.txt – the names (one per line, no values) of the variables that will be set, instead of reading .env and the environment.

The same functions are importable: kirak.catalog (the catalog) and kirak.validation.validate_project() (validation), both taking names only, never secret values.