mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
b00c1a11a9
* docs: add CLI component reuse guidance * docs: add unified ingest ux design * Refine unified ingest UX design after adversarial review iteration 1 * Refine unified ingest UX design after adversarial review iteration 2 * Refine unified ingest UX design after adversarial review iteration 3 * feat(cli): route public connection ingest command * feat(cli): hide standalone scan from public help * feat(cli): plan public ingest depth and query history * feat(cli): execute public database ingest facets * feat(ingest): read connection query history config * fix(cli): use public ingest wording * fix(config): stop generating ingest adapter allow lists * docs: document public ingest command * test: align ingest surface expectations * docs: add unified ingest public CLI surface plan * feat(cli): preflight deep public ingest readiness * feat(setup): store query history in connection context * feat(setup): store database context depth * feat(setup): verify context readiness by database depth * fix(setup): keep context build foreground only * fix(config): reject reserved ingest connection ids * test: close unified ingest v1 expectations * docs: add unified ingest v1 closure plan * fix(ingest): bypass adapter allow-list for public source ingest * fix(ingest): honor query history window intent * fix(ingest): hide scan internals from public database ingest * feat(ingest): use foreground view for interactive public ingest * fix(setup): use schema context and query history wording * test(cli): verify unified ingest public output * docs: add unified ingest v1 public output closure plan * fix(setup): forward query history flags * fix(setup): prompt for postgres query history * fix(status): report query history readiness * fix(ingest): remove legacy public guidance * fix(ingest): polish foreground retry copy * docs(examples): use unified query history wording * chore(ingest): finish public query history cleanup * docs: add unified ingest v1 query history status cleanup plan * test(docs): cover unified ingest public docs * docs: align ingest CLI reference with unified UX * docs: update context build guides for unified ingest * docs: update setup and primary source ingest wording * docs: stop advertising adapter-backed example ingest * docs: close unified ingest public docs gaps * docs: add unified ingest v1 docs site closure plan * fix: render unified ingest foreground warnings * fix: explain query history schema order * fix: add public ingest retry guidance * fix: align setup next steps with unified ingest * fix: remove scan wording from demo progress * test: verify unified ingest ux closure * docs: add unified ingest v1 foreground and retry closure plan * fix(cli): preserve query-history pull config in public ingest * fix(cli): omit hidden commands from docs command tree * test(cli): close unified ingest final public surface checks * docs: add unified ingest v1 final public surface closure plan * fix(cli): use public source labels in ingest reports * fix(cli): suppress low-level public ingest output * test(cli): verify unified ingest public plain output * docs: add unified ingest v1 public plain output closure plan * fix(cli): add public ingest copy sanitizers * fix(cli): sanitize public ingest progress copy * fix(cli): rename setup schema scope prompt * docs(plan): add progress copy closure; test: align setup back-nav fixture Adds the iter9 plan and updates the setup back-navigation test fixture to pass disableQueryHistory plus listSchemas/listTables stubs that the unified ingest setup step now requires. * docs(plan): add final ux labels plan with narrowed label scans * fix(cli): aggregate unsupported query-history warnings * fix(cli): align setup database labels * test(cli): fix setup database test type-check * fix(cli): remove primary-source wording from setup output * test(cli): verify unified ingest setup closure * docs(plan): add unified ingest v1 verification copy closure plan * fix(cli): remove top-level scan command * fix(cli): remove legacy ingest and wiki commands * Merge scan into ingest flow * feat(cli): split ingest progress into per-phase rows, rename work units to tasks Each database target in the unified ingest dashboard now renders one row per real subprocess (Schema, then Query history when enabled) instead of a single combined bar. Each phase has its own monotonic 0-100% bar so the progress never snaps back to zero when historic-sql starts after scan completes. Completed phases keep their final bar, summary, and elapsed time visible as an inline audit trail; queued and skipped phases are shown explicitly. Also rename user-facing "work units" / "Failed work units" to "tasks" / "Failed tasks" in ingest output and parseIngestSummary. The parser still accepts the legacy "Work units:" wording in captured output for backward compat. Internal memory-flow event names and type fields are left alone. * Fix test harness failures * Fix CI smoke checks --------- Co-authored-by: Andrey Avtomonov <7889985+andreybavt@users.noreply.github.com>
146 lines
4.6 KiB
Text
146 lines
4.6 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.
|
|
|
|
## Claude Code
|
|
|
|
### Install via `ktx setup`
|
|
|
|
During setup, select **Claude Code** from the agent targets. KTX writes:
|
|
|
|
| Mode | File |
|
|
|------|------|
|
|
| CLI skills | `.claude/skills/ktx/SKILL.md` |
|
|
|
|
Both project-scoped and global installations are supported. Global installs write to `~/.claude/skills/ktx/SKILL.md`.
|
|
|
|
### 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/`.
|
|
- 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:
|
|
|
|
| Mode | File |
|
|
|------|------|
|
|
| CLI skills | `.agents/skills/ktx/SKILL.md` |
|
|
|
|
Both project-scoped and global installations are supported. Global installs write to `$CODEX_HOME/skills/ktx/SKILL.md` (defaults to `~/.codex/skills/ktx/SKILL.md`).
|
|
|
|
### 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.
|
|
- 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 |
|
|
| Config location | `.claude/skills/ktx/SKILL.md` | `.cursor/rules/ktx.mdc` | `.agents/skills/ktx/SKILL.md` | `.opencode/commands/ktx.md` |
|