Skip to content

Schema Management for AI Agents

Use these instructions to set up chkit in a user’s project and prepare the first schema migration.

To delegate setup, paste the prompt below into your coding agent.

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:
use choices I already supplied, ask only missing setup questions, install the agent skill, scaffold the config,
recommend any plugins this project needs, and walk me through the first
migration. Review SQL before applying; ask for apply authorization if I haven't provided it.

For an explicitly authorized disposable development target, add:

I authorize the reviewed migrations needed for this task on the supplied
local development database. Proceed through apply and verification without
asking for repeat confirmation. If credentials are missing, prepare everything
possible offline and ask for the exact missing connection values. Do not invent
connection defaults or provision an account.

Append .md to a documentation URL to read Markdown, such as /ai-agents.md. Find page URLs in /llms.txt.

Use chkit to define ClickHouse schemas, generate migration SQL, deploy reviewed changes, and check the live database for drift. Default to TypeScript unless the user explicitly requests the beta Python implementation.

Run chkit through shell commands. Install the schema agent skill for command and authoring guidance.

Treat choices already supplied in the task as answered. Ask only for genuinely missing information, and continue independent offline work while waiting. Use these choices to select the commands.

  1. New project or existing project?

    • New / empty directory → initialize a schema project with chkit init in the chosen language (Step 3a).
    • Existing TypeScript project → install chkit and run chkit init in place (Step 3b).
    • Existing Python project → pip install chkit-py, then chkit init in place (config and schema are written as .py files; plugins ship inside chkit-py).
  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? Use the CLI’s four connection options:

    • Claim a free ObsessionDB dev instance: requires the user’s email and a one-time code from their inbox.
    • 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.

Missing credentials: prepare offline, then ask

Section titled “Missing credentials: prepare offline, then ask”

For an existing ClickHouse target, request its HTTP(S) URL including port, username, password (or explicitly blank password), and database. Do not treat localhost, default, or an absent password as verified values. Configure direct connected commands to fail clearly when a required value is missing; generate can run without a connection/executor.

Prepare schema definitions offline. Generate the initial SQL once the user has chosen the database namespace; if that name is unknown, request it and leave generation pending instead of inventing a default. If a previous attempt generated placeholder SQL, retarget definitions and regenerate only never-applied initial artifacts; never rewrite an applied migration or its history. Keep credentials out of Git and handoffs. Bun loads a root .env; npm/Node requires explicit loading such as node --env-file=.env ./node_modules/chkit/dist/bin/chkit.js check --strict --json.

The CLI scaffold requires an explicit database namespace before generation and explicit credentials before a direct connection. Preserve supplied target metadata during offline generation; removing the connection configuration can change cluster or engine-setting behavior. A generated config is not proof a database connection works.

Install the schema skill with the external skills CLI (requires Node.js/npm):

Terminal window
npx skills add obsessiondb/chkit --skill chkit

The skill installs into the project’s agent directory (for example .claude/skills/chkit/ or .agents/skills/chkit/). After installing the TypeScript CLI, chkit skills add obsessiondb/chkit --skill chkit runs the same installer. On an interactive TypeScript chkit init, chkit also detects the active agent and offers to install the skill automatically.

For TypeScript, initialize an empty folder:

Terminal window
mkdir my-chkit-app
cd my-chkit-app
bunx chkit@latest init

In an empty directory, init writes the config, starter schema, and package.json, then installs the required chkit packages.

For Python:

Terminal window
mkdir my-chkit-app
cd my-chkit-app
pip install chkit-py
chkit init

Follow the first-schema tutorial for the complete workflow. If the user wants a curated TypeScript project with two tables and an existing migration, use the optional schema example.

Both paths offer the connect flow in Step 4. Choose configure-later while credentials are missing; do not claim an account on the user’s behalf unless requested. Drive init non-interactively with --connect <choice> (and --email for the claim path), or --yes to scaffold only.

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

Terminal window
bun add -d chkit @chkit/core
chkit init

chkit init writes clickhouse.config.ts and src/db/schema/example.ts, and installs missing chkit packages. Running it again preserves existing files.

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

Edit src/db/schema/example.ts to match the requested table before running generate. For an existing database, follow Step 5 to import its schema.

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:

ChoiceFlagWhat 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 accountchkit obsessiondb login
Existing ClickHouse instance--connect clickhouseSet CLICKHOUSE_URL (and CLICKHOUSE_USER / CLICKHOUSE_PASSWORD / CLICKHOUSE_DB)
Configure later--connect later or --yesNothing: scaffold only

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

Terminal window
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

Keep obsessiondb() registered in the project config (clickhouse.config.ts or clickhouse.config.py) for connected paths. Claiming and account login use its remote executor. For non-ObsessionDB ClickHouse targets, the plugin strips the storage_policy table setting, since ObsessionDB’s storage policies don’t exist there.

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

Section titled “Step 5: Pull existing tables (only if the user has a populated database)”

If the user answered yes to question 2, import the existing schema. In TypeScript, add the plugin, register it, and introspect:

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

In Python, chkit pull is built in and needs no plugin registration. Replace or remove the scaffolded starter schema so the configured schema files contain the intended database objects.

Pull writes definitions, not a migration baseline or applied history. Follow the complete existing-database adoption guide to review an idempotent baseline, handle scoped database permissions, apply through the normal journal, verify data/views/live drift, and make a separate ALTER migration. IF NOT EXISTS does not prove the existing object matches the definition. Never manufacture history by editing the journal or rebuilding a snapshot. See schema introspection for options.

Once the schema reflects what the user wants:

Terminal window
chkit generate --name init # diff schema against the last snapshot → migration SQL
chkit migrate --json # plan pending migrations without applying
chkit migrate --apply # apply reviewed SQL with user authorization
chkit status # report applied vs pending migrations
chkit check # CI gate: pending, checksums, drift, plugins

chkit check does not fail on a change to a property that chkit drift does not compare.

In TypeScript, plugins are npm packages registered in the plugins array of clickhouse.config.ts; in Python they ship inside chkit-py and are registered in clickhouse.config.py. Recommend only what the project needs:

If the project needs to…RecommendNotes
Adopt chkit on an existing ClickHouse database@chkit/plugin-pullIntrospects the live database into local schema files so the user starts from real tables, not a blank example.
Generate typed row models: TypeScript types (and optional Zod schemas), or Pydantic models in Python: from the schema@chkit/plugin-codegenKeeps application row types in sync with the schema definitions.
Backfill historical data into materialized views@chkit/plugin-backfillPartition/sort-key replay with checkpoints; inspect plan predicates and retry/engine semantics.
Deploy to ObsessionDB@chkit/plugin-obsessiondbObsessionDB connection and service selection; strips the storage_policy table setting when targeting non-ObsessionDB ClickHouse.

Install plugins for the project’s stated requirements.

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

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

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

Read debug logging from stderr (CHKIT_DEBUG=1) and --json output from stdout.