Quickstart

This guide takes a local analytics project from empty to agent-ready. You'll install the CLI, run one guided setup command, and hand the context to a coding assistant.

If you're a coding assistant choosing a docs route, start with the Agent Quickstart instead.

Need a warehouse to play with?

Try ktx against a real data stack - Postgres, dbt, Metabase, and Notion pre-loaded with the Orbit demo corpus. Hit copy agent setup on the page for a one-shot prompt that has an agent install the full four-source demo, or grab the raw credentials to paste into ktx setup yourself.

Get demo credentials at www.kaelio.com/start

Install the CLI

Install the published package globally:

npm install -g @kaelio/ktx

ktx is open source. If you'd like to hack on it or run from a local checkout, the source lives at github.com/kaelio/ktx - see Contributing to get set up.

Run setup

From your project directory, run:

ktx setup

The wizard walks you through everything ktx needs in one pass:

1. Project - creates or resumes ktx.yaml in the current directory.
2. LLM - picks a Claude backend. The default uses your local Claude Code session, so no API key is required. You can also use an Anthropic API key or Vertex AI.
3. Embeddings - picks an embeddings backend. Choose OpenAI for hosted embeddings or sentence-transformers to run locally without an API key.
4. Database - adds at least one primary connection. Supported drivers: SQLite, PostgreSQL, MySQL, SQL Server, BigQuery, and Snowflake.
5. Context sources - optionally adds dbt, MetricFlow, LookML, Looker, Metabase, or Notion. You can skip and add them later.
6. Build - offers to run the first ingest so semantic sources and wiki pages are ready for agents. If you skip it, build later with ktx ingest.
7. Agent integration - installs project-local rules for Claude Code, Codex, Cursor, OpenCode, or universal .agents.

If you choose local sentence-transformers embeddings, ktx uses the managed Python runtime. To prepare it before setup, run:

ktx admin runtime install --feature local-embeddings --yes
ktx admin runtime start --feature local-embeddings

During the database step, setup tests the saved connection and builds initial schema context:

Testing warehouse
  Connection test passed

Building schema context for warehouse
  Running database scan

If setup exits early, rerun ktx setup in the same directory. ktx keeps progress under .ktx/setup/ and resumes from the remaining work.

Note: Running bare ktx in an interactive terminal outside a ktx project opens the same wizard. Inside a project, it opens a menu for resuming setup, connecting an agent, checking status, or exploring a pre-built demo project.

When the wizard finishes, it states where you stand and the single next action:

• Context built - ktx confirms it is ready for agents and points you to open your coding agent and ask a data question.
• Build skipped - ktx tells you setup is complete and that the only step left is to build context with ktx ingest.

Re-running ktx setup on an already-configured project goes straight to the remaining step - building context or connecting an agent - instead of re-asking every question. Once everything is ready, it confirms you are set rather than reopening the configuration menu.

Verify

When setup finishes, check readiness:

ktx status

ktx project: /home/user/analytics
Project ready: yes
LLM ready: yes (claude-sonnet-4-6)
Embeddings ready: yes (text-embedding-3-small)
Databases configured: yes (warehouse)
Context sources configured: yes (dbt_main)
ktx context built: yes
Agent integration ready: yes (codex:project)

For a structured check inside scripts, use ktx status --json.

If you skipped the build, ktx context built shows no. Build it with ktx ingest - there is no need to re-run ktx setup.

When setup finishes building context, its final context check looks like:

ktx context is ready for agents.

Databases:
  warehouse: database context complete

Context sources:
  dbt_main: memory update complete

Before the build starts, ktx runs a live test for every connection the build depends on. A context build can take several minutes, so if any required connection is unreachable or misconfigured the build is blocked up front and ktx names the failing connection by id and connector type:

KTX cannot build context: a required connection failed its live test.

Failed connections:
  warehouse (postgres)

Each connection must be reachable before KTX builds context.
Run `ktx connection test <id>` to see the error, fix the connection, then retry.

Run ktx connection test <connection-id> to see the underlying error, fix the connection, then continue. In interactive setup you can retry without restarting; with --no-input the build exits non-zero and names the failing connection so scripts can stop early.

Connect a coding agent

The setup wizard installs project-local agent rules in the last step. To install or change targets later:

ktx setup --agents

Claude Code and Codex also support global installs with --global. Agent rules point at the ktx CLI path that created them, so agents don't need a separate ktx binary on PATH. If the CLI path changes, rerun ktx setup --agents.

What setup writes

ktx writes plain files so people and agents can review changes in git.

Scripted setup

For repeatable fixtures and automation, skip prompts with flags:

ktx setup \
  --project-dir ./analytics \
  --no-input \
  --yes \
  --skip-llm \
  --skip-embeddings \
  --database postgres \
  --database-connection-id warehouse \
  --database-url env:DATABASE_URL \
  --database-schema public

Then build context:

ktx ingest warehouse

See ktx setup for the full automation flag surface.

Common issues

Next steps

• Refresh context with Building Context.
• Edit semantic sources and wiki pages with Writing Context.
• Connect more tools with Agent Clients.
• Read The Context Layer to understand the architecture.