465724a991
* docs: simplify readme * docs: add mcp cli reference * test: use docs base path * docs: enlarge readme tagline |
||
|---|---|---|
| .github/workflows | ||
| assets | ||
| docs/superpowers | ||
| docs-site | ||
| examples | ||
| packages | ||
| python | ||
| scripts | ||
| website | ||
| .gitignore | ||
| .pre-commit-config.yaml | ||
| AGENTS.md | ||
| biome.json | ||
| CLAUDE.md | ||
| conductor.json | ||
| GEMINI.md | ||
| knip.json | ||
| LICENSE | ||
| package.json | ||
| pnpm-lock.yaml | ||
| pnpm-workspace.yaml | ||
| pyproject.toml | ||
| README.md | ||
| release-policy.json | ||
| tsconfig.base.json | ||
| uv.lock | ||
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-slandpython/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
License
KTX is licensed under the Apache License, Version 2.0. See LICENSE.