Serving Agents

ktx serves agents through the CLI and project-local instruction files. Agents read generated rules, call ktx commands, inspect context files, and use JSON for structured results.

Recommended setup

Run the agent install step from a ktx project:

ktx setup --agents

Or install a specific target:

ktx setup --agents --target codex

Supported targets:

Claude Code and Codex also support global installs:

ktx setup --agents --target claude-code --global
ktx setup --agents --target codex --global

Installed files are recorded in .ktx/agents/install-manifest.json. Rerun ktx setup --agents after moving a checkout or reinstalling the CLI.

Agent command set

All supported clients use the same command surface. Use --project-dir outside the ktx project directory.

Readiness

ktx status --json

Run this before relying on context. It reports project, provider, connection, context-build, and agent-integration readiness.

Semantic layer discovery

ktx sl --json
ktx sl --connection-id warehouse --json
ktx sl "revenue" --json --limit 10

Use these commands to find source names, connection ids, measures, dimensions, and files to inspect.

Semantic-layer validation and queries

ktx sl validate orders --connection-id warehouse

Compile SQL before executing:

ktx sl query \
  --connection-id warehouse \
  --measure orders.total_revenue \
  --dimension orders.created_date \
  --format sql

Execute only when the task calls for live data:

ktx sl query \
  --connection-id warehouse \
  --measure orders.total_revenue \
  --dimension orders.status \
  --execute \
  --max-rows 100

For complex calls, agents can write a JSON query object and pass it with --query-file.

Wiki context

ktx wiki --json
ktx wiki "revenue recognition" --json --limit 10

Search the wiki for business definitions, metric caveats, process rules, and non-obvious terms.

Context refresh

Agents can refresh context when the user asks them to:

ktx ingest warehouse --fast
ktx ingest
ktx ingest --file docs/revenue-notes.md --connection-id warehouse

Use --deep only when LLM and embedding setup is ready.

Good agent behavior

Agents should:

• Run ktx status --json before using ktx context.
• Use ktx sl <query> and ktx wiki <query> before writing SQL from memory.
• Inspect the relevant YAML or Markdown files after search returns candidates.
• Compile SQL with ktx sl query --format sql before executing.
• Use --max-rows whenever executing a live query.
• Validate edited semantic sources with ktx sl validate.
• Keep generated context changes reviewable in git.

ktx is a local context layer with a CLI and plain project files. Do not assume a background server, ORPC route, frontend app, or external migration system.

Manual setup

Use manual setup for custom agents that can read project-local instructions.

1. Install the universal target:

   ktx setup --agents --target universal

2. Configure the agent to read .agents/skills/ktx/SKILL.md.

3. Open the agent in the ktx project directory.

4. Ask it to run ktx status --json and summarize readiness.

For per-client notes, see Agent Clients.

Troubleshooting