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.

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 - runs the first ingest so semantic sources and wiki pages are ready for agents.
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 fast database ingest

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.

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.

When setup builds deep context, its final context check looks like:

ktx context is ready for agents.

Databases:
  warehouse: deep context complete

Context sources:
  dbt_main: memory update complete

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 --fast

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.