For AI Agents

This page is written for AI coding agents (Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, and others) tasked with adding ClickHouse schema management to a user’s project. It tells you what to ask, what to install, and what not to do unprompted.

If you’re a human who landed here, copy the prompt below into your agent — it points the agent back at this page and lets it drive the rest.

Copy this prompt

Paste this into your coding agent to start setup:

Set up chkit (ClickHouse schema management) in this repo. First fetch
https://chkit.obsessiondb.com/ai-agents.md and follow the instructions there:
ask me the setup questions, install the agent skill, scaffold the config,
recommend any plugins this project needs, and walk me through the first
migration. Don't apply anything to the database without confirming with me first.

Every docs page is available as raw Markdown by appending .md to its URL — this page is /ai-agents.md. A full machine-readable index lives at /llms.txt.

What chkit is

chkit is a ClickHouse schema and migration toolkit for TypeScript. Schemas are defined in TypeScript, diffed into migration SQL, applied to ClickHouse, and verified against the live database.

You drive chkit with shell commands, plus an installable agent skill that loads its full command surface, schema DSL, and workflows into your context.

Step 1 — Ask the user before scaffolding

chkit’s interactive CLI asks these questions when a human runs it. You run it non-interactively, so you ask them. The answers select which commands you run — ask all three up front, then act. Do not assume answers; if the user just says “set up chkit”, ask first.

1. New project or existing project?

   • New / empty directory → scaffold from a curated example with create-chkit (Step 3a).
   • Existing TypeScript project → install chkit and run chkit init in place (Step 3b).

2. Is there an existing ClickHouse database with tables to manage?

   • Yes → add @chkit/plugin-pull and introspect the live tables into schema files, so the user starts from real tables instead of the blank example (Step 5).
   • No → keep the scaffolded example schema and edit it to match the first table.

3. How should chkit connect to a database? — the same four paths as the CLI’s connect prompt:

   • Claim a free ObsessionDB dev instance — fastest; needs the user’s email and a one-time code they receive by email.
   • Already have an ObsessionDB account — log in and pick a service.
   • Already have a ClickHouse instance — connect with environment variables.
   • Configure later — scaffold only; the user wires up the connection themselves.

Step 2 — Install the agent skill

chkit ships an installable agent skill that teaches you its commands, schema DSL, and workflows. Install it first — it is the most reliable way to operate chkit correctly:

chkit skills add obsessiondb/chkit

The skill installs into the project’s agent directory (for example .claude/skills/chkit/ or .cursor/skills/chkit/). On an interactive chkit init, chkit also detects the active agent and offers to install the skill automatically.

Step 3 — Scaffold based on the answers

3a. New project — create-chkit

create-chkit downloads a curated example and wires it to the user’s package manager. Pass a target directory and an example to skip the prompts:

bun create chkit@latest my-chkit-app --example clickbench

It then runs the same connect flow as chkit init (Step 4). Drive it non-interactively with --connect <choice> (and --email for the claim path), or --skip-onboarding to scaffold only.

3b. Existing project — chkit init

Install chkit as a dev dependency, then initialize in the current directory:

bun add -d chkit @chkit/core
chkit init

chkit init writes clickhouse.config.ts and src/db/schema/example.ts, and installs any missing chkit packages so the scaffolded config resolves. It is idempotent — re-running it leaves existing files untouched.

Without a TTY, init prints the connect runbook (Step 4) instead of prompting. Pass --yes to skip onboarding entirely (a silent file-writer for CI), or --connect <choice> to drive a specific path.

Edit src/db/schema/example.ts to match the table the user actually wants before running generate (unless you are pulling from an existing database — see Step 5).

Step 4 — Connect a database

Map the answer from question 3 to commands. Both chkit init and create-chkit accept the same flags, so you can drive any path without a TTY:

