---
title: Getting Started
description: Get chkit running in your project — start from a curated example or add it to an existing repo.
sidebar:
  order: 0
  label: Overview
---

import { LinkCard, CardGrid } from '@astrojs/starlight/components';
import CopyPromptButton from '../../../components/CopyPromptButton.astro';

chkit is a ClickHouse schema and migration toolkit for TypeScript projects. Pick the path that matches what you're working on.

## Let an agent set it up

If you work in an AI coding agent (Claude Code, Cursor, Codex, and others), let it do the setup. Copy this prompt and paste it into your agent — it fetches chkit's [agent instructions](/ai-agents/) and walks you through install, config, plugins, and your first migration.

<CopyPromptButton prompt="Set up chkit (ClickHouse schema management) in this repo. First fetch https://chkit.obsessiondb.com/ai-agents.md and follow the instructions there: 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." />

Prefer to do it yourself? Pick a path below.

<CardGrid>
  <LinkCard
    title="Start with an example"
    href="/getting-started/with-an-example/"
    description="Scaffold a working chkit project from a curated example with create-chkit. Best for a first look or as a reference setup to copy from."
  />
  <LinkCard
    title="Add to an existing project"
    href="/getting-started/add-to-existing-project/"
    description="Install chkit alongside your application code, generate your first migration, and apply it. Best if you already have a TypeScript project."
  />
</CardGrid>

## Prerequisites

Both paths need the same baseline:

- Node.js 20+ or Bun 1.3.5+
- A ClickHouse endpoint (`CLICKHOUSE_URL`, optionally `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`) — ClickHouse 24.x or newer (see [compatibility](/guides/clickhouse-compatibility/))

## Where to next

Once either path is working:

- [The migration workflow](/guides/migration-workflow/) — how generate, snapshot, and migrate fit together, and what to commit
- [CLI reference](/cli/overview/) — every command, flag, and expected output
- [Configuration](/configuration/overview/) — wire up `clickhouse.config.ts`
- [Schema DSL](/schema/dsl-reference/) — define tables, views, and materialized views
- [Troubleshooting](/guides/troubleshooting/) — fixes for common errors if a command fails