--- 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 '' --json --project-dir /path/to/project --connection-id ''` - `ktx sl query --project-dir /path/to/project --connection-id '' --query-file '' --format json --execute --max-rows 100` - `ktx wiki search '' --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 --json` | Search wiki pages | | `ktx sl list --json` | List semantic-layer sources | | `ktx sl search --json` | Search semantic-layer sources | | `ktx sl validate --connection-id ` | Validate semantic source definitions | | `ktx sl query --format json` | Execute a Semantic 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 |