Choice	Flag	What to run
Claim a free ObsessionDB dev instance	--connect claim --email <you@example.com>	Two steps — see below. Needs a code emailed to the user.
Existing ObsessionDB account	--connect account	chkit obsessiondb login
Existing ClickHouse instance	--connect clickhouse	Set CLICKHOUSE_URL (and CLICKHOUSE_USER / CLICKHOUSE_PASSWORD / CLICKHOUSE_DB)
Configure later	--connect later or --yes	Nothing — scaffold only

The claim path is two steps and needs a human in the loop, because the code arrives by email:

chkit obsessiondb signup --email <you@example.com>   # sends a one-time code
# ask the user for the code from their inbox, then:
chkit obsessiondb signup --email <you@example.com> --code <CODE>
chkit obsessiondb service claim                      # provisions the free dev instance

Any connected path keeps the obsessiondb() plugin registered in clickhouse.config.ts — claiming and account login need it for the remote executor, and it rewrites Shared engines when targeting non-ObsessionDB ClickHouse.

Step 5 — Pull existing tables (only if the user has a populated database)

If the user answered yes to question 2, adopt their existing schema instead of the blank example. Add the plugin, register it, and introspect:

bun add -d @chkit/plugin-pull
# register pull() in the plugins array of clickhouse.config.ts
chkit pull

This writes schema files from the live tables, so generate diffs against what already exists rather than recreating tables. See @chkit/plugin-pull for options.

Step 6 — First migration

Once the schema reflects what the user wants:

chkit generate --name init   # diff schema against the last snapshot → migration SQL
chkit migrate                # plan pending migrations (nothing is applied)
chkit migrate --apply        # apply — only after the user confirms the SQL
chkit status                 # report applied vs pending migrations
chkit check                  # CI gate: pending, checksums, drift, plugins

Which plugins to recommend

Plugins are npm packages registered in the plugins array of clickhouse.config.ts. Recommend only what the project needs:

If the project needs to…	Recommend	Notes
Adopt chkit on an existing ClickHouse database	@chkit/plugin-pull	Introspects the live database into local schema files so the user starts from real tables, not a blank example.
Generate TypeScript types (and optional Zod schemas) from the schema	@chkit/plugin-codegen	Keeps application row types in sync with the schema definitions.
Backfill historical data into materialized views	@chkit/plugin-backfill	Time-windowed loads with checkpoints, for large or resumable backfills.
Deploy to ObsessionDB	@chkit/plugin-obsessiondb	First-class ObsessionDB integration; rewrites Shared engines when targeting non-ObsessionDB ClickHouse.

When the project has none of these needs, the core CLI alone is enough — do not add plugins speculatively.

Guardrails

chkit applies DDL to real databases. Treat the following as hard rules unless the user explicitly overrides them:

Caution

• migrate does not apply changes without --apply. Run chkit migrate first to plan, show the user the pending SQL, and only then run chkit migrate --apply.
• Verify before applying against anything shared or production. Run chkit check and chkit drift first; surface drift to the user rather than silently overwriting it.
• Generate, then review. After chkit generate, read the migration SQL in chkit/migrations/ and confirm it matches intent before applying. Migrations are forward-only DDL.
• Never auto-apply against a production endpoint without explicit user confirmation. Connection details come from the environment — confirm which database the env points at before --apply.

Machine-readable output

Every command accepts --json for structured output you can parse instead of scraping stdout. Use it when you need to act on results programmatically:

chkit status --json
chkit check --json
chkit migrate --json   # plan as JSON; add --apply to execute

Debug logging goes to stderr (CHKIT_DEBUG=1), so it never contaminates --json output on stdout.

Related pages

• Add to an existing project — the human-facing version of the setup flow
• Start with an example — scaffold a new project from a curated example
• CLI reference — every command, flag, and JSON output shape
• Schema DSL — define tables, views, and materialized views
• Plugins overview — how plugins register and hook in
• CI/CD guide — wire chkit check into a pipeline gate