mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
41e20c9ce7
The GitHub repo was renamed back from Kaelio/ktx-ai-data-agents-context to Kaelio/ktx, reverting the URL changes from #250 across package metadata, CI (codecov + star-history slugs), issue/security templates, the release runbook, and docs/install commands. Also removes the rename-resilience machinery #250 added: semantic-release now reads the repository URL straight from package.json (Kaelio/ktx) again, so the repositoryUrl() derivation in scripts/semantic-release-config.cjs, its tests, and the rename note in docs/release.md are no longer needed.
352 lines
13 KiB
Text
352 lines
13 KiB
Text
---
|
|
title: Quickstart
|
|
description: Install ktx, run setup, and connect your coding agent.
|
|
---
|
|
|
|
import { CopyButton } from "@/components/copy-button";
|
|
|
|
This guide takes a local analytics project from empty to agent-ready. You'll
|
|
install the CLI, run one guided setup command, and hand the context to a
|
|
coding assistant.
|
|
|
|
If you're a coding assistant choosing a docs route, start with the
|
|
[Agent Quickstart](/docs/ai-resources/agent-quickstart) instead.
|
|
|
|
<div
|
|
className="not-prose my-8 overflow-hidden rounded-2xl border"
|
|
style={{
|
|
borderColor: 'color-mix(in oklch, #ff8a4d 32%, transparent)',
|
|
background:
|
|
'linear-gradient(135deg, color-mix(in oklch, #ff8a4d 10%, transparent) 0%, color-mix(in oklch, #ff8a4d 3%, transparent) 100%)',
|
|
}}
|
|
>
|
|
<div className="flex flex-col gap-6 p-5 sm:p-7 md:flex-row md:items-center md:gap-10">
|
|
<div className="min-w-0 flex-1">
|
|
<div
|
|
className="text-[11px] font-black uppercase tracking-[0.16em]"
|
|
style={{ color: '#ff8a4d' }}
|
|
>
|
|
Need a warehouse to play with?
|
|
</div>
|
|
<div className="mt-2.5 text-base leading-relaxed text-fd-foreground">
|
|
Try **ktx** against a real data stack - Postgres, dbt, Metabase, and Notion
|
|
pre-loaded with the Orbit demo corpus. Hit **copy agent setup** on the page
|
|
for a one-shot prompt that has an agent install the full four-source demo,
|
|
or grab the raw credentials to paste into `ktx setup` yourself.
|
|
</div>
|
|
<a
|
|
href="https://www.kaelio.com/start"
|
|
className="group mt-5 inline-flex items-center gap-2 rounded-full px-4 py-2.5 text-sm font-semibold text-white no-underline shadow-[inset_0_1px_0_rgba(255,255,255,0.35),0_2px_4px_rgba(255,138,77,0.2),0_10px_24px_-8px_rgba(255,138,77,0.55)] transition-all duration-200 hover:-translate-y-0.5 hover:shadow-[inset_0_1px_0_rgba(255,255,255,0.4),0_3px_6px_rgba(255,138,77,0.28),0_16px_30px_-8px_rgba(255,138,77,0.65)]"
|
|
style={{
|
|
background: 'linear-gradient(180deg, #ff9d63 0%, #f97316 100%)',
|
|
}}
|
|
>
|
|
Get demo credentials at www.kaelio.com/start
|
|
<svg
|
|
width="14"
|
|
height="14"
|
|
viewBox="0 0 24 24"
|
|
fill="none"
|
|
stroke="currentColor"
|
|
strokeWidth="2.4"
|
|
strokeLinecap="round"
|
|
strokeLinejoin="round"
|
|
className="transition-transform duration-200 group-hover:translate-x-0.5"
|
|
aria-hidden="true"
|
|
>
|
|
<line x1="5" y1="12" x2="19" y2="12" />
|
|
<polyline points="12 5 19 12 12 19" />
|
|
</svg>
|
|
</a>
|
|
</div>
|
|
<div
|
|
className="relative grid h-[152px] w-[152px] shrink-0 grid-cols-2 grid-rows-2 gap-2.5 self-center md:h-[168px] md:w-[168px]"
|
|
aria-hidden="true"
|
|
>
|
|
{[
|
|
{ src: '/ktx/icons/postgresql.svg', tint: '#e9eef5', rotate: -7, name: 'Postgres' },
|
|
{ src: '/ktx/icons/metabase.svg', tint: '#e8f1fc', rotate: 6, name: 'Metabase' },
|
|
{ src: '/ktx/icons/dbt.svg', tint: '#fde6dc', rotate: -4, name: 'dbt' },
|
|
{ src: '/ktx/icons/notion.svg', tint: '#f0eee8', rotate: 8, name: 'Notion' },
|
|
].map((sticker) => (
|
|
<div
|
|
key={sticker.name}
|
|
className="flex items-center justify-center rounded-2xl border border-fd-border bg-fd-card shadow-[0_2px_4px_rgba(20,18,12,0.04),0_14px_28px_-12px_rgba(20,18,12,0.22)]"
|
|
style={{ transform: `rotate(${sticker.rotate}deg)` }}
|
|
>
|
|
<span
|
|
className="flex h-full w-full items-center justify-center rounded-2xl"
|
|
style={{ background: sticker.tint }}
|
|
>
|
|
<img
|
|
src={sticker.src}
|
|
alt=""
|
|
width="38"
|
|
height="38"
|
|
style={{ objectFit: 'contain' }}
|
|
/>
|
|
</span>
|
|
</div>
|
|
))}
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div
|
|
className="not-prose my-6 rounded-lg border p-4"
|
|
style={{
|
|
borderColor: 'color-mix(in oklch, var(--color-fd-primary) 35%, transparent)',
|
|
background: 'color-mix(in oklch, var(--color-fd-primary) 8%, transparent)',
|
|
}}
|
|
>
|
|
<div className="flex flex-wrap items-center gap-x-3 gap-y-2">
|
|
<div className="text-sm font-semibold text-fd-foreground">
|
|
Or, ask an AI agent to install and configure **ktx** for you.
|
|
</div>
|
|
<div className="group relative ml-auto inline-flex">
|
|
<button
|
|
type="button"
|
|
aria-describedby="agent-setup-overlay"
|
|
className="inline-flex cursor-help items-center gap-1.5 rounded-full border border-fd-border bg-fd-background/70 px-2.5 py-1 text-xs font-medium text-fd-muted-foreground transition-colors hover:border-fd-primary/40 hover:text-fd-foreground focus:outline-none focus-visible:border-fd-primary/40 focus-visible:text-fd-foreground"
|
|
>
|
|
<svg
|
|
width="12"
|
|
height="12"
|
|
viewBox="0 0 24 24"
|
|
fill="none"
|
|
stroke="currentColor"
|
|
strokeWidth="2.4"
|
|
strokeLinecap="round"
|
|
strokeLinejoin="round"
|
|
aria-hidden="true"
|
|
>
|
|
<circle cx="12" cy="12" r="10" />
|
|
<path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3" />
|
|
<line x1="12" y1="17" x2="12.01" y2="17" />
|
|
</svg>
|
|
What does it do?
|
|
</button>
|
|
<div
|
|
id="agent-setup-overlay"
|
|
role="tooltip"
|
|
className="invisible absolute right-0 top-full z-20 translate-y-0.5 pt-2 opacity-0 transition-all duration-150 group-hover:visible group-hover:translate-y-0 group-hover:opacity-100 group-focus-within:visible group-focus-within:translate-y-0 group-focus-within:opacity-100"
|
|
>
|
|
<div className="w-[min(24rem,calc(100vw-2rem))] rounded-lg border border-fd-border bg-fd-popover p-3 text-sm leading-6 text-fd-popover-foreground shadow-xl">
|
|
<div className="text-xs font-semibold uppercase tracking-wide text-fd-muted-foreground">
|
|
The agent will
|
|
</div>
|
|
<ol className="mt-2 space-y-1.5 pl-0">
|
|
{[
|
|
<>Check prerequisites on your machine</>,
|
|
<>Ask only for credentials and connection choices</>,
|
|
<>Run <code className="whitespace-nowrap">ktx setup</code> in your project</>,
|
|
<>Verify each connection it configured</>,
|
|
<>Report what was installed and what is ready</>,
|
|
].map((item, index) => (
|
|
<li key={index} className="flex gap-2.5">
|
|
<span
|
|
className="mt-0.5 inline-flex h-5 w-5 shrink-0 items-center justify-center rounded-full text-[11px] font-bold tabular-nums"
|
|
style={{
|
|
background: 'color-mix(in oklch, var(--color-fd-primary) 18%, transparent)',
|
|
color: 'var(--color-fd-primary)',
|
|
}}
|
|
>
|
|
{index + 1}
|
|
</span>
|
|
<span className="leading-6">{item}</span>
|
|
</li>
|
|
))}
|
|
</ol>
|
|
<div className="mt-3 border-t border-fd-border pt-2 text-xs text-fd-muted-foreground">
|
|
Works with any AI coding agent.
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div className="mt-3 max-w-full overflow-hidden rounded-md border bg-fd-background">
|
|
<div className="flex items-center justify-between gap-2 border-b px-3 py-2">
|
|
<span className="text-xs font-semibold uppercase tracking-wide text-fd-muted-foreground">
|
|
Prompt
|
|
</span>
|
|
<CopyButton
|
|
text={[
|
|
'Run npx skills add Kaelio/ktx --skill ktx and use the ktx skill',
|
|
'to install and configure ktx',
|
|
].join(' ')}
|
|
className="-my-1"
|
|
/>
|
|
</div>
|
|
<div className="p-3 font-mono text-[13.5px] leading-6 text-fd-foreground">
|
|
Run {'`npx skills add Kaelio/ktx --skill ktx`'} and use the ktx skill to install and configure ktx
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
## Install the CLI
|
|
|
|
Install the published package globally:
|
|
|
|
```bash
|
|
npm install -g @kaelio/ktx
|
|
```
|
|
|
|
**ktx** is open source. If you'd like to hack on it or run from a local checkout,
|
|
the source lives at [github.com/kaelio/ktx](https://github.com/kaelio/ktx) -
|
|
see [Contributing](/docs/community/contributing) to get set up.
|
|
|
|
## Run setup
|
|
|
|
From your project directory, run:
|
|
|
|
```bash
|
|
ktx setup
|
|
```
|
|
|
|
The wizard walks you through everything **ktx** needs in one pass:
|
|
|
|
1. **Project** - creates or resumes `ktx.yaml` in the current directory.
|
|
2. **LLM** - picks a Claude backend. The default uses your local Claude Code
|
|
session, so no API key is required. You can also use an Anthropic API key
|
|
or Vertex AI.
|
|
3. **Embeddings** - picks an embeddings backend. Choose OpenAI for hosted
|
|
embeddings or `sentence-transformers` to run locally without an API key.
|
|
4. **Database** - adds at least one primary connection. Supported drivers:
|
|
SQLite, PostgreSQL, MySQL, SQL Server, BigQuery, and Snowflake.
|
|
5. **Context sources** - optionally adds dbt, MetricFlow, LookML, Looker,
|
|
Metabase, or Notion. You can skip and add them later.
|
|
6. **Build** - runs the first ingest so semantic sources and wiki pages
|
|
are ready for agents.
|
|
7. **Agent integration** - installs project-local rules for Claude Code,
|
|
Codex, Cursor, OpenCode, or universal `.agents`.
|
|
|
|
If you choose local `sentence-transformers` embeddings, **ktx** uses the managed
|
|
Python runtime. To prepare it before setup, run:
|
|
|
|
```bash
|
|
ktx admin runtime install --feature local-embeddings --yes
|
|
ktx admin runtime start --feature local-embeddings
|
|
```
|
|
|
|
During the database step, setup tests the saved connection and builds initial
|
|
schema context:
|
|
|
|
```text
|
|
Testing warehouse
|
|
Connection test passed
|
|
|
|
Building schema context for warehouse
|
|
Running database scan
|
|
```
|
|
|
|
If setup exits early, rerun `ktx setup` in the same directory. **ktx** keeps
|
|
progress under `.ktx/setup/` and resumes from the remaining work.
|
|
|
|
> **Note:** Running bare `ktx` in an interactive terminal outside a **ktx**
|
|
> project opens the same wizard. Inside a project, it opens a menu for
|
|
> resuming setup, connecting an agent, checking status, or exploring a
|
|
> pre-built demo project.
|
|
|
|
## Verify
|
|
|
|
When setup finishes, check readiness:
|
|
|
|
```bash
|
|
ktx status
|
|
```
|
|
|
|
```text
|
|
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)
|
|
```
|
|
|
|
For a structured check inside scripts, use `ktx status --json`.
|
|
|
|
When setup finishes building context, its final context check looks like:
|
|
|
|
```text
|
|
ktx context is ready for agents.
|
|
|
|
Databases:
|
|
warehouse: database context complete
|
|
|
|
Context sources:
|
|
dbt_main: memory update complete
|
|
```
|
|
|
|
## Connect a coding agent
|
|
|
|
The setup wizard installs project-local agent rules in the last step. To
|
|
install or change targets later:
|
|
|
|
```bash
|
|
ktx setup --agents
|
|
```
|
|
|
|
Claude Code and Codex also support global installs with `--global`. Agent
|
|
rules point at the **ktx** CLI path that created them, so agents don't need a
|
|
separate `ktx` binary on `PATH`. If the CLI path changes, rerun
|
|
`ktx setup --agents`.
|
|
|
|
## What setup writes
|
|
|
|
**ktx** writes plain files so people and agents can review changes in git.
|
|
|
|
| Path | Purpose |
|
|
|------|---------|
|
|
| `ktx.yaml` | Project configuration |
|
|
| `.ktx/secrets/*` | Local secret files referenced from `ktx.yaml` - do not commit |
|
|
| `semantic-layer/<connection-id>/*.yaml` | Semantic sources for SQL compilation |
|
|
| `wiki/global/*.md` | Shared business context and metric definitions |
|
|
| `.claude/skills/ktx/`, `.agents/skills/ktx/`, `.cursor/rules/ktx.mdc`, `.opencode/commands/ktx.md` | Installed agent rules |
|
|
|
|
## Scripted setup
|
|
|
|
For repeatable fixtures and automation, skip prompts with flags:
|
|
|
|
```bash
|
|
ktx setup \
|
|
--project-dir ./analytics \
|
|
--no-input \
|
|
--yes \
|
|
--skip-llm \
|
|
--skip-embeddings \
|
|
--database postgres \
|
|
--database-connection-id warehouse \
|
|
--database-url env:DATABASE_URL \
|
|
--database-schema public
|
|
```
|
|
|
|
Then build context:
|
|
|
|
```bash
|
|
ktx ingest warehouse
|
|
```
|
|
|
|
See [ktx setup](/docs/cli-reference/ktx-setup) for the full automation flag
|
|
surface.
|
|
|
|
## Common issues
|
|
|
|
| Symptom | Fix |
|
|
|---------|-----|
|
|
| `ktx: command not found` | Reinstall `@kaelio/ktx` and open a new shell |
|
|
| Setup resumes the wrong project | Pass `--project-dir <path>` |
|
|
| LLM or embeddings health check fails | Rerun setup and pick a different credential, model, or backend |
|
|
| Database test fails | Verify the same connection with the database's native client, then rerun setup |
|
|
| Agent integration is incomplete | Run `ktx setup --agents --target <target>` |
|
|
|
|
## Next steps
|
|
|
|
- Refresh context with [Building Context](/docs/guides/building-context).
|
|
- Edit semantic sources and wiki pages with
|
|
[Writing Context](/docs/guides/writing-context).
|
|
- Connect more tools with [Agent Clients](/docs/integrations/agent-clients).
|
|
- Read [The Context Layer](/docs/concepts/the-context-layer) to understand
|
|
the architecture.
|