ktx

The context layer for data agents

Quickstart · CLI Reference · Agent Setup · Slack

ktx is a self-improving context layer that teaches agents how to query yourwarehouse accurately - from approved metric definitions, joinable columns, andbusiness knowledge it builds and maintains for you.

[!NOTE]Run ktx with your own LLM API keys or a Claude Pro/Max subscription.No extra usage billing from ktx.

Why ktx

General-purpose agents struggle on data tasks. They re-explore your warehouseon every question, invent their own metric logic, and return numbers thatdon't match approved definitions.

Traditional semantic layers don't fix this. They demand constant manualupkeep and don't absorb the rest of your company's knowledge.

ktx does both, automatically:

• Learns from company knowledge. Ingests wiki content, organizes it,removes duplicates, and flags contradictions for human review.
• Maps the data stack. Samples tables, captures metadata and usagepatterns, detects joinable columns, and annotates sources so agents writebetter queries.
• Builds a semantic layer. Combines raw tables and high-level metricsthrough a join graph that automatically resolves chasm and fan traps, soagents fetch metrics declaratively instead of rewriting canonical SQL eachtime.
• Serves agents at execution. Exposes CLI and MCP tools with combinedfull-text and semantic search across wiki and semantic-layer entities.

How ktx compares

Who is ktx for

Use ktx if you:

• Want agents like Claude Code, Codex, Cursor, or OpenCode to query yourwarehouse with approved metric definitions
• Have business knowledge scattered across dbt, Looker, Metabase, Notion, andteam wikis
• Need agents to reuse canonical SQL instead of inventing it on every prompt

Skip ktx if you:

• You don't have a SQL warehouse - ktx sits on top of one
• You only need one ad-hoc query - psql or a notebook will do

Works with PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, andSQLite. Integrates with dbt, MetricFlow, LookML, Looker, Metabase, and Notion.

Quick Start

npm install -g @kaelio/ktx
ktx setup
ktx status

ktx setup creates or resumes a local ktx project, configures providersand connections, builds context, and installs agent integration.

Example ktx status after setup:

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)

[!TIP]Already using an agent? Ask Claude Code, Codex, Cursor, or OpenCode fromyour project directory:

Follow instructions from
https://docs.kaelio.com/ktx/docs/agents-setup.md
to install and configure ktx

[!IMPORTANT]If ktx status prints ktx mcp start --project-dir ..., run it beforeopening your agent client.

First commands

See the CLI Referencefor every command, flag, and option.

Project Layout

my-project/
├── ktx.yaml                         # Project configuration
├── semantic-layer/<connection-id>/  # YAML semantic sources
├── wiki/global/                     # Shared business context
├── wiki/user/<user-id>/             # User-scoped notes
├── raw-sources/<connection-id>/     # Ingest artifacts and reports
└── .ktx/                            # Local state and secrets, git-ignored

Commit ktx.yaml, semantic-layer/, and wiki/. Keep .ktx/ local.

Project resolution defaults to KTX_PROJECT_DIR, then the nearest ktx.yaml,then the current directory. Pass --project-dir <path> when scripting.

FAQ

• Does ktx send my schema or query results to a hosted service?No. ktx runs locally. The only data leaving your machine is what yousend to the LLM provider you configured.
• Which LLM backends are supported?Anthropic API, Google Vertex AI, AI Gateway, and the local Claude Codesession through the Claude Agent SDK. SeeLLM configuration.
• How is ktx different from a dbt or MetricFlow semantic layer?ktx ingests those layers and combines them with raw-tableintrospection and wiki content. Agents get one searchable surface insteadof three disconnected ones - and ktx flags contradictions acrosssources.
• Does ktx need a running server?There is no hosted service. The local MCP daemon runs on demand viaktx mcp start when an agent client needs it.
• Is my warehouse safe?Yes. Connections are read-only - ktx never writes to your database.

Docs

• Quickstart
• The Context Layer
• Building Context
• CLI Reference
• Agent Quickstart
• Community & Support

Community

• Slack — ask questions, share what you're building, and chat with maintainers.
• GitHub Issues — report bugs and request features.
• Contributing — set up the repo, run tests, and open a PR.

Development

git clone https://github.com/kaelio/ktx.git
cd ktx
pnpm install
uv sync --all-groups
pnpm run build
pnpm run check

ktx is a pnpm + uv workspace:

Local development CLI:

pnpm run setup:dev
pnpm run link:dev
ktx-dev --help

Useful checks:

pnpm run type-check
pnpm run test
pnpm run dead-code
uv run pytest -q

Telemetry

ktx collects anonymous usage telemetry from interactive CLI runs toimprove setup, command reliability, and data-agent workflows. No file paths,hostnames, SQL, schema names, error messages, or argv are recorded. SeeTelemetry for theevent catalog and opt-out options.

License

ktx is licensed under the Apache License, Version 2.0. See LICENSE.

Star History