The context layer for analytics agents

---

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.

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.

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>	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 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 --target codex

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

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.