Skip to content
Back to search

ktx

SkillWorks with CodexGitHub

ktx is an executable context layer for data and analytics agents πŸ™ Allow Claude Code, Codex, or other AI agents to query analytical databases accurately and with full context of your company

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Kaelio/ktx with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Kaelio/ktx'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kaelio-ktx/badge.svg)](/listings/kaelio-ktx)

HTML

<a href="/listings/kaelio-ktx"><img src="/api/listings/kaelio-ktx/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install -g @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` 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 from > your project directory: > > ```text > Run npx skills add Kaelio/ktx --skill ktx and use the ktx skill to install > and configure ktx in this project. > ```

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 285 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center">
  2. <img src="assets/ktx-lockup.svg" alt="ktx" width="500" />
  3. </h1>
  4. <h1 align="center">
  5. The context layer for data agents
  6. </h1>
  7. <p align="center">
  8. <a href="https://www.npmjs.com/package/@kaelio/ktx"><img src="https://img.shields.io/npm/v/@kaelio/ktx?style=flat-square&color=f97316" alt="npm version" /></a>
  9. <a href="https://codecov.io/gh/Kaelio/ktx"><img src="https://codecov.io/gh/Kaelio/ktx/graph/badge.svg?branch=main" alt="Codecov" /></a>
  10. <a href="https://github.com/Kaelio/ktx/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/Kaelio/ktx/ci.yml?branch=main&label=tests&style=flat-square" alt="Tests" /></a>
  11. <a href="https://docs.kaelio.com/ktx/docs/"><img src="https://img.shields.io/badge/docs-ktx-22c55e?style=flat-square" alt="Documentation" /></a>
  12. <a href="https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ"><img src="https://img.shields.io/badge/slack-join%20community-4A154B?style=flat-square&logo=slack&logoColor=white" alt="Join the ktx Slack community" /></a>
  13. <a href="https://github.com/Kaelio/ktx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square" alt="License" /></a>
  14. <a href="https://www.ycombinator.com/companies/kaelio"><img src="https://img.shields.io/badge/Y%20Combinator-P25-orange?style=flat-square" alt="Y Combinator P25" /></a>
  15. </p>
  16. <p align="center">
  17. <a href="https://docs.kaelio.com/ktx/docs/getting-started/quickstart"><b>Quickstart</b></a> Β·
  18. <a href="https://docs.kaelio.com/ktx/docs/cli-reference/ktx"><b>CLI Reference</b></a> Β·
  19. <a href="https://docs.kaelio.com/ktx/docs/community/ai-resources"><b>Agent Setup</b></a> Β·
  20. <a href="https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ"><b>Slack</b></a>
  21. </p>
  22. <p align="center">
  23. <sub>Built and maintained by <a href="https://www.kaelio.com"><b>Kaelio</b></a></sub>
  24. </p>
  25. ---
  26. **ktx** is a self-improving context layer that teaches agents how to query your
  27. warehouse accurately - from approved metric definitions, joinable columns, and
  28. business knowledge it builds and maintains for you.
  29. > [!NOTE]
  30. > Run **ktx** with your own LLM API keys or a local agent sign-in β€” a
  31. > **Claude Pro/Max** subscription through Claude Code, or your local Codex
  32. > authentication. No extra usage billing from **ktx**.
  33. <p align="center">
  34. <a href="https://youtu.be/5V4TuzYVlrA">
  35. <img src="assets/launch-video-thumb.png" alt="Watch the ktx launch video (1:56)" width="820" />
  36. </a>
  37. </p>
  38. <p align="center">
  39. <img src="docs-site/public/images/ingestion-flow.png" alt="Ingestion: ktx ingests databases, BI tools, modeling code, and docs through its context engine (source connectors, context builder, reconciliation, validation) into wiki Markdown and semantic-layer YAML" width="900" />
  40. </p>
  41. <p align="center">
  42. <img src="docs-site/public/images/mcp-runtime-flow.png" alt="Serving: an agent queries ktx through MCP, which searches the wiki and semantic layer, returns approved metrics, and compiles them into read-only SQL run against the warehouse" width="900" />
  43. </p>
  44. ## Why ktx
  45. General-purpose agents struggle on data tasks. They re-explore your warehouse
  46. on every question, invent their own metric logic, and return numbers that
  47. don't match approved definitions.
  48. Traditional semantic layers don't fix this. They demand constant manual
  49. upkeep and don't absorb the rest of your company's knowledge.
  50. **ktx** does both, automatically:
  51. - **Learns from company knowledge.** Ingests wiki content, organizes it,
  52. removes duplicates, and flags contradictions for human review.
  53. - **Maps the data stack.** Samples tables, captures metadata and usage
  54. patterns, detects joinable columns, and annotates sources so agents write
  55. better queries.
  56. - **Builds a semantic layer.** Combines raw tables and high-level metrics
  57. through a join graph that automatically resolves chasm and fan traps, so
  58. agents fetch metrics declaratively instead of rewriting canonical SQL each
  59. time.
  60. - **Serves agents at execution.** Exposes CLI and MCP tools with combined
  61. full-text and semantic search across wiki and semantic-layer entities.
  62. ## How ktx compares
  63. | | General-purpose agent | Traditional semantic layer | **ktx** |
  64. | --- | :---: | :---: | :---: |
  65. | Builds warehouse context automatically | β€” | β€” | βœ“ |
  66. | Detects joinable columns + resolves fan/chasm traps | β€” | Manual | βœ“ |
  67. | Approved, reusable metric definitions | β€” | βœ“ | βœ“ |
  68. | Absorbs wiki / Notion / team knowledge | β€” | β€” | βœ“ |
  69. | Flags contradictions across sources | β€” | β€” | βœ“ |
  70. | Ships CLI + MCP for agent execution | Partial | β€” | βœ“ |
  71. | Read-only by design | n/a | n/a | βœ“ |
  72. ## Who is ktx for
  73. **Use ktx if you:**
  74. - Want agents like Claude Code, Codex, Cursor, or OpenCode to query your
  75. warehouse with approved metric definitions
  76. - Have business knowledge scattered across dbt, Looker, Metabase, Notion, and
  77. team wikis
  78. - Need agents to reuse canonical SQL instead of inventing it on every prompt
  79. **Skip ktx if you:**
  80. - You don't have a SQL warehouse - **ktx** sits on top of one
  81. - You only need one ad-hoc query - `psql` or a notebook will do
  82. Works with PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server,
  83. SQLite, DuckDB, Amazon Athena, and MongoDB. Integrates with dbt, MetricFlow,
  84. LookML, Looker, Metabase, Sigma, Notion, and Google Drive.
  85. ## Quick Start
  86. ```bash
  87. npm install -g @kaelio/ktx
  88. ktx setup
  89. ktx status
  90. ```
  91. `ktx setup` creates or resumes a local **ktx** project, configures providers
  92. and connections, builds context, and installs agent integration.
  93. Example `ktx status` after setup:
  94. ```text
  95. ktx project: /home/user/analytics
  96. Project ready: yes
  97. LLM ready: yes (claude-sonnet-4-6)
  98. Embeddings ready: yes (text-embedding-3-small)
  99. Databases configured: yes (warehouse)
  100. Context sources configured: yes (dbt_main)
  101. ktx context built: yes
  102. Agent integration ready: yes (codex:project)
  103. ```
  104. > [!TIP]
  105. > Already using an agent? Ask Claude Code, Codex, Cursor, or OpenCode from
  106. > your project directory:
  107. >
  108. > ```text
  109. > Run npx skills add Kaelio/ktx --skill ktx and use the ktx skill to install
  110. > and configure ktx in this project.
  111. > ```
  112. > [!IMPORTANT]
  113. > If `ktx status` prints `ktx mcp start --project-dir ...`, run it before
  114. > opening your agent client.
  115. ## Upgrading
  116. Re-run the global install with the `@latest` tag:
  117. ```bash
  118. npm install -g @kaelio/ktx@latest
  119. ```
  120. ## First commands
  121. | Command | Purpose |
  122. | --- | --- |
  123. | `ktx setup` | Create, resume, or update a **ktx** project |
  124. | `ktx status` | Check project readiness |
  125. | `ktx ingest` | Build context for every configured connection |
  126. | `ktx sl "revenue"` | Search semantic sources |
  127. | `ktx wiki "refund policy"` | Search local wiki pages |
  128. | `ktx mcp start` | Start the MCP server for agent clients |
  129. See the [CLI Reference](https://docs.kaelio.com/ktx/docs/cli-reference/ktx)
  130. for every command, flag, and option.
  131. ## Project Layout
  132. ```text
  133. my-project/
  134. β”œβ”€β”€ ktx.yaml # Project configuration
  135. β”œβ”€β”€ semantic-layer/<connection-id>/ # YAML semantic sources
  136. β”œβ”€β”€ wiki/global/ # Shared business context
  137. β”œβ”€β”€ wiki/user/<user-id>/ # User-scoped notes
  138. β”œβ”€β”€ raw-sources/<connection-id>/ # Ingest artifacts and reports
  139. └── .ktx/ # Local state and secrets, git-ignored
  140. ```
  141. Commit `ktx.yaml`, `semantic-layer/`, and `wiki/`. Keep `.ktx/` local.
  142. Project resolution defaults to `KTX_PROJECT_DIR`, then the nearest `ktx.yaml`,
  143. then the current directory. Pass `--project-dir <path>` when scripting.
  144. ## FAQ
  145. - **Does ktx send my schema or query results to a hosted service?**
  146. No. **ktx** runs locally. The only data leaving your machine is what you
  147. send to the LLM provider you configured.
  148. - **Which LLM backends are supported?**
  149. Anthropic API, Google Vertex AI, AI Gateway, the local Claude Code session
  150. through the Claude Agent SDK, and your local Codex authentication through the
  151. Codex SDK. See
  152. [LLM configuration](https://docs.kaelio.com/ktx/docs/guides/llm-configuration).
  153. - **How is ktx different from a dbt or MetricFlow semantic layer?**
  154. **ktx** *ingests* those layers and combines them with raw-table
  155. introspection and wiki content. Agents get one searchable surface instead
  156. of three disconnected ones - and **ktx** flags contradictions across
  157. sources.
  158. - **Does ktx need a running server?**
  159. There is no hosted service. The local MCP daemon runs on demand via
  160. `ktx mcp start` when an agent client needs it.
  161. - **Is my warehouse safe?**
  162. Yes. Connections are read-only - **ktx** never writes to your database.
  163. ## Docs
  164. - [Quickstart](https://docs.kaelio.com/ktx/docs/getting-started/quickstart)
  165. - [The Context Layer](https://docs.kaelio.com/ktx/docs/concepts/the-context-layer)
  166. - [Building Context](https://docs.kaelio.com/ktx/docs/guides/building-context)
  167. - [CLI Reference](https://docs.kaelio.com/ktx/docs/cli-reference/ktx)
  168. - [AI Resources](https://docs.kaelio.com/ktx/docs/community/ai-resources)
  169. - [Community & Support](https://docs.kaelio.com/ktx/docs/community/support)
  170. ## Community
  171. - **[Slack](https://join.slack.com/t/ktxcommunity/shared_invite/zt-3y9b44m1x-LVyNNJD5nwaZHq4XS29LMQ)** β€” ask questions, share what you're building, and chat with maintainers.
  172. - **[GitHub Issues](https://github.com/Kaelio/ktx/issues)** β€” report bugs and request features.
  173. - **[Contributing](https://docs.kaelio.com/ktx/docs/community/contributing)** β€” set up the repo, run tests, and open a PR.
  174. ## Development
  175. ```bash
  176. git clone https://github.com/kaelio/ktx.git
  177. cd ktx
  178. pnpm install
  179. uv sync --all-groups
  180. pnpm run build
  181. pnpm run check
  182. ```
  183. **ktx** is a pnpm + uv workspace:
  184. | Path | Purpose |
  185. | --- | --- |
  186. | `packages/cli` | TypeScript CLI and published npm package source |
  187. | `packages/cli/src/context` | Core context engine |
  188. | `packages/cli/src/llm` | LLM and embedding providers |
  189. | `packages/cli/src/connectors` | Database scan connectors |
  190. | `python/ktx-sl` | Semantic-layer query planning |
  191. | `python/ktx-daemon` | Portable compute service |
  192. Local development CLI:
  193. ```bash
  194. pnpm run setup:dev
  195. pnpm run link:dev
  196. ktx-dev --help
  197. ```
  198. Useful checks:
  199. ```bash
  200. pnpm run type-check
  201. pnpm run test
  202. pnpm run dead-code
  203. uv run pytest -q
  204. ```
  205. ## Telemetry
  206. **ktx** collects privacy-conscious usage telemetry to understand installs and
  207. improve setup, command reliability, and data-agent workflows. Catalog telemetry
  208. events do not record file paths, hostnames, SQL, schema names, table names,
  209. column names, error messages, raw environment values, or argv. Error reports use
  210. PostHog Error Tracking and can include stack frames and raw error messages,
  211. which may contain local file paths or the local username in those paths.
  212. **ktx** redacts secrets, credentials, database URLs, auth headers, argv, raw
  213. environment values, SQL text, row data, and user-typed prompt or MCP argument
  214. text from the explicit `$exception` payload. See
  215. [Telemetry](https://docs.kaelio.com/ktx/docs/community/telemetry) for the event
  216. catalog and opt-out options.
  217. ## License
  218. **ktx** is licensed under the Apache License, Version 2.0. See `LICENSE`.
  219. ## Star History
  220. <p align="center">
  221. <a href="https://star-history.com/#Kaelio/ktx&Date">
  222. <img src="assets/star-history.svg" alt="ktx Star History Chart" width="700" />
  223. </a>
  224. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.