mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-10 08:05:14 +02:00
2366b00301
* refactor(workspace): relocate @ktx/llm source into packages/cli/src/llm * refactor(workspace): rewrite @ktx/llm imports to relative paths * refactor(workspace): fold internal packages into cli * chore(workspace): gate dead-code with knip production mode Turn on production-mode knip plus an autofix run in pre-commit and the `pnpm dead-code` script, document the `/** @internal */` convention for test-only exports in AGENTS.md, annotate test-only exports across the CLI with that JSDoc, and drop dead exports/wrappers the new gate surfaced (e.g. `cli-project.ts`, `lookerRuntimeSourceToFileAdapterSource`, `createLocalScanEnrichmentProvidersFromConfig`, `PGLITE_OWNER_PROCESS_BACKEND_CAPABILITIES`, stale type re-exports). Replace the loose `ignoreIssues` allowlist in `knip.json` with explicit production entries so cross-package barrel leaks are caught. * refactor(cli): delete internal barrel index.ts files The 34 `index.ts` re-export barrels inside `packages/cli/src/` were holdovers from the pre-fold multi-workspace structure. Post-fold-in they served no production purpose: external consumers go through the single package main entry, and in-repo callers mostly imported through them only because the path was short. Internally, knip flagged most barrel re-exports as production-dead (only reached via tests). This change: - Deletes every internal barrel except `packages/cli/src/index.ts` (the published package entry). - Rewrites ~270 source/test files to import each name directly from the file that defines it. - Moves `tools/warehouse-verification/index.ts` to `create-warehouse-verification-tools.ts` (the function it defined locally) and updates its single consumer. - Renames `search/backend-conformance.ts` → `.test-utils.ts` to match the existing test-helper file convention. - Deletes 13 dead test-only chains (dbt-descriptions/*, live-database/extracted-schema, live-database/structural-sync, relationship-* feedback/review chain) plus their tests and a cascading orphan integration test. - Updates test mocks that pointed at deleted barrel paths (notion-client, connector barrels in scan/local-scan-connectors tests) to mock the source files instead. - Points the maintainer benchmark script (`scripts/relationship-benchmark-report.mjs`) at source files instead of `dist/context/scan/index.js`. - Drops the barrel `!` entries from `knip.json`; adds explicit production entries only for the benchmark code reached via dist by the maintainer script. Net: 413 files changed, ~1.2k insertions, ~9.4k deletions. `pnpm run dead-code` (Biome + knip default + knip production) and `pnpm run type-check` are clean; 2277 tests pass. * refactor(workspace): rename @ktx/cli to @kaelio/ktx and pack it directly Promote the CLI workspace package to the public name `@kaelio/ktx` and drop the separate `scripts/build-public-npm-package.mjs` wrapper. The CLI package is now publishable in place (`publishConfig.access: public`, `provenance: true`), so artifact packing uses `pnpm pack` against `packages/cli/` instead of assembling a parallel package tree. Updates all workspace filter invocations, docs, tests, and release readiness checks to reference the new package name, and folds the tarball-name helper into `scripts/public-npm-release-metadata.mjs`. * docs: align "agent clients" and "data agents" terminology Replace "client agents" with "agent clients" and "database agents" with "data agents" across AGENTS.md, README.md, the docs-site copy, and the matching setup-agents test description, matching the canonical vocabulary in docs/terminology.md. Also moves packages/cli/tsconfig.json's tsBuildInfoFile from node_modules/.cache/ to dist/.tsbuildinfo so incremental builds survive node_modules reinstalls. * refactor(release): single source of truth for package version Make packages/cli/package.json the single source of truth for the @kaelio/ktx version. publicNpmPackageVersion() now reads it directly, so artifact filenames, release-readiness checks, and the Python wheel version all derive from one field. The duplicate release-policy.json.publicNpmPackageVersion is removed. Previously the two fields could drift: tarballs were named kaelio-ktx-0.4.1.tgz while internally containing @kaelio/ktx@0.0.0-private. - update-public-release-version.mjs rewrites both Python pyproject.toml files (ktx-daemon, ktx-sl) alongside the npm package.jsons, normalizing the version for PEP 440 (e.g. 0.1.0-rc.2 -> 0.1.0rc2). - semantic-release-config.cjs adds the two pyproject.toml files to @semantic-release/git assets so the release commit back to main carries every version source in lockstep. - The six "?? '0.0.0-private'" fallback literals across the CLI are replaced with "?? getKtxCliPackageInfo().version", and createDefaultKtxMcpServer makes its version arg required. - docs/release.md describes the actual commit-back model: the dev tree always reflects the most recent release; no sentinel pin to maintain. Verified: pnpm run artifacts:build now produces kaelio-ktx-0.4.1.tgz and kaelio_ktx-0.4.1-py3-none-any.whl with @kaelio/ktx@0.4.1 inside. Full type-check, dead-code, and 2287 vitests + 173 script tests pass. * refactor(cli): inject embedding provider resolution and detect sentence-transformers runtime Make resolveProjectEmbeddingProvider and runtimeIo injectable in ingest and scan command entrypoints so tests can stub them, and teach resolvePublicIngestRuntimeRequirements to flag the local-embeddings runtime feature when ktx.yaml selects sentence-transformers. * chore(cli): mark buildLocalStatsStatus and LocalStatsStatus as @internal Both symbols are consumed only by status-project.test.ts. Annotating with /** @internal */ keeps knip's production-mode check clean without changing runtime behavior. * fix(cli): use real package metadata in print-command-tree The stubbed package name embedded a forbidden product identifier that tripped the boundary check in CI. Read the metadata from package.json instead — keeps the rendered tree unchanged and removes a duplicate source of truth. * feat(cli): show embedding coverage in `ktx status`, drop duplicate disk counts Inline `(N embedded)` next to the Wiki scope counts and Semantic-layer source counts, computed with `SUM(embedding_json IS NOT NULL)` over `knowledge_pages` and `local_sl_sources`. Rename the "Knowledge" label to "Wiki" (canonical per `docs/terminology.md`) and rename the matching `localStats.knowledgePages` field to `localStats.wikiPages`. Drop `wiki=N md` and `semantic-layer=N yaml` from the Disk row — those duplicated the per-surface rows above. Disk now reports only actual byte usage (db, cache, raw-sources). The unused `wikiGlobalMarkdownCount` / `semanticLayerYamlCount` fields, the `isMarkdownEntry` / `isYamlEntry` helpers, and the `filter` arg on `summarizeDir` are removed.
306 lines
12 KiB
Text
306 lines
12 KiB
Text
---
|
|
title: Agent Clients
|
|
description: Set up ktx with Claude Code, Claude Desktop, Cursor, Codex, and OpenCode.
|
|
---
|
|
|
|
**ktx** exposes context to end-user agents through MCP tools. The CLI remains the
|
|
admin surface for setup, ingest, status, daemon lifecycle, and debugging.
|
|
|
|
Run `ktx setup` and select your agent client targets, or configure manually
|
|
using the snippets below. Choose **Ask data questions with ktx MCP** for agent
|
|
clients. Choose **Ask data questions + manage ktx with CLI commands** only when
|
|
a developer or operator agent also needs pinned `ktx` admin commands.
|
|
|
|
## Install with setup
|
|
|
|
Install client integration first:
|
|
|
|
```bash
|
|
ktx setup --agents
|
|
```
|
|
|
|
Then start the MCP server before using HTTP-based clients:
|
|
|
|
```bash
|
|
ktx mcp start
|
|
```
|
|
|
|
Use `--target` for one target:
|
|
|
|
```bash
|
|
ktx setup --agents --target codex
|
|
```
|
|
|
|
Use `--global` only with `claude-code` or `codex`. Claude Desktop always writes
|
|
global Claude Desktop config and generates project-local skill ZIPs:
|
|
|
|
```bash
|
|
ktx setup --agents --target claude-code --global
|
|
ktx setup --agents --target codex --global
|
|
```
|
|
|
|
**ktx** records installed files in `.ktx/agents/install-manifest.json`. That
|
|
manifest lets status checks report agent readiness and lets future cleanup
|
|
remove only files **ktx** installed.
|
|
|
|
The interactive command asks two questions:
|
|
|
|
```txt
|
|
◆ What should agents be allowed to do with this ktx project?
|
|
│ ○ Ask data questions with ktx MCP
|
|
│ ○ Ask data questions + manage ktx with CLI commands
|
|
└
|
|
|
|
◆ Which agent targets should ktx install?
|
|
│ ◻ Claude Code
|
|
│ ◻ Claude Desktop
|
|
│ ◻ Codex
|
|
│ ◻ Cursor
|
|
│ ◻ OpenCode
|
|
│ ◻ Universal .agents
|
|
└
|
|
```
|
|
|
|
When every selected target supports both project and global setup, the command
|
|
also asks where to install supported agent config:
|
|
|
|
```txt
|
|
◆ Where should ktx install supported agent config?
|
|
│
|
|
│ ktx project: /path/to/your/ktx-project
|
|
│
|
|
│ ○ Project scope (ktx project directory)
|
|
│ ○ Global scope (user config)
|
|
└
|
|
```
|
|
|
|
## Generated files
|
|
|
|
**ktx** writes MCP client configuration and analytics guidance by default. It writes
|
|
admin CLI guidance only when you choose **Ask data questions + manage ktx with
|
|
CLI 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 and
|
|
prints separate skill upload steps.
|
|
|
|
| Target | Ask data questions with **ktx** MCP | Adds when agents can manage **ktx** with CLI |
|
|
|--------|------------------------------|---------------------------|
|
|
| Claude Code | `.mcp.json`, `.claude/skills/ktx-analytics/SKILL.md` | `.claude/skills/ktx/SKILL.md`, `.claude/rules/ktx.md` |
|
|
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` stdio entry + `.ktx/agents/claude/ktx-analytics.zip` upload | Adds `.ktx/agents/claude/ktx.zip` upload |
|
|
| Codex | Printed snippet for `~/.codex/config.toml`, `.agents/skills/ktx-analytics/SKILL.md` | `.agents/skills/ktx/SKILL.md`, `.codex/instructions/ktx.md` |
|
|
| Cursor | `.cursor/mcp.json`, `.cursor/rules/ktx-analytics.mdc` | `.cursor/rules/ktx.mdc` |
|
|
| OpenCode | Printed snippet for `opencode.json`, `.opencode/commands/ktx-analytics.md` | `.opencode/commands/ktx.md` |
|
|
| Universal `.agents` | Printed MCP endpoint, `.agents/skills/ktx-analytics/SKILL.md` | `.agents/skills/ktx/SKILL.md` |
|
|
|
|
MCP config gives agents access to **ktx** context tools such as discovery,
|
|
semantic-layer queries, wiki search, SQL execution, and memory ingest. The
|
|
analytics skill explains how to use those tools for semantic-layer-first
|
|
analysis. Optional admin skill and rule files list pinned CLI commands for
|
|
developer or operator agents.
|
|
|
|
## Claude Code
|
|
|
|
### Install via `ktx setup`
|
|
|
|
During setup, select **Claude Code** from the agent targets. **ktx** writes:
|
|
|
|
| Scope | Files |
|
|
|-------|-------|
|
|
| Project | `.mcp.json`, `.claude/skills/ktx-analytics/SKILL.md`; optional `.claude/skills/ktx/SKILL.md`, `.claude/rules/ktx.md` |
|
|
| Global | `~/.claude.json`, `~/.claude/skills/ktx-analytics/SKILL.md`; optional `~/.claude/skills/ktx/SKILL.md`, `~/.claude/rules/ktx.md` |
|
|
|
|
Both project-scoped and global installations are supported.
|
|
|
|
### Manual CLI skills configuration
|
|
|
|
Use manual CLI skills only for developer or operator agents that need admin
|
|
commands. End-user data agents use MCP.
|
|
|
|
Create `.claude/skills/ktx/SKILL.md`:
|
|
|
|
```markdown title=".claude/skills/ktx/SKILL.md"
|
|
---
|
|
name: ktx
|
|
description: Use local ktx semantic context and wiki knowledge for this project.
|
|
---
|
|
|
|
Available commands:
|
|
- `ktx status --json --project-dir /path/to/project`
|
|
- `ktx sl --json --project-dir /path/to/project`
|
|
- `ktx sl '<text>' --json --project-dir /path/to/project --connection-id '<id>'`
|
|
- `ktx sl query --project-dir /path/to/project --connection-id '<id>' --query-file '<path>' --format json --execute --max-rows 100`
|
|
- `ktx wiki '<query>' --json --project-dir /path/to/project --limit 10`
|
|
```
|
|
|
|
### Workflow tips
|
|
|
|
- Claude Code discovers skills automatically from `.claude/skills/`.
|
|
- Claude Code reads MCP config from `.mcp.json` for project-scoped MCP tools.
|
|
- Claude rules in `.claude/rules/` tell Claude when **ktx** should be used.
|
|
- Global installation makes **ktx** available in all projects without per-project setup.
|
|
- Keep generated skills committed only when your team wants project-local agent instructions in git.
|
|
|
|
---
|
|
|
|
## Cursor
|
|
|
|
### Install via `ktx setup`
|
|
|
|
During setup, select **Cursor** from the agent targets. **ktx** writes:
|
|
|
|
| Mode | File |
|
|
|------|------|
|
|
| Ask data questions with **ktx** MCP | `.cursor/mcp.json`, `.cursor/rules/ktx-analytics.mdc` |
|
|
| Admin CLI rules | `.cursor/rules/ktx.mdc` |
|
|
|
|
Cursor supports project-scoped installation only.
|
|
|
|
### Manual CLI rules configuration
|
|
|
|
Use manual CLI rules only for developer or operator agents that need admin
|
|
commands. End-user data agents use MCP.
|
|
|
|
Create `.cursor/rules/ktx.mdc` with the same content structure as the Claude
|
|
Code `SKILL.md` file. Cursor rules use the `.mdc` extension but support the
|
|
same markdown command definitions.
|
|
|
|
### Workflow tips
|
|
|
|
- Cursor rules in `.cursor/rules/` are automatically loaded into agent context.
|
|
- Project-scoped installs keep **ktx** command guidance close to the analytics context repository.
|
|
|
|
---
|
|
|
|
## Claude Desktop
|
|
|
|
During setup, select **Claude Desktop** from the agent targets. **ktx** writes the
|
|
MCP server entry directly into Claude Desktop's config and prepares uploadable
|
|
Claude Desktop skill packages for the **ktx** workflows:
|
|
|
|
- `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
|
|
`%AppData%/Claude/claude_desktop_config.json` (Windows) gets an
|
|
`mcpServers.ktx` entry that runs the **ktx** MCP server over stdio via a local
|
|
launcher shim at `.ktx/agents/claude/ktx-plugin-runner.sh`. The shim locates
|
|
a usable Node.js (Volta, NVM, Homebrew, system) so Claude Desktop can spawn
|
|
the server without needing `node` in PATH.
|
|
- `.ktx/agents/claude/ktx-analytics.zip` contains the `ktx-analytics` skill.
|
|
If you choose **Ask data questions + manage ktx with CLI commands**, **ktx** also
|
|
generates `.ktx/agents/claude/ktx.zip` with the admin `ktx` skill. Claude
|
|
Desktop requires each uploaded ZIP to contain exactly one skill folder.
|
|
|
|
After `ktx setup`, restart Claude Desktop so it picks up the new MCP server
|
|
entry. No daemon needs to be running -- Claude Desktop spawns the MCP server
|
|
itself per session.
|
|
|
|
Upload each generated skill ZIP from Claude Desktop:
|
|
|
|
1. Open **Customize** > **Skills**.
|
|
2. Click **+** > **Create skill** > **Upload a skill**.
|
|
3. Upload `.ktx/agents/claude/ktx-analytics.zip`.
|
|
4. If generated, upload `.ktx/agents/claude/ktx.zip`.
|
|
5. Toggle the uploaded **ktx** skills on.
|
|
|
|
Claude Desktop does not introspect local stdio MCP servers, so the per-tool
|
|
"Connector"-style UI is not rendered for **ktx**. The tools are still callable
|
|
from any Claude Desktop chat.
|
|
|
|
If you move the **ktx** checkout or project directory, rerun `ktx setup --agents`
|
|
to refresh the absolute paths in `claude_desktop_config.json` and the launcher
|
|
shim, regenerate the skill ZIPs, then restart Claude Desktop and upload the new
|
|
ZIPs.
|
|
|
|
---
|
|
|
|
## Codex
|
|
|
|
### Install via `ktx setup`
|
|
|
|
During setup, select **Codex** from the agent targets. **ktx** writes:
|
|
|
|
| Scope | Files |
|
|
|-------|-------|
|
|
| Project | MCP snippet, `.agents/skills/ktx-analytics/SKILL.md`; optional `.agents/skills/ktx/SKILL.md`, `.codex/instructions/ktx.md` |
|
|
| Global | MCP snippet, `$CODEX_HOME/skills/ktx-analytics/SKILL.md`; optional `$CODEX_HOME/skills/ktx/SKILL.md`, `$CODEX_HOME/instructions/ktx.md` |
|
|
|
|
Both project-scoped and global installations are supported. `CODEX_HOME`
|
|
defaults to `~/.codex`.
|
|
|
|
### Manual CLI skills configuration
|
|
|
|
Use manual CLI skills only for developer or operator agents that need admin
|
|
commands. End-user data agents use MCP.
|
|
|
|
Create `.agents/skills/ktx/SKILL.md` with the same content structure as Claude
|
|
Code's `SKILL.md`.
|
|
|
|
### Workflow tips
|
|
|
|
- Set `CODEX_HOME` to customize the global installation directory.
|
|
- Codex shares the `.agents/` directory structure with the universal format.
|
|
- Codex instructions in `.codex/instructions/` tell Codex when **ktx** should be used.
|
|
- Global installation makes **ktx** available across all Codex sessions.
|
|
|
|
---
|
|
|
|
## OpenCode
|
|
|
|
### Install via `ktx setup`
|
|
|
|
During setup, select **OpenCode** from the agent targets. **ktx** writes:
|
|
|
|
| Mode | File |
|
|
|------|------|
|
|
| Ask data questions with **ktx** MCP | Snippet for `opencode.json`, `.opencode/commands/ktx-analytics.md` |
|
|
| Admin CLI commands | `.opencode/commands/ktx.md` |
|
|
|
|
OpenCode supports project-scoped installation only.
|
|
|
|
### Manual CLI commands configuration
|
|
|
|
Use manual CLI commands only for developer or operator agents that need admin
|
|
commands. End-user data agents use MCP.
|
|
|
|
Create `.opencode/commands/ktx.md` with the same command definitions as Claude
|
|
Code's `SKILL.md`.
|
|
|
|
### Workflow tips
|
|
|
|
- OpenCode reads commands from `.opencode/commands/` on startup.
|
|
- Project-scoped only; use a shared repository template if multiple projects need identical command files.
|
|
|
|
---
|
|
|
|
## Command reference
|
|
|
|
Admin CLI skills call the same **ktx** CLI commands:
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `ktx status --json` | Return project setup and context readiness |
|
|
| `ktx wiki <query> --json` | Search wiki pages |
|
|
| `ktx sl --json` | List semantic sources |
|
|
| `ktx sl <query> --json` | Search semantic sources |
|
|
| `ktx sl validate <source> --connection-id <id>` | Validate semantic source definitions |
|
|
| `ktx sl query --format json` | Execute a semantic query when semantic compute is configured |
|
|
|
|
### Security constraints
|
|
|
|
- Secrets and credentials are never exposed in command output.
|
|
- Commands resolve the project from `--project-dir`, `KTX_PROJECT_DIR`, or the nearest `ktx.yaml`.
|
|
|
|
---
|
|
|
|
## Comparison
|
|
|
|
| | Claude Code | Claude Desktop | Cursor | Codex | OpenCode |
|
|
|---|---|---|---|---|---|
|
|
| MCP tools | Yes | Local stdio via `claude_desktop_config.json` | Yes | Snippet | Snippet |
|
|
| Analytics skill | `.claude/skills/ktx-analytics/SKILL.md` | Upload `.ktx/agents/claude/ktx-analytics.zip` | `.cursor/rules/ktx-analytics.mdc` | `.agents/skills/ktx-analytics/SKILL.md` | `.opencode/commands/ktx-analytics.md` |
|
|
| Admin CLI skills | Optional | Optional `.ktx/agents/claude/ktx.zip` upload | Optional (.mdc) | Optional | Optional |
|
|
| Global install | Yes | Claude Desktop config | No | Yes | No |
|
|
| Rule or instruction file | `.claude/rules/ktx.md` | Not separate | `.cursor/rules/ktx.mdc` | `.codex/instructions/ktx.md` | `.opencode/commands/ktx.md` |
|
|
| Skill file | `.claude/skills/ktx/SKILL.md` | `ktx/SKILL.md` inside `ktx.zip` | Not separate | `.agents/skills/ktx/SKILL.md` | Not separate |
|