The context layer for analytics agents

by Kaelio

---

KTX turns warehouse metadata, semantic definitions, and business knowledge into reviewable project files that agents can use to plan, query, and update analytics work.

Use KTX when you want agents to:

• Generate SQL from approved measures and joins
• Repair semantic definitions through reviewable diffs
• Explain metric provenance with warehouse evidence
• Work alongside dbt, MetricFlow, LookML, Looker, Metabase, and Notion

Supports PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, and SQLite.

Agent Setup

Ask an agent such as Claude Code, Codex, Cursor, or OpenCode to install and configure KTX from your project directory:

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

Quick Start

pnpm add --global @kaelio/ktx
ktx setup
ktx status

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

Example ktx status output 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)

Common Commands

Command	Purpose
ktx setup	Create, resume, or update a KTX project
ktx status	Check project readiness
ktx connection list	List configured connections
ktx connection test <id>	Test one connection
ktx ingest <id>	Build context for one connection
ktx ingest --all	Build context for every configured connection
ktx ingest text <file> --connection-id <connectionId>	Capture free-form notes into memory
ktx sl list	List semantic-layer sources
ktx sl search "revenue"	Search semantic-layer sources
ktx sl validate <source> --connection-id <id>	Validate a semantic source
ktx sl query --measure <measure> --format sql	Compile semantic-layer SQL
ktx sql --connection <id> "select 1"	Execute read-only SQL
ktx wiki search "revenue definition"	Search local wiki context
ktx mcp start	Start the local MCP server for agent clients

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

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.

Agent Usage

Setup can install KTX instructions for Claude Code, Codex, Cursor, OpenCode, and universal .agents clients:

ktx setup --agents

Use --target <target> when you want to install or repair one specific integration.

Agent-facing workflows typically start with:

ktx sl search "revenue" --json
ktx wiki search "refund policy" --json
ktx sl query --connection-id warehouse --measure orders.revenue --format sql

During agent setup, choose Ask data questions with KTX MCP for client agents. Choose Ask data questions + manage KTX with CLI commands only when a developer or operator agent also needs pinned ktx admin commands.

After setup, KTX prints Required before using agents. Complete those steps before opening the configured agent. If it shows ktx mcp start --project-dir ..., run that command before using Claude Code, Codex, Cursor, OpenCode, or generic MCP clients. The same output also prints the matching ktx mcp stop command for when you want to stop MCP later. Claude Desktop uses its own launcher for MCP and prints separate skill upload steps.

The analytics skill teaches client agents the MCP workflow: discover data, prefer semantic-layer measures, inspect entity details before raw SQL, and capture durable learnings. Admin CLI skills call ktx commands directly through a skill file installed in your agent's config:

ktx sl query --measure orders.revenue --dimension orders.status --format sql
ktx wiki search "revenue definition"
ktx sl validate orders

Supported client agents: Claude Code, Claude Desktop, Codex, Cursor, OpenCode, and clients that can use the printed MCP endpoint or .agents admin skills. Claude Desktop setup registers a local ktx mcp stdio server in Claude Desktop's config and generates one uploadable ZIP per Claude Desktop skill under .ktx/agents/claude/. Restart Claude Desktop after setup, then upload each ZIP from Customize > Skills > + > Create skill > Upload a skill.

The release artifact manifest contains the public npm tarball and the bundled kaelio-ktx runtime wheel. The python/ktx-sl and python/ktx-daemon directories remain source packages for development, not public release artifacts.

Workspace packages

Package	Purpose
packages/cli	CLI entry point
packages/context	Core context engine
packages/llm	LLM and embedding providers
packages/connector-bigquery	BigQuery scan connector
packages/connector-clickhouse	ClickHouse scan connector
packages/connector-mysql	MySQL scan connector
packages/connector-postgres	Postgres scan connector
packages/connector-snowflake	Snowflake scan connector
packages/connector-sqlite	SQLite scan connector
packages/connector-sqlserver	SQL Server scan connector
python/ktx-sl	Semantic-layer query planning
python/ktx-daemon	Portable compute service

Development

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

Use the development CLI locally:

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

KTX is a pnpm + uv workspace:

• TypeScript packages live in packages/*
• CLI source lives in packages/cli
• Python runtime source lives in python/ktx-sl and python/ktx-daemon
• Public docs live in docs-site/content/docs

Useful checks:

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

Docs

• Quickstart
• CLI Reference
• Building Context
• Contributing

License

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