mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-10 08:05:14 +02:00
2c18a62de4
* feat(setup): write per-role llm model presets * feat(setup): remove llm model setup flag * chore(setup): update llm preset guidance * docs(setup): document llm model presets * chore(release): sync uv.lock to 0.9.0 * fix(cli): make sl query --execute work on secret-backed connections sl query --execute used a parallel SQL executor (createDefaultLocalQueryExecutor) that passed connection.url verbatim into pg, so file:/env: secret references failed with "SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a string". Collapse onto the connector-based executor already used by MCP and ingest (createKtxCliIngestQueryExecutor), which resolves secret references and supports every driver. Delete the now-dead local/postgres/sqlite query executors, their tests, and the orphaned hasLocalQueryExecutor driver flag. * docs(agents): require one implementation per capability Add a design-reasoning default and a matching self-check question telling agents to route callers through a single shared implementation of a capability rather than forking a parallel one, and to fix the shared layer rather than patch one branch. Encodes the lesson from a divergent SQL-execution-path bug, stated generally. CLAUDE.md is a symlink to AGENTS.md, so both agent-instruction files are covered.
95 lines
3 KiB
Text
95 lines
3 KiB
Text
---
|
|
title: LLM configuration
|
|
description: Configure ktx LLM providers, model roles, and prompt caching.
|
|
---
|
|
|
|
Configure text generation, structured extraction, and ingest or memory loops in
|
|
the top-level `llm` block.
|
|
|
|
## Backends
|
|
|
|
Set `llm.provider.backend` to one of these values:
|
|
|
|
- `anthropic`: Use the Anthropic API through `ANTHROPIC_API_KEY` or the
|
|
configured `api_key` reference.
|
|
- `vertex`: Use Vertex AI Anthropic models through Google Cloud credentials.
|
|
- `gateway`: Use AI Gateway-compatible Anthropic model ids.
|
|
- `claude-code`: Use your local Claude Code session through the Claude Agent
|
|
SDK. **ktx** strips provider-routing environment variables from child processes.
|
|
- `codex`: Use your local Codex authentication through the Codex SDK.
|
|
|
|
## Claude Code
|
|
|
|
Use aliases or full Claude model IDs in `llm.models`:
|
|
|
|
```yaml
|
|
llm:
|
|
provider:
|
|
backend: claude-code
|
|
models:
|
|
default: sonnet
|
|
triage: haiku
|
|
candidateExtraction: sonnet
|
|
curator: opus
|
|
reconcile: opus
|
|
repair: haiku
|
|
```
|
|
|
|
During setup, choose the backend interactively or pass it in automation:
|
|
|
|
```bash
|
|
ktx setup --llm-backend claude-code --no-input
|
|
```
|
|
|
|
Setup writes `sonnet`, `haiku`, and `opus` aliases into `llm.models`. You can
|
|
edit any role to another alias or a full Claude model ID after setup.
|
|
|
|
`claude-code` exposes only **ktx** MCP tools for the current agent loop. SDK init
|
|
metadata may still list host slash commands, skills, and subagents; **ktx** does not
|
|
grant execution access to them.
|
|
|
|
## Codex backend
|
|
|
|
Use `codex` when you want **ktx** to run LLM-backed workflows through your
|
|
local Codex authentication instead of a direct provider API key.
|
|
|
|
```yaml
|
|
llm:
|
|
provider:
|
|
backend: codex
|
|
models:
|
|
default: gpt-5.5
|
|
triage: gpt-5.5
|
|
candidateExtraction: gpt-5.5
|
|
curator: gpt-5.5
|
|
reconcile: gpt-5.5
|
|
repair: gpt-5.5
|
|
```
|
|
|
|
Configure it non-interactively:
|
|
|
|
```bash
|
|
ktx setup --llm-backend codex --no-input
|
|
```
|
|
|
|
This is separate from Codex agent-client setup. `ktx setup --agents --target
|
|
codex` installs instructions and MCP access for an end-user Codex session.
|
|
`ktx setup --llm-backend codex` makes **ktx** itself execute ingest, scan
|
|
enrichment, memory, and other LLM-backed work through Codex.
|
|
|
|
During runtime loops, **ktx** starts a temporary loopback MCP server for the
|
|
current run, exposes only the tools passed to that run, asks Codex to use a
|
|
read-only sandbox, sets `approval_policy=never`, auto-approves only those
|
|
run-scoped MCP tools, and disables Codex web search.
|
|
|
|
Codex backend isolation is currently limited by the public Codex SDK and CLI
|
|
surface. Codex may still load user Codex config and built-in command execution
|
|
or read-only file capabilities. Use `llm.provider.backend: claude-code` when
|
|
you need stricter Claude-Code-style runtime tool isolation, or remove host
|
|
Codex MCP and tool config before running untrusted prompts through the `codex`
|
|
backend.
|
|
|
|
## Prompt caching
|
|
|
|
`llm.promptCaching` has partial parity on `claude-code`. Status and doctor warn
|
|
when the Claude Agent SDK backend ignores configured cache fields.
|