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

| 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 <query> --json` | Search wiki pages |
| `ktx sl --json` | List semantic sources |
| `ktx sl <query> --json` | Search semantic sources |
| `ktx sl validate <source> --connection-id <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 |
