mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-10 08:05:14 +02:00
191 lines
6.2 KiB
Text
191 lines
6.2 KiB
Text
---
|
|
title: Agent Clients
|
|
description: Set up KTX with Claude Code, Cursor, Codex, and OpenCode.
|
|
---
|
|
|
|
KTX integrates with coding agents through CLI skills and command files. These
|
|
files teach agents to call public `ktx` commands directly from the terminal for
|
|
semantic-layer context and wiki knowledge.
|
|
|
|
Run `ktx setup` and select your agent targets, or configure manually using the
|
|
snippets below. Setup pins generated skill files to the KTX CLI path that
|
|
created them, so agents do not need `ktx` on `PATH`.
|
|
|
|
## Install with setup
|
|
|
|
```bash
|
|
ktx setup --agents
|
|
```
|
|
|
|
Use `--target` for one target:
|
|
|
|
```bash
|
|
ktx setup --agents --target codex
|
|
```
|
|
|
|
Use `--global` only with `claude-code` or `codex`:
|
|
|
|
```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.
|
|
|
|
## Generated files
|
|
|
|
| Target | Project-scoped files | Global files |
|
|
|--------|----------------------|--------------|
|
|
| Claude Code | `.claude/skills/ktx/SKILL.md`, `.claude/rules/ktx.md` | `~/.claude/skills/ktx/SKILL.md`, `~/.claude/rules/ktx.md` |
|
|
| Codex | `.agents/skills/ktx/SKILL.md`, `.codex/instructions/ktx.md` | `$CODEX_HOME/skills/ktx/SKILL.md`, `$CODEX_HOME/instructions/ktx.md` |
|
|
| Cursor | `.cursor/rules/ktx.mdc` | Not supported |
|
|
| OpenCode | `.opencode/commands/ktx.md` | Not supported |
|
|
| Universal `.agents` | `.agents/skills/ktx/SKILL.md` | Not supported |
|
|
|
|
Skill files list pinned `ktx` commands. Rule files tell the agent when KTX is
|
|
appropriate, such as data schemas, metrics, dimensions, database structure, and
|
|
SQL questions.
|
|
|
|
## Claude Code
|
|
|
|
### Install via `ktx setup`
|
|
|
|
During setup, select **Claude Code** from the agent targets. KTX writes:
|
|
|
|
| Scope | Files |
|
|
|-------|-------|
|
|
| Project | `.claude/skills/ktx/SKILL.md`, `.claude/rules/ktx.md` |
|
|
| Global | `~/.claude/skills/ktx/SKILL.md`, `~/.claude/rules/ktx.md` |
|
|
|
|
Both project-scoped and global installations are supported.
|
|
|
|
### Manual CLI skills configuration
|
|
|
|
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 --json --project-dir /path/to/project --connection-id '<id>' --query-file '<path>' --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 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 |
|
|
|------|------|
|
|
| CLI rules | `.cursor/rules/ktx.mdc` |
|
|
|
|
Cursor supports project-scoped installation only.
|
|
|
|
### Manual CLI rules configuration
|
|
|
|
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.
|
|
|
|
---
|
|
|
|
## Codex
|
|
|
|
### Install via `ktx setup`
|
|
|
|
During setup, select **Codex** from the agent targets. KTX writes:
|
|
|
|
| Scope | Files |
|
|
|-------|-------|
|
|
| Project | `.agents/skills/ktx/SKILL.md`, `.codex/instructions/ktx.md` |
|
|
| Global | `$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
|
|
|
|
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 |
|
|
|------|------|
|
|
| CLI commands | `.opencode/commands/ktx.md` |
|
|
|
|
OpenCode supports project-scoped installation only.
|
|
|
|
### Manual CLI commands configuration
|
|
|
|
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
|
|
|
|
All supported agent clients 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 --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 | Cursor | Codex | OpenCode |
|
|
|---|---|---|---|---|
|
|
| CLI skills | Yes | Yes (.mdc) | Yes | Yes |
|
|
| Global install | Yes | No | Yes | No |
|
|
| Rule or instruction file | `.claude/rules/ktx.md` | `.cursor/rules/ktx.mdc` | `.codex/instructions/ktx.md` | `.opencode/commands/ktx.md` |
|
|
| Skill file | `.claude/skills/ktx/SKILL.md` | Not separate | `.agents/skills/ktx/SKILL.md` | Not separate |
|