From 074c9c3d97e69a628076ca92aa866ed77d1640a7 Mon Sep 17 00:00:00 2001 From: Andrey Avtomonov Date: Mon, 1 Jun 2026 17:25:43 +0200 Subject: [PATCH] docs: document codex llm backend --- .../content/docs/cli-reference/ktx-setup.mdx | 9 ++++++- .../content/docs/cli-reference/ktx-status.mdx | 8 ++++-- .../content/docs/configuration/ktx-yaml.mdx | 13 +++++++++- .../content/docs/guides/building-context.mdx | 8 +++++- .../content/docs/guides/llm-configuration.mdx | 25 +++++++++++++++++++ 5 files changed, 58 insertions(+), 5 deletions(-) diff --git a/docs-site/content/docs/cli-reference/ktx-setup.mdx b/docs-site/content/docs/cli-reference/ktx-setup.mdx index 0da7b339..af719066 100644 --- a/docs-site/content/docs/cli-reference/ktx-setup.mdx +++ b/docs-site/content/docs/cli-reference/ktx-setup.mdx @@ -51,8 +51,9 @@ prompts. | Flag | Description | |------|-------------| -| `--llm-backend ` | LLM backend: `anthropic`, `vertex`, or `claude-code` | +| `--llm-backend ` | LLM backend: `anthropic`, `vertex`, `claude-code`, or `codex` | | `--llm-backend claude-code` | Use the local Claude Code session for **ktx** LLM calls | +| `--llm-backend codex` | Use local Codex authentication for **ktx** LLM calls | | `--llm-model ` | LLM model ID or backend model alias to validate and save | | `--anthropic-api-key-env ` | Environment variable containing the Anthropic API key | | `--anthropic-api-key-file ` | File containing the Anthropic API key | @@ -65,6 +66,9 @@ valid with the Anthropic backend; Vertex flags are only valid with the Vertex backend. The `claude-code` backend uses local Claude Code authentication instead of Anthropic API key or Vertex flags. For Claude Code, `--llm-model` accepts `sonnet`, `opus`, `haiku`, or a full Claude model ID. +The `codex` backend uses local Codex authentication instead of Anthropic API key +or Vertex flags. For Codex, `--llm-model` accepts `gpt-5.3-codex`, `gpt-5.4`, +or another `gpt-*` or `codex-*` model ID. ### Embeddings @@ -191,6 +195,9 @@ ktx setup \ --llm-backend claude-code \ --llm-model opus +# Configure ktx to use local Codex authentication for LLM work +ktx setup --llm-backend codex --llm-model gpt-5.3-codex --no-input + # Script a Postgres connection that reads its URL from the environment ktx setup \ --project-dir ./analytics \ diff --git a/docs-site/content/docs/cli-reference/ktx-status.mdx b/docs-site/content/docs/cli-reference/ktx-status.mdx index 51c00148..59047ee4 100644 --- a/docs-site/content/docs/cli-reference/ktx-status.mdx +++ b/docs-site/content/docs/cli-reference/ktx-status.mdx @@ -21,7 +21,7 @@ ktx status [options] | `--json` | Print JSON output | `false` | | `-v`, `--verbose` | Show every check, including passing ones | `false` | | `--validate` | Only validate the `ktx.yaml` schema; skip readiness checks | `false` | -| `--fast` | Skip checks that require external communication (query-history readiness probes and Claude Code auth probe) | `false` | +| `--fast` | Skip checks that require external communication (query-history readiness probes, Claude Code auth probe, and Codex auth probe) | `false` | | `--no-input` | Disable interactive terminal input | - | ## Examples @@ -39,7 +39,7 @@ ktx status --verbose # Validate ktx.yaml without running readiness checks ktx status --validate -# Skip slow probes (query-history readiness, Claude Code auth) +# Skip slow probes (query-history readiness, Claude Code auth, Codex auth) ktx status --fast # Check a project from another directory @@ -57,6 +57,10 @@ flow, then rerun `ktx status`. Use `--fast` to skip this probe (useful in CI or offline contexts); skipped checks render as `-` and carry `"status": "skipped"` in JSON output. +For `llm.provider.backend: codex`, `ktx status` runs a minimal non-interactive +Codex request. If the probe fails, authenticate Codex locally with the Codex CLI +and verify the Codex CLI installation. + A `Local data` section summarises what the project has accumulated locally: ingest run counts, last completed timestamp per connection, knowledge page counts by scope, semantic-layer source and dictionary value counts, and the diff --git a/docs-site/content/docs/configuration/ktx-yaml.mdx b/docs-site/content/docs/configuration/ktx-yaml.mdx index 13105851..63f2d66f 100644 --- a/docs-site/content/docs/configuration/ktx-yaml.mdx +++ b/docs-site/content/docs/configuration/ktx-yaml.mdx @@ -376,13 +376,24 @@ llm: | Field | Type | Default | Purpose | |-------|------|---------|---------| -| `provider.backend` | `none` \| `anthropic` \| `vertex` \| `gateway` \| `claude-code` | `none` | Selected backend. `none` disables LLM features. `claude-code` uses the local Claude Code session and needs no API key. | +| `provider.backend` | `none` \| `anthropic` \| `vertex` \| `gateway` \| `claude-code` \| `codex` | `none` | Selected backend. `none` disables LLM features. `claude-code` uses the local Claude Code session and needs no API key. `codex` uses local Codex authentication. | | `provider.anthropic.api_key` | `string` | - | Anthropic API key. Required when `backend: anthropic`. Accepts `env:` or `file:` references. | | `provider.anthropic.base_url` | `string` | - | Override the Anthropic API base URL (proxy, self-hosted gateway). | | `provider.gateway.api_key` / `base_url` | `string` | - | Credentials for an AI Gateway provider. Required when `backend: gateway`. | | `provider.vertex.project` | `string` | - | Google Cloud project ID hosting the Vertex AI endpoint. | | `provider.vertex.location` | `string` | - | Vertex AI region (for example `us-east5`). Required when the `vertex` block is present. | +Use `codex` when you want **ktx** LLM work to run through local Codex +authentication: + +```yaml +llm: + provider: + backend: codex + models: + default: gpt-5.3-codex +``` + ### Model roles `models` overrides the per-role model. Keys are fixed; values are diff --git a/docs-site/content/docs/guides/building-context.mdx b/docs-site/content/docs/guides/building-context.mdx index b806c424..2791c160 100644 --- a/docs-site/content/docs/guides/building-context.mdx +++ b/docs-site/content/docs/guides/building-context.mdx @@ -37,7 +37,13 @@ ktx ingest --all ``` Enriched ingest needs a configured model and embeddings. Run `ktx setup` first; -connections without that configuration fail before any work starts. +connections without that configuration fail before any work starts. Local-auth +LLM options include Claude Code and Codex: + +```bash +ktx setup --llm-backend claude-code --no-input +ktx setup --llm-backend codex --llm-model gpt-5.3-codex --no-input +``` With `claude-code`, **ktx** agent loops can invoke only the **ktx** MCP tools for the current run. diff --git a/docs-site/content/docs/guides/llm-configuration.mdx b/docs-site/content/docs/guides/llm-configuration.mdx index 880df24e..b5067fc9 100644 --- a/docs-site/content/docs/guides/llm-configuration.mdx +++ b/docs-site/content/docs/guides/llm-configuration.mdx @@ -16,6 +16,7 @@ Set `llm.provider.backend` to one of these values: - `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 @@ -47,6 +48,30 @@ model IDs are also accepted. 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.3-codex +``` + +Configure it non-interactively: + +```bash +ktx setup --llm-backend codex --llm-model gpt-5.3-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. + ## Prompt caching `llm.promptCaching` has partial parity on `claude-code`. Status and doctor warn