mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-10 08:05:14 +02:00
56f4f9c9e8
* fix(cli): package Claude Desktop skills in one zip * Polish ktx setup-agents output: hint, summaries, outro * test: update setup agents output polish assertion * Add output-polish follow-up plan * docs: align Claude Desktop split-ZIP wording Update README and the agent-clients docs page to reflect that ktx setup now produces one uploadable ZIP per Claude Desktop skill under .ktx/agents/claude/ (ktx-analytics.zip and optionally ktx.zip) instead of a single combined ktx-skills.zip. * feat(cli): style next-actions note in TTY mode Add createAgentNextActionsLineFormatter, an ANSI line transformer wired into the "Required before using agents" Clack note. It activates only when the target stream reports hasColors(), so non-TTY pipelines and tests keep the existing plain-text output byte-identical. Per-line rules: cyan-bold step numbers + bold titles; dim sub-prose aligned under the title; dim-cyan bullet for .zip paths with HOME shortened to ~; dim "›" replaces " > " breadcrumbs; RUN/PASTE/USE/OPEN markers dimmed; already-styled lines pass through to avoid double-wrap. * docs: move output polish specs out of ktx
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 client agent targets, or configure manually
|
|
using the snippets below. Choose **Ask data questions with KTX MCP** for client
|
|
agents. 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 list --json --project-dir /path/to/project`
|
|
- `ktx sl search '<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 search '<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 search <query> --json` | Search wiki pages |
|
|
| `ktx sl list --json` | List semantic-layer sources |
|
|
| `ktx sl search <query> --json` | Search semantic-layer sources |
|
|
| `ktx sl validate <source> --connection-id <id>` | Validate semantic source definitions |
|
|
| `ktx sl query --format json` | Execute a semantic-layer 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 |
|