iCode-TUI 0.29.1__py3-none-any.whl

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

@@ -0,0 +1,210 @@
+# Configure iCode settings
+
+iCode settings control the interface appearance, default agent, sessions, tools, notifications, and some security options. This guide explains how to configure these basics in the terminal user interface (TUI) and check when changes take effect.
+
+To edit `settings.yaml` directly or configure settings through environment variables, see the [iCode settings file reference](../../reference/settings.md) for file locations, settings keys, and source precedence.
+
+## Settings dialog
+
+### Open the Settings dialog
+
+The Settings dialog can only be opened while the agent is idle.
+
+Open **Settings** in any of these ways:
+
+- Press **F10**.
+- Click `f10 Settings` at the bottom of the interface.
+- Type `/settings` in the input field, press **Space** or **Enter** to show the tab list, then select a tab.
+
+You can also open a tab directly with `/settings <tab>`:
+
+| Tab | `<tab>` | Main settings |
+| --- | --- | --- |
+| General | `general` | Appearance and input |
+| Models & Agents | `models` | Default agent, model roles, and request retries |
+| Security | `security` | Approval, project trust, diagnostics, and telemetry |
+| Sessions | `sessions` | Session titles, storage, and rollback |
+| Tools | `tools` | File search, web tools, agent questions, tool detail display, and workspace notices |
+| Notifications | `notifications` | Notification toggles, delivery methods, and events |
+
+For example, enter `/settings security` to open the **Security** tab directly.
+
+### Save changes and check when they take effect
+
+Changes are saved automatically as you make them. Press **Enter** to submit a change in a text field; it is also submitted when you move to another setting or close the dialog. Closing the dialog with **Esc** does not undo changes already submitted.
+
+The status message at the bottom right of the Settings dialog explains when changes take effect. If changes have different pending application times, the corresponding messages appear together.
+
+| Status message | When changes take effect |
+| --- | --- |
+| "Changes are saved as you make them" | Changes are saved, with no changes waiting for the dialog to close or a restart |
+| "Changes apply on close (reload)" | After you press **Esc** to close **Settings** |
+| "Changes apply when the current turn ends" | Replaces "Changes apply on close (reload)" while a turn or workflow is running; changes apply after you close **Settings** and the run ends |
+| A message showing how many changes apply after restart | Changes are saved, but you must quit and restart iCode for them to take effect |
+
+The "Takes effect" column in the following tables describes each setting's usual behavior.
+
+## Settings
+
+### General
+
+#### Appearance
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Theme | Changes the TUI theme. To adjust colors or create a custom theme, see [Customize themes](themes.md). | Immediately |
+| UI Language | Changes only iCode interface text, not conversation content, the model's output language, or existing records. You can also switch the interface language with `/language`. | Immediately |
+
+#### Input
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Save prompt history | Saves submitted input across sessions for reuse. When no other dialog covers the main screen, press **Ctrl+R** to open the prompt history list above the input field. Click an entry, or select it with the up and down arrow keys and press **Enter**, to copy the prompt into the input field. The history file, `prompt_history.jsonl`, is stored in `~/.chrys/` on macOS and Linux, or `%APPDATA%\chrys\` on Windows. Turning this setting off does not delete the file; iCode stops reading it, and **Ctrl+R** shows "No results". Re-enable the setting and restart iCode to read the file's entries again. To clear the history, delete the history file; deletion cannot be undone. | After restart |
+
+### Models & Agents
+
+This tab selects existing agent or model profiles; it does not edit them. For those operations, see [Configure agents](./agents.md) and [Configure models](./models.md).
+
+#### Agent
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Default agent | Determines only the default agent for the next TUI launch; it does not affect the current session. | Saved immediately; applies at the next launch |
+
+#### Model roles
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Session title model | Defaults to "Use active model". Used only when [Auto-generate session titles](#sessions) is enabled. | On close |
+| Approval judge model | Defaults to "Use active model". Used only in [automatic approval mode](./approval.md#understand-the-three-approval-modes). | On close |
+| Buddy model | Defaults to "Use active model". Used for the Buddy companion feature. | On close |
+
+#### LLM
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Max transient retries | Sets the maximum number of automatic retries for errors that may resolve shortly, such as temporary network interruptions, request timeouts, temporary model service unavailability, or server rate limits. It does not retry problems that waiting cannot resolve, such as invalid model configuration or request parameters. A higher limit gives temporary failures more chances to recover; if retries keep failing, it also increases the wait and the number of model requests before the final failure. Leave blank to use the TUI default; set to `0` to disable automatic retries. This setting does not cover the one resend after iCode compacts a full context window. | On close |
+
+### Security
+
+#### Approval
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Default approval mode | Sets the default approval mode for the next iCode launch; it does not affect the current session. Only `manual` and `auto` are offered; to bypass approval in the current session, use `/approval bypass`. For switching the current session's mode and the differences between modes, see [Configure approval modes](./approval.md). | Saved immediately; applies at the next launch |
+| Show the approval dialog only when Auto-Review flags a call | On by default. In automatic mode, no dialog opens while the approval judge model evaluates a call, and calls it judges safe run without one; the dialog opens only for flagged calls or when evaluation fails. When disabled, the dialog opens at once and shows **Evaluating**, so you can decide before evaluation finishes. Requests already waiting keep the behavior they started with. See [Handle approval requests in the TUI](./approval.md#handle-approval-requests-in-the-tui). | Immediately |
+
+#### Project trust
+
+Project settings, hooks, and skills come with the repository you open, so all three are off by default. When the working directory has any of them that are not loaded, iCode shows a notice naming the setting to turn on.
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Load project settings | Reads `.chrys/settings.yaml` in the current working directory and applies its project settings, such as request retries, automatic session titles, and working directory notices. See [Project-level settings](../../reference/settings.md#project-level-settings) for allowed keys and override restrictions. | On close |
+| Load project hooks | Controls whether iCode loads hooks from `.chrys/hooks` in the current working directory; it does not affect user-level hooks. To create and validate hooks, see [Configure and write hooks](../extensions/hooks.md). For the complete configuration fields, see the [Hooks configuration reference](../../reference/hooks.md). | On close |
+| Load project skills | Controls whether iCode loads skills from `.agents/skills` in the current working directory; it does not affect your own skills directories. See [Install and use skills](../extensions/skills.md). | On close |
+
+#### Diagnostics
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Capture raw HTTP traffic | Records model requests and responses for troubleshooting. **Logs may contain API keys, complete prompts, and model responses in plain text.** Enable this only while troubleshooting and protect the log files. When finished, turn it off promptly and restart iCode. The log file, `llm_raw_http.jsonl`, is stored in the current session folder; see [Find the session ID and storage location](../daily-use/sessions.md#find-the-session-id-and-storage-location). | After restart |
+
+#### Telemetry
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| OpenTelemetry export | Enables telemetry to record traces, logs, and metrics. When disabled, the other two settings do not cause iCode to save or send telemetry. | After restart |
+| Telemetry endpoint | Sets the address of the collector that receives telemetry. With no endpoints configured through settings or environment variables, only traces and logs are saved locally. Configuring any endpoint stops local storage, with no local fallback if export fails. | After restart |
+| Include sensitive data in telemetry | Additionally records prompts, model responses, tool arguments, and tool results in both local storage and remote export. Tool duration metrics may also contain tool arguments. Before enabling this, confirm where the data will go and who can access it. | After restart |
+
+For telemetry data types, storage locations, endpoint precedence, and collector connections, see the [OpenTelemetry reference](../../reference/opentelemetry.md).
+
+### Sessions
+
+#### Titles
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Auto-generate session titles | Makes additional model requests to generate titles based on the conversation. **Once you set a session title manually, iCode stops updating that session's title automatically.** To set or clear a manual title, see [Change a session title](../daily-use/sessions.md#change-the-session-title). | On close |
+
+#### Location
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Session storage root | Determines where iCode saves sessions. Leave blank to use the default location; sessions are stored in the root's `sessions` subdirectory. "In use" shows the `sessions` directory used by the current launch. After changing the root, restart iCode to use the new location; until then, sessions continue to be saved in the directory shown under "In use". **After restart, new sessions are saved in the new directory, but existing session files are not moved automatically.** To continue using existing sessions at the new location, see [Migrate session storage](../daily-use/sessions.md#migrate-session-storage). | After restart |
+
+#### Rollback
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Rollback snapshots to keep | Sets the maximum number of rollback snapshots kept per session. iCode creates a snapshot before it starts processing each newly submitted prompt; older snapshots are deleted automatically when the limit is exceeded. Snapshots are stored in the session folder's `snapshots` subdirectory. Keeping more snapshots lets `/rollback` return to more earlier session states, but uses more disk space. | On close |
+
+### Tools
+
+#### File search
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Respect .gitignore | Applies Git ignore rules to grep and glob searches. When off, hidden paths are still skipped, and other ignore files such as `.ignore` still apply. | On close |
+
+#### Web search
+
+These settings apply to agents that include the web tools, which are off by default. See [Configure web tools](./web-tools.md). An agent profile that sets its own mode, result count, or timeout overrides these values for that agent. Project settings cannot change them.
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Web search mode | `auto` (default) lets agents that include web search use it. An agent that configures no search provider sends its queries to Exa's public search endpoint, a third-party service; see [Where web requests go](./web-tools.md#where-web-requests-go). `off` turns web search off. An agent profile that sets its own mode uses that mode instead. | On close |
+| Results per web search | Number of results a search returns when the agent does not ask for a number, from 1 to 20. The default is 8. | On close |
+| Web fetch mode | `on` (default) lets agents that include web fetch read pages by URL. `off` turns web fetch off. An agent profile that sets its own mode uses that mode instead. | On close |
+| Web proxy URL | An `http://` or `https://` proxy used only by web tools, without credentials or a path. Leave blank to connect directly. Web tools ignore proxy environment variables such as `HTTP_PROXY`. | On close |
+| Web proxy DNS | Where host names are resolved when a proxy is set. `local` (default) resolves them on this device and checks every address before connecting. `remote` sends the host name to the proxy, as fake-IP proxies require, and leaves blocking private addresses to the proxy; see [Use a fake-IP proxy](./web-tools.md#use-a-fake-ip-proxy). It has no effect without a web proxy URL. | On close |
+| Custom search endpoints | A JSON array of grants for custom search endpoints used in agent profiles, each written as `{"url": "...", "credential_env_names": ["..."]}`. | On close |
+| Web search private-network origins | A JSON array of origins that web search may reach even though they resolve to private addresses, such as `["http://127.0.0.1:8080"]` for a local SearXNG. | On close |
+| Web search plain-HTTP origins | A JSON array of origins that web search may reach over plain `http://`. | On close |
+
+Values are checked with the same rules the web tools use before they are saved, and a rejected value says what is wrong. Clear a list field to empty the list. The web search timeout, the web fetch timeout and token budget, and the web fetch origin lists are not shown in the dialog; set them in `settings.yaml` (see [Web tools](../../reference/settings.md#web-tools)).
+
+#### Ask user
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Show questions in the chat | When enabled, the agent's questions appear directly in the conversation. When disabled, they appear in a popup. | On close |
+| Ask-user timeout (seconds) | Sets how long iCode waits for an answer. When left blank, it uses the default value shown in the TUI. If no answer arrives before the timeout, iCode returns a timeout result to the agent. Set to `0` to wait until an answer arrives or the task is interrupted. When using an ACP client such as an IDE plugin, `ask_user` has no server-side time limit by default; to set one, use `--ask-user-timeout` when starting the ACP server. | On close |
+
+#### Display
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Expand tool details by default | When enabled, new tool groups are expanded by default. When disabled, they are collapsed and show only a summary and the current operation. You can click a tool group at any time to expand its details. | Immediately |
+
+#### Workspace notice
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Workspace change notices | When processing a newly submitted prompt, iCode gives the agent a summary of working directory file changes since the previous prompt was submitted. This includes changes made by the current session's agent and its sub-agents, as well as changes made manually, by other programs, or by other iCode sessions. | On close |
+
+### Notifications
+
+#### General
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Enable Notifications | The master switch for event notifications. When disabled, no desktop popups or sounds are sent, but delivery and event selections are preserved and still apply when notifications are re-enabled. | Immediately |
+
+#### Delivery
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Desktop popup, Sound | Can be enabled separately. If both are disabled, no notifications are delivered, even when the master switch and event switches are enabled. | Immediately |
+| Suppress while iCode is focused | Prevents desktop popups and sounds while iCode is in the foreground. | Immediately |
+| Test | Sends a test notification using the current delivery settings, regardless of the master switch, event switches, or focus state. It only checks whether desktop popups and sound work; enable at least one of "Desktop popup" or "Sound" before testing. | Immediately |
+
+#### Events
+
+| Setting | Effect and notes | Takes effect |
+| --- | --- | --- |
+| Approval required | Controls whether a notification is triggered when approval is required. | Immediately |
+| Agent needs input | Controls whether a notification is triggered when the agent needs input. | Immediately |
+| Agent finished | Controls whether a notification is triggered when the agent finishes a task. | Immediately |
+| Agent error | Controls whether a notification is triggered when the agent encounters an error. | Immediately |

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

@@ -0,0 +1,61 @@
+# Customize themes
+
+Use the theme editor to adjust colors in the terminal user interface (TUI) and preview the results directly. This guide covers editing an existing theme, saving your own theme, undoing changes, and deleting themes.
+
+Color changes are previewed live but are not saved automatically. Save your changes through the editor's “Save” dialog to write them to a theme file and keep them for the next launch. To write YAML files directly or look up color fields, see the [Theme file reference](../../reference/themes.md).
+
+## Open the editor
+
+1. Press **F9**, or click `f9 Themes` in the footer, to open the theme list.
+2. Select “Edit themes…” at the bottom of the list to open the theme editor beside the main interface.
+3. Use the dropdown at the top of the editor to choose a theme to edit. This changes the editing target without changing the applied theme selection.
+
+The current conversation remains visible beside the editor, so you can see how colors affect text, tool cards, and other interface elements.
+
+While the editor is open, switching the applied theme through F9, `/theme`, or the settings window is restricted. Use the editor's dropdown to choose another theme to edit. To change the theme for everyday use, close the editor first.
+
+## Adjust and preview colors
+
+The editor groups colors under headings such as `Colors`, `Buttons`, and `Borders`. Each color is identified by its field name, such as `primary` (the main color) or `background` (the overall background).
+
+1. Click a color swatch to open the color picker.
+2. For non-ANSI themes, choose or enter a color under `RGB / HSV`, or switch to “256 colors” to select a color. ANSI themes offer `ANSI` and “256 colors” modes. The actual appearance of ANSI colors depends on your terminal palette.
+3. The main interface previews your adjustments live. Click “Confirm” to keep the change in the editor. Click “Cancel” or press **Esc** to discard changes made during this visit to the color picker.
+
+Background and panel colors (`background`, `surface`, `panel`, and `boost`) must remain opaque, so the color picker does not offer transparency controls for these fields.
+
+## Undo and reset
+
+Choose an action based on how much you want to undo:
+
+| Action | Result |
+| --- | --- |
+| “Restore” in the color picker | Restores the value from when you opened the picker |
+| “Undo” / “Redo” in the editor | Undoes or redoes confirmed edits |
+| The “↺” reset button beside a changed field | Restores that field to its value when the theme was loaded into the editor |
+| “Reset all” | Restores all fields to their values when the theme was loaded into the editor |
+
+## Save a theme
+
+1. Click “Save” in the editor.
+2. Enter a theme name in the “Save theme” dialog.
+3. Click “Save”. Once the success notification appears, the theme is applied immediately and the selection is remembered.
+
+Theme names must follow these rules:
+
+* Use no more than 100 characters. Start with an ASCII letter or digit, and use only ASCII letters, digits, dots, underscores, and hyphens. Do not end the name with a dot.
+* Do not include a `.yaml` or `.yml` extension.
+* When editing a built-in theme, save under a new name. When editing a user theme, an exact match with the original name (including letter case) overwrites the original file; a new name saves a separate file. Duplicate-name checks are case-insensitive.
+* Do not use Windows device names such as `CON`, `NUL`, `COM1`–`COM9`, or `LPT1`–`LPT9`. Names formed by adding a dot and suffix to these names, such as `CON.dark`, are also prohibited.
+
+## Close the editor or switch editing targets
+
+If there are unsaved changes when you select another theme to edit or click “Close”, you will be asked whether to discard them. Choose “Discard” to discard the changes and continue, or “Cancel” to keep editing.
+
+When the editor closes, the interface returns to the currently applied theme.
+
+## Delete a user theme
+
+“Delete” removes the theme file and any unsaved changes to that theme. Built-in themes cannot be deleted.
+
+Select a user theme at the top of the editor and click “Delete”. Check the theme name in the confirmation dialog, then click “Delete” again. Deleting the currently applied theme switches iCode to the default theme, `chrys`.

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

@@ -0,0 +1,60 @@
+# Configure tools
+
+Built-in tools let agents access files, search content, execute shell commands, and use other iCode features. This guide explains how to enable or disable built-in tool kinds for an agent in the terminal user interface (TUI).
+
+Tools provided by MCP servers are not built-in tools and must be managed separately in [MCP configuration](../extensions/mcp.md).
+
+For the tool kind values and individual tool names used in agent configuration and hooks, see [Tool kinds and names](../../reference/tool-kinds-and-names.md).
+
+## Open tool configuration
+
+Enter `/agents tools` in the input field to open the current agent's "Tools" tab. To configure another agent, select it from the list on the left.
+
+## Select built-in tools
+
+Each option corresponds to a kind of built-in tool. Enable the kinds the agent needs for its tasks:
+
+| Tool kind | Available operations | When to enable |
+| --- | --- | --- |
+| Filesystem Read | Read files and view images (PNG, JPEG, or WebP) | Enable when the agent needs to analyze project files; the agent can use the image viewing tool only if the selected model supports image input |
+| Filesystem Write | Create, overwrite, and precisely edit files | Enable only when the agent needs to modify files |
+| File search | Search file contents or find files by name pattern | Enable when the agent needs to locate code and files in a project |
+| Web search | Find online URLs and summaries; uses Exa (exa.ai) unless the agent profile names other providers | Enable when the agent needs current external information, such as documentation or release details. Queries go to that outside service and can carry details from your conversation, so mind your data and privacy |
+| Web fetch | Read the text of a page by URL | Enable when the agent needs to read pages it finds or that you point it to |
+| Shell | Execute terminal commands in a subprocess | Enable when the agent needs to run builds, tests, or other commands |
+| Ask User | Request additional information or ask the user to make a choice during a task | Suitable for TUI and ACP sessions; headless CLI mode (`icode run`) does not provide this tool to the agent |
+| Sleep | Pause a task for up to 3600 seconds; the TUI displays a countdown that can be skipped | Enable when the agent needs to wait before continuing a task |
+| Document Converter (PDF, Office) | Convert PDF, DOCX, PPTX, XLSX, and XLS files to Markdown; if the current model supports image input and the agent has "Filesystem Read" enabled, images can also be extracted from PDF, DOCX, and PPTX files for the agent to view; XLSX and XLS conversion includes only text and tables | Enable when the agent needs to read these document formats |
+| Todo List | Track tasks with multiple steps using a live checklist | Suitable for tasks with many steps that need visible progress tracking |
+
+Check the kinds to enable, uncheck those you do not need, then click "Save".
+
+If you modify the agent used by the current session, the new tool configuration takes effect starting with subsequent requests.
+
+Web search is off in every agent shipped with iCode, and it is separate from File search, which only searches local files. Web fetch is a separate switch. With no search provider configured, queries go to Exa's public search service. Before you turn it on, see [Configure web tools](./web-tools.md) for where requests go, approval, and network limits.
+
+## Use the Ask User tool
+
+The Ask User tool requests additional information or asks the user to make a choice during a task. A single request can contain 1 to 5 questions, including single-select, multi-select, and free-text questions.
+
+By default, questions appear in an ask-user dialog. If the dialog obscures conversation content you need to review, click **Answer Inline** to show the current question in the conversation instead; this applies only to the current question. If you want future questions to appear in the conversation by default, enable **Show questions in the chat** in [Configure iCode settings](./settings.md).
+
+In the TUI, multiple questions appear in the same question dialog. You can switch between question tabs, fill in the answers, and review all answers on the summary page before submitting them together.
+
+The wait time for an answer is controlled by the **Ask-user timeout (seconds)** setting in [Configure iCode settings](./settings.md).
+
+## Configure tools as needed
+
+Tool configuration determines which capabilities an agent can use. For a specialized agent, enable only the tool kinds needed to complete its tasks.
+
+For example:
+
+- An agent that only analyzes code can enable "Filesystem Read" and "File search" without enabling "Filesystem Write" or Shell.
+- An agent that modifies code and runs tests typically needs "Filesystem Read", "Filesystem Write", "File search", and Shell.
+- When working with an untrusted project, use caution when enabling Shell and "Filesystem Write".
+
+Enabling a tool only makes that capability available to the agent; operations that require approval are still handled according to the current approval mode. For details on approval requests and how to confirm them, see [Configure approval modes](./approval.md).
+
+For filesystem, search, and Shell tools, relative paths are resolved against the current [working directory](../daily-use/workspaces.md), and shell commands run in the current working directory by default. Switching working directories changes the base for these relative paths and the default working directory for commands. The working directory is the default location for operations; it does not restrict tools to paths within it. Whether an operation can run also depends on its tool arguments, whether approval is granted when required, and the permissions of the system user running iCode.
+
+When a command prints a lot, the agent sees the beginning and the end of its output, and iCode saves the output in the session directory when it can. If a command prints more than 32 MiB, iCode keeps only the first and last parts; the middle is not saved anywhere, and the result tells the agent how much was left out.

chrys/app/tui/screens/guides/_docs/en/guides/configuration/web-tools.md

@@ -0,0 +1,286 @@
+# Configure web tools
+
+The web tools let an agent look things up on the internet: `web_search` finds pages and returns their URLs and summaries, and `web_fetch` reads the text of a page at a known URL. This guide explains how to turn them on for an agent, where their requests go, and how to choose a search provider and limit network access.
+
+**Web tools are off by default.** No agent shipped with iCode (Code, QA, Explore, or General) includes them, so iCode sends no search queries and fetches no pages until you enable the tools for an agent.
+
+`web_search` is separate from the "File search" tools (`grep` and `glob`), which only search files on your machine.
+
+## Turn on web tools
+
+### Add the tools to an agent
+
+Enter `/agents tools` in the input field, select the agent, check **Web search**, **Web fetch**, or both, and click "Save". Both are available straight away. Web search sends its queries to Exa (exa.ai) unless you choose another provider, so read [Where web requests go](#where-web-requests-go) before you turn it on.
+
+To do the same in an agent profile, add the tool kinds to `tools.builtins`:
+
+```yaml
+tools:
+  builtins: [filesystem.read, search, web_search, web_fetch]
+```
+
+Web tools belong to each agent separately. A sub-agent such as General gets them only if its own profile includes them. To add them to a built-in agent, edit and save it in the TUI; iCode then saves your own copy of that agent (see [Override built-in agents](../../reference/agent-profile.md#override-built-in-agents)).
+
+### Turn a web tool off
+
+To turn a tool off without removing it from your agents, press **F10** to open **Settings**, select the **Tools** tab, and set **Web search mode** or **Web fetch mode** to `off` in the **Web search** section. **Web search mode** defaults to `auto` and **Web fetch mode** to `on`, so an agent that includes a tool can use it.
+
+These settings apply only to agents whose profile does not set a mode. A mode set in an agent profile takes precedence, so a profile can turn a tool off for that agent alone, and a profile that sets `on` keeps the tool even when the setting is `off`:
+
+```yaml
+tools:
+  web_fetch:
+    mode: off
+```
+
+Changes in **Settings** apply when you close the dialog. Changes to an agent's tools apply from the next request.
+
+## Where web requests go
+
+With `web_search` turned on and no provider configured, the default mode `auto` sends your search queries to **Exa's public, anonymous search endpoint at `https://mcp.exa.ai/mcp`**. Exa is a third-party search service. No API key or account is needed. iCode sends only what the agent searches for and how many results it wants, not your files or the conversation itself; the agent writes the queries, so they can include details from your task. The service has free-tier rate limits and can be unavailable. To send queries somewhere else, [choose a search provider](#choose-a-search-provider); to stop searching, set the mode to `off`.
+
+`web_fetch` requests each URL directly from the website that hosts it, or through the [web proxy](#control-network-access) if you set one. Requests identify themselves with the user agent `Chrys-Web/1.0` and never send cookies or stored credentials.
+
+Search results and fetched pages are returned to the agent as tool results, so they are also sent to the model provider along with the rest of the conversation. Requests are made only when the agent calls a tool, never at startup.
+
+## Approve web tool calls
+
+The `web_search` and `web_fetch` kinds require approval by default. This default applies after any explicit `approval.overrides` rules and before the profile's `approval.default`, so an agent's `default: auto` does not remove it. The current approval mode decides how the request is handled, as for any other tool:
+
+- In manual mode, each web tool call opens the **Approval Required** dialog.
+- In automatic mode, the approval judge model may approve the call.
+- In bypass mode, including the headless CLI `icode run`, web tool calls run without asking.
+
+To stop being asked about searches, set an override in the agent profile, for example `approval.overrides: {web_search: auto}`. See [Configure approval modes](./approval.md).
+
+## Choose a search provider
+
+Configure search providers in the agent profile under `tools.web_search`. The fields are listed in the [agent profile reference](../../reference/agent-profile.md#toolsweb_search). Each provider has an ID of your choice in `providers`, and the mode decides how providers are used:
+
+| Mode | Behavior |
+| --- | --- |
+| `auto` | With no `provider`, `fallback_chain`, or `providers`, uses anonymous Exa. With a `providers` map, you must also set `fallback_chain` to the provider IDs to try, in order. |
+| `provider` | Uses exactly one provider, named in `provider`. `fallback_chain` is not allowed. |
+| `off` | Turns web search off for this agent. |
+
+`true` and `false` are also accepted: `true` means `auto` (`on` for `web_fetch`) and `false` means `off`.
+
+If the combination is invalid, such as `auto` with a `providers` map but no `fallback_chain`, the agent starts without its web tools and iCode shows a warning with the reason (see [When web tools do not appear](#when-web-tools-do-not-appear)). An unknown mode or a malformed provider entry makes the whole profile invalid instead.
+
+### Search services that need no key
+
+| Type | Service |
+| --- | --- |
+| `exa_mcp` | Exa's public endpoint, the same service `auto` uses by default |
+| `bing_html` | Bing search result pages |
+| `duckduckgo_html` | DuckDuckGo's HTML search result pages |
+
+These types accept only `type`: the endpoints are fixed and take no credentials. For example, to use DuckDuckGo instead of Exa:
+
+```yaml
+tools:
+  builtins: [filesystem.read, search, web_search, web_fetch]
+  web_search:
+    mode: provider
+    provider: ddg
+    providers:
+      ddg:
+        type: duckduckgo_html
+```
+
+`bing_html` and `duckduckgo_html` read ordinary search result pages rather than an official API, so availability and result quality depend on the service and your network. Advertising and generated answers are left out. A captcha, consent page, or unfamiliar page layout is reported as an error, never as an empty result.
+
+### Search APIs with a key
+
+| Type | Service | Typical key variable |
+| --- | --- | --- |
+| `tavily` | Tavily Search API | `TAVILY_API_KEY` |
+| `brave` | Brave Search API | `BRAVE_SEARCH_API_KEY` |
+| `exa` | Exa Search API (authenticated) | `EXA_API_KEY` |
+
+Set `api_key_env` to the name of the environment variable that holds the key:
+
+```yaml
+tools:
+  web_search:
+    mode: auto
+    fallback_chain: [primary, backup]
+    providers:
+      primary:
+        type: tavily
+        api_key_env: TAVILY_API_KEY
+      backup:
+        type: exa
+        api_key_env: EXA_API_KEY
+```
+
+iCode reads the key from the environment that started iCode or from your user `.env` file (macOS / Linux: `~/.chrys/.env`; Windows: `%APPDATA%\chrys\.env`). A variable set in the starting environment takes precedence, even when it is empty. A `.env` file in the working directory cannot provide web credentials. The user `.env` file is read each time the agent is built, so after changing it, save the agent again or restart iCode. Only the keys of the providers the agent actually uses are read.
+
+### Fall back to another provider
+
+In `auto` mode, iCode tries the providers in `fallback_chain` in order and returns the first answer, including an empty one. It moves on to the next provider when:
+
+- The provider runs out of its share of the time limit (see [Time limits and retries](#time-limits-and-retries)).
+- A connection error, HTTP 5xx, 408, or 429 persists after one retry.
+- The provider cannot be reached: its name cannot be resolved, it resolves to a private address, or the connection is refused in a way a retry cannot fix (for example, a certificate rejected by a proxy).
+- The request is too large for the provider, such as a long query that no longer fits in its URL.
+- The provider redirects, returns a captcha or consent page, or sends a response that is too large, uses an unsupported compression, or cannot be read.
+- `exa_mcp`, `bing_html`, or `duckduckgo_html` returns any HTTP 4xx error, or `exa_mcp` reports that the search failed (for example, its free rate limit was reached). An empty result from `exa_mcp` is an answer, so the chain stops there.
+
+For keyed and custom providers, an HTTP 4xx error usually means a configuration problem, such as a wrong key, so the chain stops and the agent receives the error with its status, for example `Error: http_4xx (HTTP 403)`. Errors caused by the request itself, such as an empty query, also stop the chain. There is no hidden fallback: iCode tries only the providers you list.
+
+### Use your own search endpoint
+
+The `custom_http` type connects to any HTTP search service that returns JSON. Map the request and response in the profile:
+
+```yaml
+tools:
+  builtins: [web_search]
+  web_search:
+    mode: provider
+    provider: corporate
+    providers:
+      corporate:
+        type: custom_http
+        endpoint: https://search.example.com/v1/search
+        method: POST
+        auth:
+          location: header
+          name: Authorization
+          prefix: "Bearer "
+          key_env: CORP_SEARCH_API_KEY
+        request:
+          json:
+            query: {$input: query}
+            limit: {$input: limit}
+        response:
+          results_pointer: /data/items
+          url_pointer: /link
+          title_pointer: /title
+          snippet_pointer: /summary
+```
+
+A custom endpoint also needs a grant in your user settings. The grant names the exact endpoint URL and every environment variable the provider may read. Add it in **Settings** under **Custom search endpoints**, or in the user `settings.yaml`:
+
+```yaml
+tools:
+  web_search:
+    custom_endpoints:
+      - url: https://search.example.com/v1/search
+        credential_env_names: [CORP_SEARCH_API_KEY]
+```
+
+Mapping rules:
+
+- `{$input: NAME}` inserts a value from the search: `query`, `limit`, `allowed_domains`, or `blocked_domains`. `{$env: NAME}` inserts an environment variable, which must also be listed in the grant. Each marker replaces a whole value and keeps its type.
+- `method` is `GET` or `POST`. `GET` sends `request.query_params`, with lists becoming repeated parameters. `POST` can also send a `request.json` body.
+- `auth.location` is `header`, `query`, or `none`. Put keys only in `auth` or `$env` markers, never directly in headers.
+- The `*_pointer` fields are JSON Pointers, such as `/data/items`. `results_pointer` and `url_pointer` are required. If the results container is missing, the search fails instead of returning nothing.
+
+Two presets fill in the mapping for common services:
+
+- SearXNG: `type: custom_http`, `preset: searxng`, and your instance's `endpoint`, such as `https://search.example.com/search`. JSON output must be enabled on the SearXNG server.
+- SerpAPI: `type: custom_http` and `preset: serpapi`. Grant `https://serpapi.com/search` with `credential_env_names: [SERPAPI_API_KEY]`.
+
+## Control network access
+
+Network access for web tools is set only in your user settings. Project settings and agent profiles cannot change it, so a repository you open cannot widen what the tools may reach. The common search options are on the **Tools** tab of **Settings**; the fetch lists are set in the user `settings.yaml`. For every key, see the [settings file reference](../../reference/settings.md#web-tools).
+
+```yaml
+tools:
+  web_egress:
+    proxy_url: ""        # an explicit HTTP(S) proxy for web tools only
+    proxy_dns: local     # remote: the proxy resolves host names
+  web_search:
+    private_origins: []
+    http_origins: []
+    custom_endpoints: []
+  web_fetch:
+    denied_origins: []   # never fetch these; this always wins
+    allowed_origins: []  # when not empty, fetch only these
+    private_origins: []  # allow these even if they resolve to a private address
+    http_origins: []     # allow plain http:// for these
+```
+
+List entries are origins: a scheme, host, and optional port, such as `https://docs.example.com` or `http://127.0.0.1:8080`. They cannot include paths, queries, credentials, or wildcards. Default ports and upper-case host names are normalized. In **Settings**, lists are entered as JSON arrays, such as `["https://docs.example.com"]`, and are checked with the same rules the tools use before they are saved.
+
+The rules work as follows:
+
+- **HTTPS only**: plain `http://` is refused unless the origin is in `http_origins`.
+- **Public addresses only**: before connecting, iCode resolves the host name and refuses private, loopback, link-local, and other non-public addresses unless the origin is in `private_origins`. iCode then connects to the address it checked, while keeping the original host name for the request and TLS certificate checks. With **Web proxy DNS** set to `remote`, the proxy resolves the name instead; see [Use a fake-IP proxy](#use-a-fake-ip-proxy).
+- **Fetch lists**: `denied_origins` always wins. When `allowed_origins` is not empty, `web_fetch` reads only from those origins.
+- **Search and fetch are separate**: an exemption for search never lets `web_fetch` reach that origin, and the reverse.
+- **Proxy**: web tools ignore proxy variables such as `HTTP_PROXY` and `HTTPS_PROXY`. To use a proxy, set **Web proxy URL** (`tools.web_egress.proxy_url`) to an `http://` or `https://` proxy address without credentials or a path. It applies only to web tools. With **Web proxy DNS** at its default `local`, iCode reaches a site through the proxy at its IPv4 addresses only, so a site that has only IPv6 addresses fails with `proxy_ipv6_unsupported`. With `remote`, the proxy resolves the name and may reach such a site over IPv6. In either mode, a URL that names an IPv6 address directly, such as `https://[2001:db8::1]/`, cannot go through the proxy. Certificate settings from the environment, such as `SSL_CERT_FILE`, are still honored.
+- Host names may contain underscores, such as `http://search_box:8080`, in tool URLs, origin lists, and the proxy URL.
+
+For example, to use a SearXNG instance at `http://127.0.0.1:8080/search`, grant that endpoint in `custom_endpoints` and add `http://127.0.0.1:8080` to both `tools.web_search.private_origins` and `tools.web_search.http_origins`.
+
+### Use a fake-IP proxy
+
+Some proxies, such as Clash or Surge in TUN or fake-IP mode, answer DNS lookups with placeholder addresses in `198.18.0.0/15` and connect to the real site themselves. Those addresses are not public, so every web request fails with `private_address_blocked`, and the error adds a hint that names this setting. To use such a proxy:
+
+1. Set **Web proxy URL** (`tools.web_egress.proxy_url`) to the proxy's HTTP port, such as `http://127.0.0.1:7890`.
+2. Set **Web proxy DNS** (`tools.web_egress.proxy_dns`) to `remote`.
+
+```yaml
+tools:
+  web_egress:
+    proxy_url: http://127.0.0.1:7890
+    proxy_dns: remote
+```
+
+With `remote`, iCode sends the host name to the proxy, and the proxy decides which address it finally connects to. Blocking private and other non-public destinations for a name is then the proxy's job, not iCode's. iCode still applies every other rule: HTTPS only, the origin lists, redirect checks, and TLS certificate checks against the host name. It also still refuses URLs that name a non-public address directly, such as `https://127.0.0.1` or `https://localhost`, unless the origin is in `private_origins`. An IPv6 address written in a URL still cannot go through a proxy and fails with `proxy_ipv6_unsupported`.
+
+iCode never switches to `remote` on its own. Adding the fake-IP range to `private_origins` is not a substitute: the lists hold single origins, and exempting the range would also let names that resolve to your own network through.
+
+## Filter search results by domain
+
+The agent can limit a search to `allowed_domains` or exclude `blocked_domains`, but not both at once. A domain also covers its subdomains. iCode always checks the results itself, and how much the provider helps depends on the provider:
+
+- Tavily and the Exa API filter by domain themselves.
+- Exa's public endpoint cannot filter, so iCode asks it for more results and keeps only the matching ones.
+- Other providers receive the filter as `site:` and `-site:` terms in the query.
+
+When the filter removes results, the search output reports how many.
+
+## Time limits and retries
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| Search `timeout_seconds` | 30 seconds | Deadline for the whole search call, including time spent waiting for a free connection slot |
+| Fetch `timeout_seconds` | 60 seconds | Deadline for the whole fetch call |
+
+Within a search, each remaining provider gets an equal share of the time left. A transient failure (a connection error, or HTTP 5xx, 408, or 429) is retried once within that share. A provider that runs out of time passes the search to the next provider in `fallback_chain`.
+
+Set these limits in the user `settings.yaml` (`tools.web_search.timeout_seconds` and `tools.web_fetch.timeout_seconds`, 1 to 120 seconds), or per agent under `tools.web_search` and `tools.web_fetch` in the profile.
+
+## Limits of fetched pages and search results
+
+- `web_fetch` reads one URL with GET. It accepts text, HTML, JSON, and XML. HTML is converted to Markdown after scripts, styles, forms, and hidden templates are removed. PDFs, images, and other binary files are refused, and the body of an error response is never returned.
+- The `prompt` the agent passes to `web_fetch` is shown to you and included with the page as a focus hint. No second model reads the page.
+- Same-site redirects (same scheme and port, with or without a `www.` prefix) are followed for up to 2 hops, each checked against the network rules. A redirect to another site is reported to the agent with the new URL, which it must fetch explicitly.
+- Responses are limited to 2 MiB, both as sent and after decompression. Web fetch and the Bing and DuckDuckGo adapters accept only gzip or uncompressed responses.
+- A fetched page returns at most 16,000 tokens by default (`tools.web_fetch.max_tokens`, up to 64,000). The agent can ask for less, but not more. Search output is limited to about 8,000 tokens.
+- Fetched pages are reused for 15 minutes (up to 64 pages and 16 MiB), and URLs that differ only in the `#fragment` share one copy.
+- Web search and web fetch share 3 simultaneous connections per agent, and an agent can make at most 20 searches in one turn.
+- iCode does not run JavaScript, does not read `robots.txt`, and does not summarize pages. Use `denied_origins` to keep `web_fetch` away from specific origins. Each entry matches exactly one origin: it does not cover subdomains or the `www.` variant, so list each one you mean.
+
+Search results and page text come from outside sources. iCode marks them as untrusted data for the agent; check the source links before relying on important claims.
+
+## Provider-run search
+
+Some model services can run web search themselves. When a model profile declares such a tool in its `chat_options`, for example `{"tools": [{"type": "web_search"}]}`, the provider's tool takes over that name. If the agent also includes the matching iCode tool, the local tool is turned off for that run and iCode shows a notice once. This works per name: a provider-run `web_search` leaves a local `web_fetch` in place.
+
+Provider-run search happens on the model provider's side, so iCode's approval rules and network settings do not apply to it. To use iCode's own tools instead, remove the declaration from the model's `chat_options`.
+
+## When web tools do not appear
+
+If iCode cannot set up an agent's web tools, for example because a key variable is missing or a custom endpoint is not granted, the agent still starts without them and iCode shows a warning that names the agent and the reason. Fix the configuration, then save the agent again or restart iCode.
+
+Also check that:
+
+- The agent includes `web_search` or `web_fetch` in `tools.builtins`.
+- The tool's mode is not `off`: the profile's `tools.web_search.mode` or `tools.web_fetch.mode`, or, when the profile sets none, **Web search mode** or **Web fetch mode** in **Settings**.
+- The model profile does not declare a provider-run web tool with the same name.
+
+To see which tools are loaded, enter `/runtime` in the input field; see [Tool kinds and names](../../reference/tool-kinds-and-names.md).