Agent Clients

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:

ktx setup --agents

Then start the MCP server before using HTTP-based clients:

ktx mcp start

Use --target for one target:

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:

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:

◆  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:

◆  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.

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:

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:

---
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:

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:

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:

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:

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