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.
Copy this prompt
Section titled “Copy this prompt”Paste this into your coding agent to start setup:
Set up chkit (ClickHouse schema management) in this repo. First fetchhttps://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 firstmigration. 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 suppliedlocal development database. Proceed through apply and verification withoutasking for repeat confirmation. If credentials are missing, prepare everythingpossible offline and ask for the exact missing connection values. Do not inventconnection 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.
What chkit is
Section titled “What chkit is”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.
Step 1: Resolve the setup choices
Section titled “Step 1: Resolve the setup choices”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.
-
New project or existing project?
- New / empty directory → initialize a schema project with
chkit initin the chosen language (Step 3a). - Existing TypeScript project → install chkit and run
chkit initin place (Step 3b). - Existing Python project →
pip install chkit-py, thenchkit initin place (config and schema are written as.pyfiles; plugins ship inside chkit-py).
- New / empty directory → initialize a schema project with
-
Is there an existing ClickHouse database with tables to manage?
- Yes → add
@chkit/plugin-pulland 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.
- Yes → add
-
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.
Step 2: Install the agent skill
Section titled “Step 2: Install the agent skill”Install the schema skill with the external skills CLI (requires Node.js/npm):
npx skills add obsessiondb/chkit --skill chkitThe 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.
Step 3: Scaffold based on the answers
Section titled “Step 3: Scaffold based on the answers”3a. New project: chkit init
Section titled “3a. New project: chkit init”For TypeScript, initialize an empty folder:
mkdir my-chkit-appcd my-chkit-appbunx chkit@latest initIn an empty directory, init writes the config, starter schema, and package.json, then installs the required chkit packages.
For Python:
mkdir my-chkit-appcd my-chkit-apppip install chkit-pychkit initFollow 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.
3b. Existing project: chkit init
Section titled “3b. Existing project: chkit init”Install chkit as a dev dependency, then initialize in the current directory:
bun add -d chkit @chkit/corechkit initchkit 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.
Step 4: Connect a database
Section titled “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 instanceKeep 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:
bun add -d @chkit/plugin-pull# register pull() in the plugins array of clickhouse.config.tschkit pullIn 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.
Step 6: First migration
Section titled “Step 6: First migration”Once the schema reflects what the user wants:
chkit generate --name init # diff schema against the last snapshot → migration SQLchkit migrate --json # plan pending migrations without applyingchkit migrate --apply # apply reviewed SQL with user authorizationchkit status # report applied vs pending migrationschkit check # CI gate: pending, checksums, drift, pluginschkit check does not fail on a change to a property that chkit drift does not compare.
Which plugins to recommend
Section titled “Which plugins to recommend”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… | 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 typed row models: TypeScript types (and optional Zod schemas), or Pydantic models in Python: 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 | Partition/sort-key replay with checkpoints; inspect plan predicates and retry/engine semantics. |
| Deploy to ObsessionDB | @chkit/plugin-obsessiondb | ObsessionDB connection and service selection; strips the storage_policy table setting when targeting non-ObsessionDB ClickHouse. |
Install plugins for the project’s stated requirements.
Guardrails
Section titled “Guardrails”chkit applies DDL to real databases. Treat the following as hard rules unless the user explicitly overrides them:
Machine-readable output
Section titled “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 --jsonchkit check --jsonchkit migrate --json # plan as JSON; add --apply to executeRead debug logging from stderr (CHKIT_DEBUG=1) and --json output from stdout.
Related pages
Section titled “Related pages”- Add to an existing project: the human-facing version of the setup flow
- First-schema tutorial: initialize a project, create a table, and deploy a schema change
- Start with an example: optional TypeScript starter with two tables and a migration
- 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 checkinto a pipeline gate