AI¶

Configure AI profiles and terminal AI Agent settings. This is the largest settings tab, encompassing AI features enablement, profiles (with model, API endpoint, connection mode, and reasoning levels), token quota management, snippet editor settings, and internet access configuration. Open via Configuration → Global Settings → AI; stored in ~/.kortty/global-settings.xml.

Core Settings¶

Terminal AI Agent¶

AI Profiles¶

The security-check profile is a dedicated AI profile for snippet Security Check actions. Leave it empty (or use Clear) to reuse the default profile. It can also be set directly in the snippet Security Check window, and both places share the same remembered setting.

AI request timeout is the maximum runtime of a single AI request and applies to every profile. The default 0 means korTTY imposes no timeout at all: long-running tasks such as the snippet editor's Full code analysis run until the model answers. Set a positive number of minutes to cancel requests that exceed it. A profile can override the value — see Timeout for this profile below.

Profile Settings (in Editor Grid)¶

The same fields are edited in AI > AI Manager > Profiles, where the whole form is visible at once:

Snippet Editor¶

Internet Access Configuration¶

Notes¶

AI Profiles¶

KorTTY stores multiple named AI profiles, each with its own model, connection method, reasoning settings, prompt preset, and optional knowledge stores. Each profile tracks its own token usage separately. Profiles support three connection modes:

• HTTP API: Direct connection to an OpenAI-compatible REST endpoint (specify API URL, model name, and optional API key).
• Local CLI: Execute a local command-line AI client (configure CLI provider, custom executable, arguments template, and custom model name).
• Integrated llama.cpp: Choose the installed chat GGUF in Local GGUF model. korTTY acquires a private loopback llama-server lease for it; the API URL and profile API key are managed by korTTY and are not editable.

An explicitly chosen or security-check profile remains most specific. Otherwise terminal text actions use the configured Text profile, code actions use the Coding profile, and an unassigned role falls back to the Default profile. Configure those roles and the local runtime under AI > AI Manager > Local AI; see Local models with llama.cpp.

The AI Manager is modeless and can remain open while you use the main window. Invoking it again restores and focuses the same manager for that main window, and its open primary section remains visibly marked with a bold accent underline when you interact with controls inside that section.

Local AI manager settings¶

Automatic (keep active backend) retains the active runtime package backend for updates. With no installed package, Auto initially selects Metal on macOS and CPU elsewhere. Starting a model configured for another supported GPU backend offers to install the matching signed package.

The Local Models > Setup assistant exposes optional Text, Coding, and RAG-embedding slots. It verifies every selected fixed revision, quantization, license, and exact size before starting its asynchronous runtime/model installation, runs a real chat or embedding test for each installed GGUF, and saves the resulting role assignments only after all tests succeed. The Text and Coding slots may share one model. Configure refuses to replace a model's persisted runtime settings while that model is serving an active request.

Knowledge stores assigned to the Text/Coding roles add only bounded, cited excerpts to matching normal terminal and snippet AI requests, never the complete knowledge store. A cloud Text/Coding profile receives those excerpts over its configured provider connection, so assigning the knowledge store to that role/profile is explicit permission for that disclosure. Agent, Planning, Swarm, and scheduled autonomous prompts remain a separate opt-in; see RAG knowledge stores.

Prompt optimization presets¶

Auto (model detection) resolves common Llama, Qwen, Mistral/Mixtral, Gemma, DeepSeek, Phi, and GPT-OSS names. A family preset adds concise compatibility guidance while leaving korTTY's strict JSON/code contracts authoritative; Generic adds no family-specific guidance. llama.cpp still applies the GGUF's native chat template.

Reasoning Effort Levels¶

Reasoning effort configures how deeply the AI thinks before responding. Available levels depend on the model and endpoint:

• Disabled: No reasoning parameter sent; model uses its default behavior.
• None: Explicitly disable reasoning with the transport's supported off value.
• Minimal: Light reasoning; fastest execution.
• Low: Low effort reasoning; balance between speed and depth.
• Medium: Medium effort; reasonable depth.
• High: High effort; more thorough reasoning.
• Extra high: Maximum reasoning effort; slowest but most comprehensive.

