iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/tui/screens/guides/_docs/en/guides/configuration/chat-options.md

@@ -0,0 +1,276 @@
+# Chat Options
+
+Chat Options add fields to every request a model profile sends. Use them to set reasoning effort, turn thinking on or off, turn on prompt caching, or pass settings that a gateway or self-hosted server needs. This guide explains how to fill them in, then lists settings for common model services, with links to each service's own documentation.
+
+Provider documentation last checked: **2026-09-30**. Examples are alternatives, not a list to enable together. Support depends on the exact model, API endpoint, and server version; a compatible protocol does not guarantee identical options.
+
+## Add a Chat Option
+
+1. Open the "Model Configuration" window (see [Configure models](./models.md#open-the-model-configuration-window)) and select a model profile.
+2. In the "Extra Options" section, find "Chat Options". Click "+ Add" for a new row.
+3. Enter the field name in the left box and its value in the right box.
+4. Click "Save".
+
+Changes apply to later requests after you save and close the window. To remove an option, click ✕ at the end of its row, then save.
+
+### How values are read
+
+iCode reads each value as JSON when it can:
+
+- `0.2` is sent as a number and `true` as a boolean.
+- `{"type": "adaptive"}` is sent as an object and `["a", "b"]` as a list.
+- Anything else is sent as text: `high` is sent as `"high"`. To send text that looks like a number or `true`, put it in quotes, for example `"1"`.
+
+Keep the whole value on one line. Check braces, quotes, and commas carefully. An object with a typo, such as a trailing comma, is saved as plain text, and the model service then rejects the request. Fields that must hold an object, such as `extra_body`, are checked instead: iCode shows an error and does not save.
+
+### Where service-specific fields go
+
+The client library for the selected provider and API style accepts a fixed set of field names at the top level, such as `temperature`, `reasoning_effort` for Chat Completions, or `thinking` for Anthropic. An unknown keyword can fail before the request reaches the server, with `unexpected keyword argument`. Put service extensions, or new API fields that iCode's bundled client library does not yet accept, inside `extra_body`. Examples for OpenAI-compatible servers include `top_k`, `enable_thinking`, and `chat_template_kwargs`:
+
+| Key | Value |
+| --- | --- |
+| `extra_body` | `{"chat_template_kwargs": {"enable_thinking": false}, "top_k": 20}` |
+
+A profile can have only one `extra_body` row, so put every such field into the same JSON object, as in the example above. When a field appears both as its own row and inside `extra_body`, the value in `extra_body` is the one sent.
+
+`extra_body` merges fields into the HTTP request body; it does not make an unsupported field work on the server. Likewise, `top_k` is an extension for OpenAI-compatible servers but a native field on Anthropic's API.
+
+### Settings that have their own fields
+
+Some settings don't belong in Chat Options:
+
+- **Output length**: use the "Max Output Tokens" field. Rows such as `max_tokens` are refused at save.
+- **Streaming**: use the "Streaming" checkbox, which is on by default; uncheck it to turn streaming off. Don't add a `stream` row.
+- **Model**: use the "Model" field.
+- **HTTP headers**: use the "HTTP Extra Headers" rows, or an `extra_headers` row whose value is a JSON object. For Anthropic's `anthropic-beta` header, "HTTP Extra Headers" add to iCode's beta flags, while an `extra_headers` row replaces them; see [Anthropic](#anthropic).
+- **Claude thinking settings**: use the `thinking_block_binding` and `auto_interleaved_thinking` lines of the profile file; see [Claude thinking settings](./models.md#claude-thinking-settings).
+
+iCode builds the messages, tools, and system prompt itself, so fields such as `messages` are refused at save.
+
+### Keep secrets out of the profile
+
+To read part of a value from an environment variable, write the variable name in double braces. For example, to send a gateway token as a header:
+
+| Key | Value |
+| --- | --- |
+| `extra_headers` | `{"X-Api-Token": "{{MY_GATEWAY_TOKEN}}"}` |
+
+The profile file keeps the placeholder, and iCode fills in the value when it sends a request. Set the variable before starting iCode. If it isn't set, iCode reports an error naming the variable.
+
+### Which requests use Chat Options
+
+Chat Options are shared by requests made with the profile, including the main agent, sub-agents, workflow agents, session titles, the automatic approval judge, and context compaction. Individual operations may override or filter options for their own request. Higher reasoning effort can also increase the latency and cost of these auxiliary requests.
+
+## Prompt caching
+
+In iCode's default local-history mode, requests resend the conversation currently in context. Prompt caching lets the service reuse an unchanged prefix, reducing repeated input processing and usually its price. It is separate from storing a conversation on the service. Cache writes may cost extra, so savings depend on how often the prefix is reused.
+
+OpenAI, DeepSeek, GLM, Kimi's Chat Completions API, and Qwen offer automatic caching on supported models. vLLM and SGLang manage prefix caching on the server; their launch settings and model support determine whether it is active. See the provider sections below for sources and exceptions.
+
+**Anthropic's Claude API requires a cache setting.** To enable automatic caching of the growing conversation prefix, add this row:
+
+| Key | Value |
+| --- | --- |
+| `extra_body` | `{"cache_control": {"type": "ephemeral"}}` |
+
+If the profile already has an `extra_body` row, add `"cache_control": {"type": "ephemeral"}` to its object instead. Anthropic's standard 5-minute writes cost 1.25× the base input rate; reads cost 0.1× or less, depending on the model. For a 1-hour entry, use `{"type": "ephemeral", "ttl": "1h"}`; writes cost 2×. The TTL runs from the start of a request that writes or reuses the entry, so generation time consumes part of it. A model-specific minimum prefix length also applies. See [Anthropic prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for current limits and pricing rules.
+
+### The "Prompt Caching Is Off" reminder
+
+When you save a profile with the "Anthropic" provider, a model ID containing `claude`, and no `cache_control` setting, iCode shows the "Prompt Caching Is Off" window:
+
+- **Add and Save** adds `"cache_control": {"type": "ephemeral"}` to the `extra_body` row, creating the row if needed, then saves.
+- **Save as Is** saves the profile unchanged.
+- Press **Esc** or click outside the window to return to the form without saving.
+
+iCode shows the reminder on the save that makes the profile a complete Claude profile: a new profile, or one you changed to the Anthropic provider or to a Claude model. Saving a profile that is already a Claude profile doesn't show it again.
+
+Anthropic-compatible services have their own cache behavior: they may honor, ignore, or reject `cache_control`. Check the endpoint's documentation. If it rejects the field, remove only `"cache_control": {...}` from `extra_body` and save. The reminder checks the profile's settings, not whether the server actually cached a request.
+
+### Check that caching works
+
+Open the sidebar (**Ctrl+G** shows or hides it) and select the "Context" tab. In the "Token Usage" section, the "Cached" row shows the session's accumulated reported cache reads. It grows when a request reports a hit, not necessarily on every call. `-` does not prove caching is disabled: the service may report no hits or omit cache usage.
+
+If "Cached" stays at `-` or stops growing:
+
+- Check that the profile has the setting the service needs (see [Settings for common model services](#settings-for-common-model-services)).
+- Check the model's minimum cacheable prefix length, retention period, and cache-write requirements. Short prompts may not qualify, and expired or evicted entries cannot be reused.
+- Keep reusable content stable. Changing the model, tools, reasoning settings, or compacting history can reduce cache reuse; a change need not invalidate every earlier matching prefix.
+- A request routed to a different backend may miss even with identical input. Automatic caching does not guarantee a hit.
+
+## Settings for common model services
+
+Each section below lists the recommended provider, API style, and base URL, then some commonly used settings. Field names and allowed values change with each model, so check the linked documentation for the model you use.
+
+### OpenAI
+
+Provider "OpenAI", API style "Responses", with the default base URL. "Chat Completions" works too, but some newer models support tool calls only on Responses. Prompt caching is automatic.
+
+| What you want | Key | Value |
+| --- | --- | --- |
+| Reasoning effort (Responses) | `reasoning` | `{"effort": "high"}` |
+| Reasoning summaries (Responses) | `reasoning` | `{"effort": "high", "summary": "auto"}` |
+| Reasoning effort (Chat Completions) | `reasoning_effort` | `high` |
+| Shorter answers | `verbosity` | `low` |
+| Cheaper, slower processing | `service_tier` | `flex` |
+| Cache lifetime on GPT-5.6 and later (Responses) | `extra_body` | `{"prompt_cache_options": {"mode": "implicit", "ttl": "30m"}}` |
+
+On Responses, use `reasoning` rather than `reasoning_effort`. iCode translates its `verbosity` option to the API's `text.verbosity`. Allowed effort levels, summaries, verbosity, and Flex availability vary by model. Flex can also return resource-unavailable errors; see [Flex processing](https://developers.openai.com/api/docs/guides/flex-processing).
+
+GPT-5.6 and later use `prompt_cache_options` with a `30m` TTL; automatic cache writes are billable. Earlier models use `prompt_cache_retention`, with values such as `in_memory` or `24h` depending on the model. These settings are not interchangeable. Keep `mode` implicit: explicit mode requires content-block breakpoints, which the Chat Options form does not add.
+
+On Responses with OpenAI's own address, iCode also sends the session ID as `prompt_cache_key`, so requests from one session share a cache key; sub-agents and workflow agents use their own. To use a key of your own, add a `prompt_cache_key` row. To send none, set its value to `null`.
+
+Leave `store` unset unless you want service-side continuation: iCode sends `false` by default, which still allows prompt caching. Setting it to `true` disables iCode's context compaction.
+
+Documentation: [Reasoning](https://developers.openai.com/api/docs/guides/reasoning), [Prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching), [Responses API reference](https://developers.openai.com/api/reference/resources/responses/methods/create), [Chat Completions API reference](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create).
+
+### Anthropic
+
+Provider "Anthropic", base URL `https://api.anthropic.com`. Don't add `/v1` to the base URL. **Add prompt caching**, as described in [Prompt caching](#prompt-caching).
+
+| What you want | Key | Value |
+| --- | --- | --- |
+| Prompt caching | `extra_body` | `{"cache_control": {"type": "ephemeral"}}` |
+| Adaptive thinking | `thinking` | `{"type": "adaptive"}` |
+| Thinking with a fixed budget (older models) | `thinking` | `{"type": "enabled", "budget_tokens": 8000}` |
+| Effort | `output_config` | `{"effort": "medium"}` |
+| Interleaved thinking on older models at another address | `additional_beta_flags` | `["interleaved-thinking-2025-05-14"]` |
+
+- Use `adaptive` only on models that support it; recent models reject the older `enabled`/`budget_tokens` form. For ordinary fixed-budget thinking, set "Max Output Tokens" higher than `budget_tokens` (manual interleaved thinking has different budget rules).
+- Newer Claude models reject non-default `temperature`, `top_p`, and `top_k` values, so leave them unset.
+- `additional_beta_flags` and `betas` add beta flags to the request, as does an `anthropic-beta` header in "HTTP Extra Headers". iCode sends them all, after its own flags, in one `anthropic-beta` header. An `anthropic-beta` key in an `extra_headers` row replaces all of these flags, iCode's own included; iCode then adds only the flags the thinking settings need.
+- With fixed-budget thinking at Anthropic's own address, iCode adds the interleaved-thinking flag itself; see [Claude thinking settings](./models.md#claude-thinking-settings). At another address, add it yourself as in the table above. Adaptive thinking already interleaves and needs no flag. Interleaving depends on the exact model, and accepting a beta flag does not mean it takes effect.
+- With Claude Opus 5.5, Fable 5.1 or Sonnet 5.5 and adaptive thinking at Anthropic's own address, iCode asks the service to leave out earlier thinking that no longer matches the conversation; see [Claude thinking settings](./models.md#claude-thinking-settings). A `block_binding` you write into `thinking` yourself is sent as written, and iCode adds the beta flag it needs.
+
+Documentation: [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching), [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking), [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking), [Effort](https://platform.claude.com/docs/en/build-with-claude/effort), [Beta headers](https://platform.claude.com/docs/en/api/beta-headers).
+
+### DeepSeek
+
+Provider "DeepSeek (OpenAI)", API style "Chat Completions", with the default base URL `https://api.deepseek.com`. Prompt caching is automatic.
+
+| What you want | Key | Value |
+| --- | --- | --- |
+| Turn thinking off | `extra_body` | `{"thinking": {"type": "disabled"}}` |
+| Reasoning effort | `reasoning_effort` | `high` |
+
+The current API enables thinking by default and accepts `low`, `high`, or `max` effort. In thinking mode, `temperature`, `presence_penalty`, and `frequency_penalty` are ignored; `top_p` is effective only from 0.95 to 1.0. Older model IDs may have different capabilities.
+
+Documentation: [Thinking mode](https://api-docs.deepseek.com/guides/thinking_mode), [Context caching](https://api-docs.deepseek.com/guides/kv_cache), [API reference](https://api-docs.deepseek.com/api/create-chat-completion).
+
+### GLM (Zhipu / Z.ai)
+
+Provider "GLM (OpenAI)". The default base URL is `https://open.bigmodel.cn/api/paas/v4`; outside mainland China use `https://api.z.ai/api/paas/v4`, and for the GLM Coding Plan use `https://open.bigmodel.cn/api/coding/paas/v4` or `https://api.z.ai/api/coding/paas/v4`. Prompt caching is automatic.
+
+| What you want | Key | Value |
+| --- | --- | --- |
+| Turn thinking off | `extra_body` | `{"thinking": {"type": "disabled"}}` |
+| Keep earlier reasoning in context | `extra_body` | `{"thinking": {"type": "enabled", "clear_thinking": false}}` |
+| Reasoning effort (GLM-5.2 and later) | `reasoning_effort` | `high` |
+
+GLM-5.3 always thinks and accepts `low`, `high`, or `max` effort; do not send `thinking.type: disabled` to it. GLM-5.2 has different effort mappings, and earlier models do not support this effort field. `clear_thinking: false` also requires intact historical reasoning, which iCode's GLM provider preserves. `temperature` ranges from 0 to 1.
+
+Documentation: [Thinking mode](https://docs.z.ai/guides/capabilities/thinking-mode), [Context caching](https://docs.z.ai/guides/capabilities/cache), [API reference](https://docs.z.ai/api-reference/llm/chat-completion).
+
+### Kimi (Moonshot AI)
+
+Provider "OpenAI", API style "Chat Completions", base URL `https://api.moonshot.ai/v1` (in mainland China, `https://api.moonshot.cn/v1`). Prompt caching is automatic.
+
+| What you want | Key | Value |
+| --- | --- | --- |
+| Reasoning effort (Kimi K3) | `reasoning_effort` | `high` |
+| Turn thinking off (Kimi K2.6) | `extra_body` | `{"thinking": {"type": "disabled"}}` |
+| Longer cache lifetime (Chat Completions) | `extra_body` | `{"prompt_cache_options": {"mode": "implicit", "ttl": "1h"}}` |
+
+Kimi K3 always thinks, accepts `low`, `high`, or `max` effort, and does not accept a `thinking` field. K2.7 Code always thinks but does not support `reasoning_effort`; K2.6 can disable thinking but also does not support that effort field. Leave sampling options unset unless the exact model documents them; fixed-value restrictions on some Kimi models are not a universal sampling contract. iCode only accepts `n` omitted or set to `1`.
+
+Chat Completions uses a 5-minute cache by default. The 1-hour option has a higher cache-write price; changing TTL does not change the lifetime of an existing entry before it expires.
+
+Kimi also offers an Anthropic-protocol endpoint: provider "Anthropic", base URL `https://api.moonshot.ai/anthropic`. On it, requests write to the cache only when they ask for caching, so add the `cache_control` setting from [Prompt caching](#prompt-caching).
+
+Documentation: [Chat API](https://platform.kimi.ai/docs/api/chat), [Thinking models](https://platform.kimi.ai/docs/guide/use-thinking-models), [Context caching](https://platform.kimi.ai/docs/guide/context-caching), [Anthropic-compatible API](https://platform.kimi.ai/docs/api/messages).
+
+### Qwen (Alibaba Cloud Model Studio)
+
+Provider "OpenAI", API style "Chat Completions", and the OpenAI-compatible base URL from your Model Studio console. The current recommendation is a workspace-specific endpoint, such as `https://<WorkspaceId>.cn-beijing.maas.aliyuncs.com/compatible-mode/v1` (Beijing) or `https://<WorkspaceId>.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1` (Singapore); replace `<WorkspaceId>` with your workspace ID. The older `dashscope.aliyuncs.com` and `dashscope-intl.aliyuncs.com` endpoints remain available. API keys and endpoints must match the region; other regions and Coding Plan have their own endpoints. Implicit caching is automatic on supported models, with no guaranteed hit.
+
+| What you want | Key | Value |
+| --- | --- | --- |
+| Turn thinking off | `extra_body` | `{"enable_thinking": false}` |
+| Thinking with a budget | `extra_body` | `{"enable_thinking": true, "thinking_budget": 4096}` |
+| Sampling | `extra_body` | `{"top_k": 20}` |
+| Let the model search the web | `extra_body` | `{"enable_search": true}` |
+
+`enable_thinking: false` applies to hybrid thinking models; thinking-only models cannot disable it. Budget limits, `top_k`, and `enable_search` support also vary by model. Some open-source Qwen models require "Streaming" for thinking, while commercial models can also support non-streaming requests. Model Studio also offers explicit caching via message-block markers; the Chat Options form does not add those markers.
+
+Documentation: [OpenAI compatibility](https://www.alibabacloud.com/help/en/model-studio/compatibility-of-openai-with-dashscope), [Deep thinking](https://www.alibabacloud.com/help/en/model-studio/deep-thinking), [Context cache](https://www.alibabacloud.com/help/en/model-studio/context-cache).
+
+### vLLM
+
+Provider "OpenAI", API style "Chat Completions", base URL `http://<host>:<port>/v1`. For "API Key", enter the server's `--api-key` value, or leave it blank if the server doesn't use one. Prefix caching is a server setting: check `--enable-prefix-caching` / `--no-enable-prefix-caching` and support for the deployed model.
+
+For iCode agents that use tools, start the server with `--enable-auto-tool-choice` and the `--tool-call-parser` that matches your model. Add the matching `--reasoning-parser` for reasoning models to separate reasoning from the answer.
+
+| What you want | Key | Value |
+| --- | --- | --- |
+| Turn thinking off (Qwen3 and similar) | `extra_body` | `{"chat_template_kwargs": {"enable_thinking": false}}` |
+| Reasoning effort | `reasoning_effort` | `low` |
+| Sampling | `extra_body` | `{"top_k": 20, "min_p": 0.0, "repetition_penalty": 1.05}` |
+
+These are model-template options, not universal switches. Some models always think; others use a different toggle. `reasoning_effort` does not provide the same effort levels on every model. Match the documentation to your installed vLLM version.
+
+Documentation: [Tool calling](https://docs.vllm.ai/en/latest/features/tool_calling/), [Reasoning outputs](https://docs.vllm.ai/en/latest/features/reasoning_outputs/), [OpenAI-compatible server](https://docs.vllm.ai/en/latest/serving/openai_compatible_server/), [Server arguments](https://docs.vllm.ai/en/latest/cli/serve/).
+
+### SGLang
+
+Provider "OpenAI", API style "Chat Completions", base URL `http://<host>:<port>/v1`. Configure the tool parser for tool use and the reasoning parser for reasoning models. Prefix caching is enabled by default in ordinary server configurations, but `--disable-radix-cache` or model-specific constraints can disable it.
+
+| What you want | Key | Value |
+| --- | --- | --- |
+| Turn thinking off (hybrid Qwen3 models) | `extra_body` | `{"chat_template_kwargs": {"enable_thinking": false}}` |
+| Turn thinking on (DeepSeek-V3.1) | `extra_body` | `{"chat_template_kwargs": {"thinking": true}}` |
+| Reasoning effort | `reasoning_effort` | `low` |
+| Sampling | `extra_body` | `{"top_k": 20, "min_p": 0.0, "repetition_penalty": 1.05}` |
+
+The template's accepted keys and effort levels depend on the model and SGLang version. A reasoning parser separates output; it does not itself enable thinking. Keep `separate_reasoning` enabled to display reasoning separately. Configure `reasoning_effort` in either the request or the server's template defaults, not both.
+
+Documentation: [OpenAI-compatible API](https://docs.sglang.io/docs/basic_usage/openai_api_completions), [Server arguments](https://docs.sglang.io/docs/advanced_features/server_arguments), [Tool parser](https://docs.sglang.io/docs/advanced_features/tool_parser), [Reasoning parser](https://docs.sglang.io/docs/advanced_features/separate_reasoning).
+
+### LiteLLM proxy
+
+Provider "OpenAI", API style "Chat Completions", base URL `http://<host>:4000`, and a LiteLLM virtual key (`sk-...`) as the API key. For Claude models, you can also use provider "Anthropic" with the same base URL, which reaches LiteLLM's Anthropic-format endpoint.
+
+| What you want | Key | Value |
+| --- | --- | --- |
+| Tag spend for cost tracking | `extra_body` | `{"metadata": {"tags": ["team-a"]}}` |
+| Route by tag | `extra_body` | `{"tags": ["free"]}` |
+
+Tag routing requires matching deployment tags and enabled tag filtering in the proxy; a request tag alone does not configure routing. Spend reporting also depends on the proxy's tracking setup and available features.
+
+For unsupported OpenAI parameters, the proxy administrator can configure `drop_params`; those settings are then silently omitted. It is not a general fix for an invalid provider-specific field or value. Remove or correct those fields in the profile.
+
+Documentation: [Virtual keys](https://docs.litellm.ai/docs/proxy/user_keys), [Cost tracking](https://docs.litellm.ai/docs/proxy/cost_tracking), [Tag routing](https://docs.litellm.ai/docs/proxy/tag_routing), [Dropping unsupported parameters](https://docs.litellm.ai/docs/completion/drop_params), [Anthropic `/v1/messages` endpoint](https://docs.litellm.ai/docs/anthropic_unified).
+
+### OpenRouter
+
+Provider "OpenAI", API style "Chat Completions", base URL `https://openrouter.ai/api/v1`.
+
+| What you want | Key | Value |
+| --- | --- | --- |
+| Choose which providers serve the model | `extra_body` | `{"provider": {"order": ["anthropic"], "allow_fallbacks": false}}` |
+| Reasoning effort | `extra_body` | `{"reasoning": {"effort": "high"}}` |
+| Prompt caching for Claude models | `extra_body` | `{"cache_control": {"type": "ephemeral"}}` |
+
+To combine these, put them in one object, for example `{"provider": {"order": ["anthropic"]}, "cache_control": {"type": "ephemeral"}}`.
+
+`provider.order` sets preference; retain `allow_fallbacks: false` if only the listed providers should serve the request. Top-level `cache_control` is supported for Claude automatic caching, but model and provider support still matters. OpenRouter's documented behavior can differ from calling that provider directly.
+
+Documentation: [Quickstart](https://openrouter.ai/docs/quickstart), [Provider selection](https://openrouter.ai/docs/guides/routing/provider-selection), [Reasoning tokens](https://openrouter.ai/docs/guides/best-practices/reasoning-tokens), [Prompt caching](https://openrouter.ai/docs/guides/best-practices/prompt-caching).
+
+## If requests fail after you add an option
+
+- **Saving shows `Chat Options row N: ...`**: fix the row the message names, then save again.
+- **The error contains `unexpected keyword argument 'x'`**: move the field `x` into `extra_body`, as described in [Where service-specific fields go](#where-service-specific-fields-go).
+- **The model service says it doesn't support a field**: remove only that field. If it is inside `extra_body`, delete just that member from the JSON object and keep the others. Then save.
+- **The error names an environment variable**: set that variable and restart iCode, or remove the `{{...}}` placeholder.
+- **Nothing obvious**: remove recently added rows one at a time until requests work again, and check the service's documentation for the model you use.

chrys/app/tui/screens/guides/_docs/en/guides/configuration/compaction.md

@@ -0,0 +1,42 @@
+# Configure context compaction
+
+When a long conversation approaches the model's context window, iCode automatically compacts earlier content to make room for subsequent requests. This guide explains how to configure the Last Words supplement and output limit for agents of the "Built-in" type. External ACP agents manage their own context.
+
+New agents use defaults suited to most tasks, so adjustments are usually unnecessary.
+
+## Understand when compaction happens
+
+iCode automatically calculates when to start compaction based on the maximum context window, maximum output tokens, and a safety margin for the current model profile. Set the maximum context window and maximum output tokens in the [model profile](./models.md) according to the model's capabilities and your task requirements. The "Compaction" tab does not provide a separate setting for when compaction starts.
+
+When the context is nearly full, iCode also lowers the output limit of the next request so that its input and output fit in the context window, leaving a small margin for error in its token estimate.
+
+The model service can still report that the context window is full, for example when the model's actual context window is smaller than the one set in the model profile. If the service's error names a limit smaller than the maximum context window in the model profile, the request fails at once and the error message names that limit: set the maximum context window in the model profile to that value or less. Otherwise, iCode compacts the context and sends the request once more by itself. If the service reports that the context window is full again, the request fails. When the model stops before writing anything because no room is left for its reply, the request can also fail. After such a failure, the next request first compacts the context to try to make room, for example when you click "Retry", send another message, or retry a workflow node. If it keeps happening, set the maximum context window in the model profile to the model's actual value.
+
+During compaction, iCode first summarizes older tool results and, if needed, removes older tool calls together with their results. If it still needs to free up space, it replaces completed turns in the current context with a compaction summary. If these steps are still insufficient, iCode generates Last Words for the current task to preserve the information needed to continue, then removes the current turn's tool calls, tool results, and intermediate content from the context supplied to the model, keeping the user's messages.
+
+These three steps serve different purposes: trimming older tool calls and results only reduces the space taken up by tool use; compaction summaries replace completed turns; Last Words help continue the current unfinished task.
+
+In the TUI, you can observe the following changes:
+
+- "Compacting conversation..." appears during compaction.
+- After compaction, compacted turns appear in gray in the sidebar message list. The conversation area shows a gray "Compressed" marker and a compaction summary at the corresponding position.
+- If Last Words were generated, you can expand the completed compaction card to view them.
+
+Compacted historical turns remain in the session. The agent can look up specific information from them when needed, without adding the entire conversation back to the current context.
+
+Compaction reduces context usage, but summaries cannot guarantee that every original detail is preserved. Put project rules that must be retained over time without omissions in [memory files](./memory.md), and write important work results to files in the working directory instead of leaving them only in the conversation.
+
+## Adjust compaction settings
+
+1. Enter `/agents compaction` in the input field to open the current agent's "Compaction" tab. To edit another agent, select it from the list on the left.
+2. Adjust "Last Words Max Output Tokens" as needed, entering an integer within the range allowed by the interface. The actual generation limit will not exceed the current model profile's maximum output tokens.
+3. To emphasize certain types of information in Last Words, fill in "Last Words Supplement (Optional emphasis)".
+4. Click "Save". The new settings take effect the next time this agent needs compaction.
+
+"Last Words Supplement (Optional emphasis)" specifies the information that Last Words should prioritize. For example, if you often use this agent to troubleshoot issues, you could enter:
+
+```text
+Prioritize reproduction steps, causes already ruled out, key logs, and hypotheses that still need to be tested.
+```
+
+Keep the supplement brief and focus on information needed to continue the task that could easily be lost during compaction.

chrys/app/tui/screens/guides/_docs/en/guides/configuration/memory.md

@@ -0,0 +1,48 @@
+# Configure memory
+
+This guide explains how to configure memory for the main agent.
+
+## Prepare memory content
+
+**Memory is added to the system prompt when the main agent loads.** iCode reads the memory files configured for the current main agent and provides their content to the agent as reference material. Memory content uses part of the model's context window and is sent to the model service with requests. Avoid including sensitive information such as secret keys or access tokens in memory.
+
+**Sub-agents do not load memory.** Sub-agents neither inherit the main agent's loaded memory nor load memory from their own agent profiles. Agent nodes in [workflows](../running/workflows.md), however, load the memory configured in their agent profiles.
+
+**Memory is suited to stable, reusable information.** iCode only loads memory files with the `.md` or `.txt` extension. Memory should contain information that can be reused across tasks, such as project conventions, background material, and frequently needed information. Keep it brief, clear, and up to date; instructions for a temporary task are better included directly in the current request.
+
+**The default agents already use AGENTS.md as memory.** The main agents included with iCode, such as Code Agent, load `AGENTS.md` from the working directory. To add general project instructions, start by maintaining this file. If it is not needed, remove its entry from the "Memory" tab.
+
+## Add a memory file
+
+1. Enter `/agents memory` in the input field to open the current agent's "Memory" tab. To configure another main agent, select it from the list on the left.
+2. Click "+ Add File" in the "Files" section.
+3. Enter a path, or use "Browse" to select a `.md` or `.txt` file. With "Workspace relative" selected, enter a relative path, such as `AGENTS.md` or `docs/context.md`; otherwise, enter an absolute path.
+
+    > **Note:** Relative paths are resolved against the current working directory when memory loads, rather than the directory where the agent profile was created. This lets the same agent load each project's own `AGENTS.md`. Relative paths must stay inside the working directory; use an absolute path for files outside it.
+4. Click "Save", then close the agent configuration window.
+
+## Add a memory folder
+
+To load a set of reference files, click "+ Add Folder" in the "Folders" section. With "Workspace relative" selected, enter a relative path; otherwise, enter an absolute path. When finished, click "Save", then close the agent configuration window.
+
+iCode first loads the `.md` and `.txt` files directly in the folder, then scans subfolders one level at a time. For each configured folder, it scans at most two levels of subfolders and loads at most 100 files. If an important file may fall outside these limits, add it separately in the "Files" section.
+
+## Load and reload memory
+
+If the same file is both added individually and discovered in a folder, it is loaded only once. The combined content from all memory sources is limited to 35,000 tokens. Individually added files load first, then folders. Once a file would exceed the limit, that file and all remaining files are skipped, and iCode displays a warning.
+
+After switching working directories or changing the current agent profile, iCode reloads memory using the new paths.
+
+iCode does not monitor loaded memory files for changes. After editing a file directly on disk, reload the main agent for the changes to take effect. For example, restart iCode, switch working directories, modify and save the current agent profile, or switch to another main agent and then switch back.
+
+## Verify that memory is loaded
+
+Enter `/runtime` in the input field, or click the file count at the right end of the status bar above the input field, to open "Runtime Details". Switch to the "Files" tab. This page lists the files actually loaded, grouped by their configured source. If the expected files appear in the list, memory has loaded.
+
+If an expected file is missing, check the following:
+
+* Does the path exist, and does the file have the `.md` or `.txt` extension?
+* For a relative path, is the file in the current working directory?
+* Does the entry type match the actual path? A file entry must point to a file, and a folder entry to a folder.
+* Is there a warning that the content exceeds 35,000 tokens or that some files were skipped?
+* Did you click "Save" after changing the configuration?

chrys/app/tui/screens/guides/_docs/en/guides/configuration/models.md

@@ -0,0 +1,158 @@
+# Configure models
+
+A model profile contains the information needed to connect to a model service. This guide explains how to create, clone, edit, switch, and delete model profiles in the terminal user interface (TUI). Once saved, profiles let you switch between tasks without entering connection parameters again.
+
+## Open the model configuration window
+
+Open the "Model Configuration" window in any of these ways:
+
+- Press **F4**.
+- Click `f4 Models` at the bottom of the interface.
+- Enter `/models` in the input field.
+
+The list on the left shows existing model profiles. The form on the right shows the currently selected profile.
+
+While a task is running, the "Model Configuration" window opens in read-only mode. You cannot create, edit, or delete profiles. Wait for the task to finish before changing the configuration.
+
+## Manage model profiles
+
+### Create a model profile
+
+1. Click "New".
+2. Enter a "Profile Name" of your choice, such as `My Model`.
+3. In the "Model Options" section, select the "Provider" and "API Style". Only OpenAI and DeepSeek (OpenAI) provide an API Style option. Before configuring it, check the model service's documentation for supported APIs and follow its recommendation when choosing "Chat Completions" or "Responses". If the service supports only one API, select its corresponding style; if it supports both, choose according to the service's recommendation or your needs.
+4. Enter the model ID in "Model" and, as required by the model service, fill in "Base URL" and "API Key".
+5. Set "Max Context Window" and the "Max Output Tokens" field according to the provider's documentation.
+6. Adjust "Streaming", "Vision Model", and "Connection Options" as needed. "Streaming" is on for a new profile.
+7. Click "Save".
+
+**Notes:**
+
+- Clicking "New" immediately creates and saves a blank profile. You must click "Save" for any subsequent entries or changes to take effect. Closing the window does not delete the blank profile you created.
+- The profile name identifies the model profile in the interface and is not sent to the model service. It cannot be empty or duplicate an existing name (case-insensitive). Names can contain Chinese characters, spaces, letters, numbers, and common symbols.
+- A profile with missing required information, such as the model ID or token limits, does not appear in the model selection list.
+- With "Streaming" on, the reply appears as the model writes it. A long reply can take longer than "HTTP Read Timeout (s)" as long as the model service keeps sending it; the timeout applies only when the service stops sending for that long. Profiles that an earlier iCode version saved with "Streaming" unchecked now stream too; to turn it off, uncheck "Streaming" and save again. If you go back to an earlier iCode version, it treats profiles that this version saved with "Streaming" on as not streaming.
+- With "Vision Model" on, images are sent to the model in PNG, JPEG, GIF, or WebP format. An image a tool returns in another format is sent as a short note that the image was left out, and the conversation continues.
+- If no usable model profile existed before, the new profile automatically becomes the current model profile after you save it and close the window. If another model profile is already in use, saving a new profile does not automatically switch models.
+- To set reasoning effort, prompt caching, or other request fields, use "Chat Options" in the "Extra Options" section. See [Chat Options](./chat-options.md), which also lists settings for common model services. When a save makes a profile a Claude profile on the Anthropic protocol without a cache setting, iCode offers to add one.
+
+### Provide an API key through an environment variable
+
+An API key entered directly is saved locally in the model profile file.
+
+To read the key from an environment variable, enter the following in the "API Key" field:
+
+```text
+{{PROVIDER_API_KEY}}
+```
+
+Replace `PROVIDER_API_KEY` with the name of the environment variable that holds the key. Make sure the variable is set before starting iCode. Environment variable names can contain only letters, numbers, and underscores, and cannot start with a number.
+
+### Clone a model profile
+
+Clone an existing profile when you need another profile with mostly the same parameters. For example, you might use a different model ID from the same provider, or set different context and output limits for the same model.
+
+1. Select the model profile to copy in the list on the left.
+2. Click "Clone".
+3. iCode creates and selects a copy containing all fields from the original profile, and generates a unique name for it.
+4. Edit the profile name and any fields you want to change.
+5. Click "Save".
+
+Clicking "Clone" saves the copy immediately, but does not switch the current model to the copy.
+
+### Edit a model profile
+
+1. Select a model profile in the list on the left.
+2. Edit the fields you want to change.
+3. Click "Save".
+
+If you edit the model profile currently in use, the updated configuration applies to subsequent requests after you save it and close the configuration window.
+
+### Claude thinking settings
+
+Claude Opus 5.5, Fable 5.1 and Sonnet 5.5 tie the thinking they return to the conversation before it. When that earlier conversation changes, for example after iCode compacts the context, the model service may refuse to read that thinking back. When one of these models uses adaptive thinking (`"thinking": {"type": "adaptive"}` in ["Chat Options"](./chat-options.md#anthropic)) at Anthropic's own address, iCode asks the service to leave out thinking that no longer matches instead of refusing the request. The model then sees less of its earlier reasoning, but the request goes through. On accounts where the service would not otherwise check this, the request makes it check, so such thinking is left out there too.
+
+To change this, open the profile's file in the `models` folder of the iCode configuration directory (`~/.chrys/models/` on macOS and Linux, `%APPDATA%\chrys\models\` on Windows; the file's `name:` line shows the profile name), add a `thinking_block_binding` line with one of these values, and restart iCode:
+
+| Value | What iCode asks the service |
+| --- | --- |
+| `auto` (default) | As described above. |
+| `drop_block` | To leave out thinking that no longer matches, at any address and with any model, when thinking is adaptive or has a fixed budget. |
+| `error` | To refuse a request with thinking that no longer matches, at any address and with any model, when thinking is adaptive or has a fixed budget. |
+| `off` | Nothing. A `block_binding` you write into `thinking` in "Chat Options" is still sent as written. |
+
+If the service still refuses a request because of thinking that no longer matches, iCode sends the request once more without the earlier thinking it read back, and doesn't send that thinking again. This costs one extra request, and the model no longer sees that earlier reasoning. With `error`, iCode reports the refusal instead.
+
+With fixed-budget thinking (`"type": "enabled"`) at Anthropic's own address, iCode also turns on thinking between tool calls, except on Claude Haiku 4.5 and Claude Opus 4.6, which don't support it in that mode. To turn this off, add the line `auto_interleaved_thinking: false`.
+
+Saving the profile in the "Model Configuration" window keeps these lines.
+
+### Delete a model profile
+
+Deleting a profile removes its local model profile file and **cannot be undone in iCode**. Once you are sure you no longer need the profile:
+
+1. Open the "Model Configuration" window.
+2. Select the profile to delete in the list on the left.
+3. Click "Delete".
+4. In the confirmation window, check the profile name again, then click "Delete".
+
+iCode keeps at least one model profile, so "Delete" is unavailable when only one remains. If you delete the profile currently in use, iCode automatically switches to another selectable profile after you close the configuration window.
+
+## Switch and verify model profiles
+
+### Switch the current model profile
+
+You can switch model profiles by clicking the model profile name or using the input field.
+
+To switch by clicking the model profile name:
+
+1. Click the model profile name in the status bar above the input field to open the model selection window.
+2. Click a model profile, or select one with the Up and Down arrow keys and press Enter to confirm.
+
+To switch quickly from the input field:
+
+1. Enter `$` in the input field. The model profile list appears above it.
+2. Continue typing the profile name to filter the results.
+3. Use the Up and Down arrow keys to select a model profile, then press Enter to confirm.
+
+After switching, the status bar shows the new model profile name. The profile currently in use appears in gray in the list, with a hollow circle before its name. Profiles with missing required fields do not appear in the list.
+
+The conversation continues with the new profile. Some model services return the model's reasoning in a form only that service can read back, such as Claude's thinking or OpenAI's encrypted reasoning. If the new profile sends requests to a different service address, iCode leaves that earlier reasoning out of its requests. Your messages, the model's replies and the results of tools iCode ran are still sent; results of tools the model service ran itself in the same step may be left out too. Switch back to a profile with the original address, and that reasoning is sent again. Reasoning saved by earlier iCode versions is still sent as before.
+
+If the model profile name in the status bar is grayed out, the current agent is bound to a specific model profile, and clicking it only shows a notice about the binding. In this case, entering `$` does not display the model profile list either. You must first [change the agent's model settings](./agents.md#set-the-model-an-agent-uses) before you can switch model profiles. You also cannot switch while the agent is running.
+
+### Verify a model profile
+
+After switching models, submit the following in the input field:
+
+```text
+Hello
+```
+
+iCode should respond with a greeting. If the model service returns an error, first check the model ID, base URL, API key, and other model profile settings.
+
+If the error persists, compare the symptoms against the following cases:
+
+- **The error message contains `The Chat Completions client supports only n=1`**: With the Chat Completions style, iCode processes only one response per request and does not support multiple candidate responses, so the `n` parameter must be omitted or set to the integer `1`. Remove the value or set it to `1` in the profile's ["Chat Options"](./chat-options.md), including when it was set indirectly through `extra_body`.
+- **The response has an `HTTP 200` status but is not a valid model reply**: for example a `text/html` Content-Type with an error page, an error JSON body, or an empty body. This means a gateway or proxy wrapped a backend error as a successful response; check that the selected API style matches the model service address, and review the proxy route.
+- **The model service's content filter stopped the reply**: iCode does not retry the request, and it does not run any tools that a filtered or refused reply asked for. Rephrase the request.
+- **With the Responses style, the model service reports that the reply failed**: iCode shows the service's error. It retries only errors that may pass on another attempt, such as a server error or a rate limit; it does not retry a request the service rejects, such as one with an image it can't read or one over the account's quota. A streamed reply that stops before it is finished is retried the same way. A request over the context window is the exception: see [If iCode can't reach the model service](#if-icode-cant-reach-the-model-service). iCode does not retry when the service already ran a tool that may have changed something for the failed reply, such as an MCP call, so that the tool does not run twice. If a service never says whether a streamed reply is finished, iCode keeps what it received and writes a warning to the log.
+- **With the Anthropic protocol, a streamed reply stops before it is finished**: iCode retries the request and does not run the tools that the interrupted reply asked for. As with the Responses style, it does not retry when the service already ran a tool that may have changed something, such as an MCP call.
+- **Streamed replies sometimes stop partway without an error**: some services using the Chat Completions style end a stream without saying that the reply is finished. iCode keeps such a reply. To have iCode treat it as an interrupted reply and retry, open the profile's file in the `models` folder of the iCode configuration directory (`~/.chrys/models/` on macOS and Linux, `%APPDATA%\chrys\models\` on Windows; the file's `name:` line shows the profile name), add the line `stream_requires_finish_reason: true`, and restart iCode. Saving the profile in the "Model Configuration" window keeps this line.
+- **Requests fail with "Streaming" on, and the model service or gateway doesn't support streaming**: uncheck "Streaming" in the model profile and save. If you edit the profile's file instead, add the line `stream: false` and restart iCode. Turning streaming off helps only when the service can't stream.
+
+### If iCode can't reach the model service
+
+When iCode can tell why a model request failed, it says so in plain words, with the original error text below it; a paused sub-agent's card shows both as well. While iCode retries, the retry notice shows only the plain-words message. If the device running iCode doesn't seem to have a network connection, iCode says so as well; check that first.
+
+| The message says | What to check |
+| --- | --- |
+| Can't resolve the address | Your network connection and DNS. If the address is wrong, fix the base URL in the model profile. |
+| The host refused the connection | The address and port in the base URL, and that the model service is running. |
+| Connecting or waiting for a response timed out | Your network, firewall, or VPN. |
+| Can't connect to the proxy | That the proxy is running and set up correctly. To connect without the proxy, turn on **Bypass proxy** in the model profile. |
+| The proxy requires authentication | The proxy's user name and password. |
+| Couldn't establish a secure connection | On a corporate network, the proxy's certificate setup. |
+| The API key is invalid or lacks access | The API key in the model profile. |
+| The request exceeds the model's context window | That the context window in the model profile matches the model's real one. With context compaction on, iCode compacts the context and sends the request once more; this error appears only if that also fails. See [Configure context compaction](./compaction.md). |
+| The model profile's maximum context window is larger than the server's limit | Set "Max Context Window" in the model profile to the server's limit that the message names, or less, and save. |