Not all models support all levels. When LM Studio publishes capabilities.reasoning.allowed_options through its native model metadata, korTTY uses that exact list instead of treating a silently converted value as supported, and it reads that list automatically: picking another model or endpoint in the profile editor re-reads the metadata for the model you just chose, so the dropdown follows the profile without any further action. The list is only read from the endpoint's model metadata here — a single request that sends no prompt. Use the Refresh reasoning options button when you want to force a re-check, or for an endpoint that publishes no such metadata: that button also runs active connection probes.

For a binary off/on model, an explicit none request switches this feature off, while omitting the reasoning parameter uses the model's published default; the unsupported Minimal, Low, Medium, High, and Extra high levels are not offered. A model whose LM Studio metadata publishes no reasoning capability at all — including a virtual model that overrides its reasoning metadata to false — offers only Disabled: LM Studio skips an unsupported request-time reasoning value with a log warning instead of rejecting the request, so an active probe would mistake every level for supported.

A detected list belongs to the endpoint and model it was read for. Changing either discards it, and where korTTY cannot read the new combination's metadata — a CLI profile, a cloud endpoint — the profile falls back to the conservative defaults for its model name until you press Refresh reasoning options. A level that is no longer offered is dropped from the request with a log line naming the level actually used. Fields that a profile's own connection mode does not use, such as the CLI provider of an HTTP profile, never invalidate a detected list. Profiles using an integrated model keep their detected levels.

For MiniMax endpoints (directly or through an aggregator whose model name contains minimax), both Disabled and an explicit none are sent as MiniMax's own thinking: disabled parameter, because those models ignore reasoning_effort and otherwise think by default — billing the hidden reasoning as completion tokens and, for MiniMax-M3, opening the reply with an inline <think> block. An explicit effort level is passed through unchanged.

For the native Anthropic (Claude) endpoint, an enabled reasoning level requests extended thinking with a level-dependent thinking budget; models that do not support extended thinking are retried once without it. The model's reasoning is shown in the Terminal AI Agent's 💭 thinking rows.

Image input (vision)¶

Image input (vision) decides whether korTTY may attach images to a prompt for this profile — used by the session journal's AI screenshot analysis. Auto (detect) derives the capability from the endpoint: for a local LM Studio endpoint the model metadata is authoritative (a vlm model counts as image-capable; the answer is read together with the reasoning levels — by the automatic metadata read and by Refresh reasoning options — and cached with them), the native Anthropic endpoint always counts as image-capable, and other endpoints are recognized by well-known vision model names (GPT-4o/4.⅕, o3/o4, Gemini, Gemma 3, Qwen-VL, LLaVA, Pixtral and similar). Enabled/Disabled override the detection for models it misjudges. CLI and integrated (llama.cpp/MLX) profiles cannot send images. Local LM Studio vision models (vlm) also appear in the model dropdown.

Token Quota Management¶

Each AI profile maintains a token usage quota with the following controls:

• Tokenizer: Choose which tokenizer estimates token counts—useful when switching between OpenAI and other providers. Options are Estimate (generic), cl100k_base (GPT-3.5/4), o200k_base (o1/o1-mini), p50k_base (Codex), and r50k_base (GPT-2).
• Max tokens limit: Set a spending cap (in thousands or millions of tokens, or unlimited). Token count resets on a rolling schedule.
• Reset period: Number of days between resets (1–3650), with an optional anchor date for predictable reset timing.
• Warning thresholds: Yellow warning triggers at a percentage of the limit; red warning at a higher percentage. Configure both as integers 0–100.

Token usage is displayed as a colored bar and summary on the profile editor, and the profile list shows token status inline.

Internet Access Modes¶

Per-profile internet access strategy for AI requests. Each mode requires different credentials and MCP configuration:

• Disabled (default): No internet access.
• KorTTY Tavily Tool: Built-in web search using Tavily API directly (requires Tavily API key).
• LM Studio Tavily MCP: Web search via an LM Studio Tavily MCP instance (requires Tavily API key and MCP server label).
• Bright Data Web MCP: Structured data extraction and browsing via Bright Data Web MCP (requires Bright Data API token and MCP server label).
• Brave Search MCP: Search via Brave Search MCP (requires Brave Search API key and MCP plugin ID in mcp/<server_label> format).
• SearXNG MCP: Search via a SearXNG MCP instance (requires SearXNG URL and MCP plugin ID in mcp/<server_label> format).
• LM Studio Toolpack: Community LM Studio Toolpack web-search server (requires plugin ID in mcp/<server_label> format).

Credentials are encrypted and stored securely. Use the Clear toggle adjacent to each secret field to erase stored values on the next save.