iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/tui/screens/guides/_docs/en/guides/daily-use/sessions.md

@@ -0,0 +1,77 @@
+# Manage and resume sessions
+
+A session contains conversation history and related data, such as rollback snapshots and diagnostic logs. iCode saves sessions automatically so you can resume a conversation or look up past tasks later. This guide explains how to switch, name, find, resume, and delete sessions in the terminal user interface (TUI), and how to migrate existing sessions when changing their storage location.
+
+## Switch to a new session
+
+When the agent is idle, enter the appropriate command in the input field, depending on whether you want to keep the current session:
+
+| Goal | Command | Effect on the current session |
+| --- | --- | --- |
+| Start a new session and keep the current session available to resume later | `/new` | Kept; you can resume it from the session list |
+| Start a new session without keeping the current session | `/clear` | Opens a confirmation dialog; once confirmed, the session is permanently deleted and cannot be recovered |
+
+## Change the session title
+
+You can change the current session's title in any of these ways:
+
+- Click the "Session: ..." area in the upper-left corner of the main screen to open the "Session Title" dialog, enter a title, and click "Save".
+- Enter `/rename` in the input field to open the "Session Title" dialog, enter a title, and click "Save".
+- Enter a title directly after `/rename`, for example, `/rename Fix the login issue`.
+
+After you set a title manually, the new title appears in the session list and on the main screen, and iCode stops updating that session's title automatically. If [automatic session titles](../configuration/settings.md#sessions) are enabled, clearing the "Session Title" dialog and saving restores the existing automatic title and lets iCode continue updating it automatically during subsequent tasks.
+
+## Resume an existing session
+
+When the agent is idle, enter `/resume` in the input field to resume the most recent chat session.
+
+To find and resume another session, press **F1**, click `f1 Sessions`, or enter `/sessions` in the input field to open the "Chat Sessions" window. It lists each session's ID, title, directory, last active time, number of conversation turns, and session data size. Each page shows up to 100 sessions, most recently active first.
+
+- **Filter by where a session was last used**: The "TUI", "CLI", and "ACP" checkboxes above the search field show sessions last used in the TUI, in [`icode run`](../running/icode-run.md), or in an editor or other client connected through [`icode acp`](../running/icode-acp.md). Only "TUI" is checked at first. Sessions from earlier iCode versions count as TUI. iCode remembers your choice until you quit it. Hover over a session to see where it was last used.
+- **Switch pages**: Click "Previous" or "Next" on the right, next to the checkboxes.
+- **Sort sessions**: Sessions are sorted by last active time, newest first. Click a column header to sort the current page by that column: "Last Active", "Turns", and "Size" start in descending order, and the other columns in ascending order. Click the same header again to reverse the order.
+- **Search sessions**: Enter a session ID, title, directory, or a prompt you previously entered in the search field at the bottom. The search covers only the current page.
+- **Resume a session**: Select a session and click "Resume". You can also double-click it, or select it with the up and down arrow keys and press Enter. iCode closes the current conversation view, loads the selected session, and switches the working directory to the session's saved primary working directory; the current session remains saved in the list. Before resuming, check the working directory that will be restored in the list's "Directory" column. If that directory no longer exists, iCode asks you to choose another folder; see [If the working directory is deleted or moved](workspaces.md#if-the-working-directory-is-deleted-or-moved).
+
+When you resume a long conversation, iCode shows its most recent part first so you can continue right away; earlier messages keep loading above it for a few seconds.
+
+If a resumed conversation continues on a different model service than before, some earlier reasoning may be left out; see [Switch the current model profile](../configuration/models.md#switch-the-current-model-profile).
+
+## Delete old sessions
+
+Open the "Chat Sessions" window and first check the session ID, directory, and last active time. If you are unsure, resume the session to check its contents, then return to the "Chat Sessions" window. Select a session you no longer need and click "Delete".
+
+Once you confirm deletion, the session's conversation history, rollback snapshots, diagnostic data, and other session contents are permanently deleted and cannot be recovered. Deleting a session does not undo changes the agent has already made to working directory files.
+
+Deleting the current session also starts a new session, like `/clear`. A session open in another iCode instance cannot be deleted; close that instance first.
+
+## Find the session ID and storage location
+
+The current session ID appears in the "Session: ..." area in the upper-left corner of the main screen. IDs for past sessions appear in the list in the "Chat Sessions" window.
+
+Enter `/settings sessions`, or press **F10** and select the "Sessions" tab. The "In use" text below "Session storage root" shows the actual `sessions` directory currently in use. Each session is saved in a subdirectory named after its session ID.
+
+If you have not customized the session storage root, the `sessions` directory defaults to `~/.chrys/sessions` on macOS and Linux, and `%APPDATA%\chrys\sessions` on Windows.
+
+## Migrate session storage
+
+To change where sessions are stored, set a new session storage root and migrate existing sessions to it. The new location takes effect after a restart; changing the storage location alone does not migrate existing sessions automatically.
+
+Before starting, finish the current task and close other iCode instances, then follow these steps:
+
+1. Enter `/settings sessions`, or press **F10** and select the "Sessions" tab, then choose a new root directory under "Session storage root".
+2. Click "Migrate sessions". Check that "From" is the `sessions` directory currently in use and "To" is the `sessions` directory under the new root, then click "Migrate".
+3. Wait for migration to finish, then handle any sessions that were not copied according to the results:
+
+   | Result | Meaning | Next step |
+   | --- | --- | --- |
+   | Copied | The session was copied to the destination directory. | No action needed. |
+   | already present | The destination already contains the same session ID, so it was skipped. iCode does not compare or update the destination contents. | If you cannot confirm which version is at the destination, use an empty destination directory and migrate again, or keep the source data. |
+   | active | The session is open in an iCode instance, so it was skipped. | Close other instances and retry. If it is the current session, close settings and run `/new`; do not send a message in the new session, then migrate again. |
+   | busy | The session is being saved or is in use by another operation, so it was skipped. | Wait for the operation to finish, then retry. |
+   | failed | The session could not be copied. | Use the paths and reasons listed in the window to resolve permission or path issues, then retry. |
+
+4. After handling sessions marked "active", "busy", or "failed", click "Close", then click "Migrate sessions" to migrate again (the "Migrate" button is disabled after each migration). Repeat until all sessions you want to keep have been copied.
+5. Close all iCode instances and restart, then press **F1** to open the "Chat Sessions" window and confirm that important sessions appear and can be resumed.
+
+Migration keeps the original data in the source directory; it is not deleted automatically. After confirming that migration is complete, if you need to free up space, close iCode and archive or delete the old `sessions` directory shown under "From" in the migration window. Manual deletion cannot be undone.

chrys/app/tui/screens/guides/_docs/en/guides/daily-use/workspaces.md

@@ -0,0 +1,51 @@
+# Working directory
+
+The working directory is the default directory iCode uses for file operations and command execution. Before asking the agent to modify files, save any unsaved content to disk and record existing changes with a Git commit. This makes it easier to distinguish the agent's changes and restore the previous state if needed.
+
+## Choose a working directory at startup
+
+In a terminal, enter the project directory and start iCode:
+
+```shell
+cd <project-directory>
+icode
+```
+
+iCode uses the directory it was started in as the working directory.
+
+You can also specify a working directory with `-C` or `--workdir`, without first entering the project directory:
+
+```shell
+icode -C <project-directory>
+```
+
+## Change the working directory during a session
+
+When the agent is idle, click the current working directory path at the right end of the conversation area's bottom border, or enter `/chdir` in the input field to open the "Change Directory" dialog. Browse to and select the target directory. To create a new folder, click the folder it should go in, click "New Folder", enter a name, and press Enter; the new folder is then selected. If you have used the target working directory recently, select it from the "Recent" group on the "Favorites" tab.
+
+If you know the target path, enter the following command in the input field to switch directly:
+
+```text
+/chdir <project-directory>
+```
+
+`<project-directory>` can be an absolute path or a path relative to the current working directory. If the target does not exist or is not a directory, iCode displays an error and keeps the current working directory.
+
+After the switch, the new working directory path appears at the right end of the conversation area's bottom border. The agent uses the new working directory as the default location for subsequent file reads, commands, and other operations.
+
+When switching working directories, iCode reloads the current agent and loads memory and skills from the new working directory (its skills only while “Load project skills” is on). For configuration details, see [Configure memory](../configuration/memory.md) and [Install and use skills](../extensions/skills.md).
+
+Switching working directories does not create a new session; the current conversation history is preserved. When working on an unrelated project, first enter `/new` to create a new session, then switch working directories in that session. This avoids recording the working directory change in the original session or mixing context from different projects.
+
+## If the working directory is deleted or moved
+
+If the working directory is deleted or moved outside iCode, for example in a file manager or another terminal, iCode cannot keep using it:
+
+- A task that is already running continues. Commands and file operations that need the working directory fail, and the agent tells you that the directory no longer exists.
+- When the task ends, or when you send a message, iCode shows the "Working Folder Not Found" dialog. Click "Choose Folder…" and select a folder; the "Change Directory" dialog opens at the nearest folder that still exists. iCode switches to the selected folder and keeps the current conversation.
+- A message you sent stays in the input field. Send it again after switching.
+- If you close the dialog without choosing a folder, it appears again the next time you send a message. You can also switch with `/chdir`, or move the folder back to where it was.
+
+When you resume a session whose working directory no longer exists, iCode asks you to choose a folder to open the session in. If you cancel, the session is not resumed; if you started iCode with `-s`, iCode starts a new session instead.
+
+If you start iCode from a directory that no longer exists, iCode shows an error and exits. Enter an existing directory, or pass `-C` with the full path of your project directory, such as `icode -C ~/projects/my-app`.

chrys/app/tui/screens/guides/_docs/en/guides/extensions/external-acp-agents.md

@@ -0,0 +1,126 @@
+# Configure external ACP agents
+
+This guide explains how to connect an external agent that supports the Agent Client Protocol (ACP) in the terminal user interface (TUI) and add it as a sub-agent of the main agent.
+
+**External ACP agents can be used as sub-agents or workflow nodes, but not as the main chat agent**. Each time an external ACP agent is called, iCode starts an external agent process for that invocation and communicates with it over ACP. The external agent handles the task and tool calls; approval requests, execution status, progress updates, and the final result are passed over the ACP connection. When the invocation ends, iCode closes the connection and terminates the process.
+
+## Prepare the external agent
+
+Before configuring an external agent, confirm that it:
+
+- Is installed on the device running iCode.
+- Supports running an ACP server over standard input and output (stdio).
+- Has completed any required login or authentication, or has the environment variables needed for authentication ready.
+- Can start in ACP mode using an executable and arguments.
+
+You do not need to start the ACP server in advance. When testing the connection or calling the sub-agent, iCode automatically starts the external agent process using the configuration and establishes an ACP connection over stdio.
+
+Before the initial setup, consult the external agent's documentation and prepare the following information:
+
+- The executable and arguments required to start ACP mode.
+- The required authentication information.
+- Optional session modes, models, and other configuration options.
+
+You can specify the session mode, model, and other configuration options during the initial setup, or fill them in using the test results after a successful connection.
+
+## Create a profile and test the connection
+
+### Create an external ACP agent profile
+
+1. Open the "Agent Configuration" window.
+2. Click "New" and enter a name, display name, and description.
+3. Change "Agent Type" to "External ACP". iCode automatically enables "Sub-Agent only".
+4. Open the "ACP Settings" tab, enter the program name or path in "Executable", and add each startup argument separately.
+5. Add any environment variables required for authentication. The external agent does not inherit iCode's environment, so add them here; see [Use environment variables](#use-environment-variables).
+6. You can leave "Session Mode", "Model ID", and "Config Options" blank for now. Click "Test" after completing the basic setup.
+
+Fill in "Executable" and "Arguments" separately. For example, if the startup command is:
+
+```text
+example-agent acp --model example-model
+```
+
+Enter `example-agent` in "Executable", then add `acp`, `--model`, and `example-model` as separate startup arguments. Do not enter the entire command in "Executable".
+
+> **Note**
+>
+> Changing a custom agent's "Agent Type" from "Built-in" to "External ACP" clears its existing configuration except for basic information such as its name, display name, and description. To keep the original configuration, create a new external ACP agent.
+
+### Test the connection
+
+When testing a connection, iCode starts a temporary external agent process and checks whether it can establish an ACP session, without sending a task. After a successful connection, the report shows sections for identity, capabilities, modes, models, configuration options, and authentication methods, listing the information provided by the external agent. Information the agent does not provide may appear as "Not advertised.", "The agent did not report its identity.", or a blank entry. This does not indicate a connection failure.
+
+When the test ends, iCode closes the temporary process.
+
+If the connection fails, check the following in order:
+
+- Whether the error message and the end of the standard error output indicate missing dependencies, incorrect arguments, or authentication failure.
+- Whether the executable and startup arguments are correct.
+- Whether the authentication information or environment variables are valid.
+- Whether the configured working directory exists and is accessible.
+
+### Example: Configure iCode as an external ACP agent
+
+iCode itself can also provide an ACP server over stdio. Use the following configuration:
+
+- "Executable": `icode`
+- "Arguments": add `acp`
+
+This configuration corresponds to the startup command:
+
+```bash
+icode acp
+```
+
+This command starts the iCode ACP server, offering the `Code` agent by default and using `manual` approval mode. For more configuration and usage instructions for the iCode ACP server, see [Use the iCode ACP server](../running/icode-acp.md).
+
+## Use environment variables
+
+The external agent does not inherit the environment iCode runs in. It starts with only a basic set of variables — `HOME`, `LOGNAME`, `PATH`, `SHELL`, `TERM`, and `USER` on macOS and Linux; `APPDATA`, `HOMEDRIVE`, `HOMEPATH`, `LOCALAPPDATA`, `PATH`, `PATHEXT`, `PROCESSOR_ARCHITECTURE`, `SYSTEMDRIVE`, `SYSTEMROOT`, `TEMP`, `USERNAME`, and `USERPROFILE` on Windows — plus the environment variables set in the agent profile. Add anything else the agent needs, such as API keys or proxy settings like `HTTPS_PROXY`, as environment variables in the profile.
+
+In the executable, arguments, environment variable values, and working directory, you can use `{{ENV_VAR}}` to reference environment variables in the environment where iCode runs. This lets you reuse existing configuration values without entering fixed values or sensitive information directly in the agent profile. Environment variable names can contain only letters, digits, and underscores, and cannot start with a digit.
+
+For example, if an API key is stored in the `EXTERNAL_AGENT_API_KEY` environment variable, set the value of the environment variable required by the external agent to:
+
+```text
+{{EXTERNAL_AGENT_API_KEY}}
+```
+
+iCode resolves these references when you save the profile, when you test the connection, and each time it starts the external agent. If a referenced variable does not exist or has an empty value, the profile cannot be saved, and the connection test or invocation fails.
+
+## Set the working directory
+
+When "Working Directory" is blank, the external agent uses the current iCode session's working directory.
+
+"Working Directory" accepts a relative or absolute path. Relative paths are resolved against the current session's working directory.
+
+By default, the external agent's working directory must be within the current session's primary working directory or any additional working directory. To use a directory outside all of these locations, select "Allow cwd outside workspace". This option only relaxes directory validation; it does not change the external agent's file permissions. Before enabling it, confirm that the external agent program is trusted and check whether the target directory contains sensitive files.
+
+## Adjust the external agent's configuration
+
+After the first successful connection test, use the test report to refine the external agent's configuration:
+
+- **Session Mode**: Set the external agent's session mode. Enter a mode ID listed in the test report.
+- **Model ID**: Specify the model the external agent uses. Enter a model ID listed in the test report. This setting does not affect the model used by the main agent.
+- **Config Options**: Set other configuration options provided by the external agent. Enter the corresponding option IDs and values from the test report.
+
+All of these settings can be left blank. When they are blank, iCode uses the external agent's defaults. Test the connection again after changing the configuration.
+
+By default, the connection test fails if the external agent does not support the specified session mode or configuration options. To ignore unsupported settings and continue connecting, enable "Best effort mode and config options".
+
+"Model ID" is applied on a best-effort basis. If the external agent does not list the specified model, or answers the switch with an unsupported-method or invalid-parameters error, iCode continues using the external agent's default model. Any other error while switching the model fails the connection.
+
+## Set the result and timeouts
+
+"Result" determines what the main agent receives:
+
+- **Last message segment**: Returns only the external agent's final reply segment. Suitable for most tasks.
+- **Full transcript**: Returns all message segments the external agent sends during the invocation. Suitable for tasks where the complete response sequence is needed.
+
+"Handshake Timeout (seconds)" limits how long iCode waits to start the process, complete ACP initialization, and open a session. "Idle Timeout (seconds; 0 disables)" limits how long iCode waits without receiving any activity during an invocation. Set it to `0` to allow an unlimited idle wait. The **Test** button does not use "Handshake Timeout (seconds)": it always waits at most 15 seconds, so an agent that starts more slowly can fail the test yet still work when invoked.
+
+## Add the external ACP agent to the main agent
+
+After saving the external agent profile, follow the steps in [Configure sub-agents for an agent](../configuration/agents.md#configure-sub-agents-for-an-agent) to add it to the main agent.
+
+In the "Profile" dropdown, external ACP agent names have an `(ACP)` marker. Select the corresponding profile and save.

chrys/app/tui/screens/guides/_docs/en/guides/extensions/hooks.md

@@ -0,0 +1,167 @@
+# Configure and write hooks
+
+Hooks automatically run local scripts or commands when specified events occur. For example, a hook can record results after a turn ends, check arguments before a tool runs, or add instructions for the model when a user submits a message.
+
+This guide uses a simple example to introduce writing and configuring hooks, followed by several common examples you can adapt. For the full list of events, configuration fields, defaults, and script input and output formats, see the [Hooks configuration reference](../../reference/hooks.md).
+
+> **Security notice**
+>
+> Hooks run directly with the current user's permissions, without tool approval or sandbox restrictions. Before enabling hooks included in a project, inspect their configuration files and the scripts and commands they run.
+>
+> Hooks may receive conversation content, tool arguments, and tool results. If a hook sends this data to an external service, check whether it contains sensitive information.
+
+## Create your first hook
+
+The following steps create a project hook in the working directory of the current iCode session. It applies only to this working directory and appends the turn status to `hook-events.log` in that directory after each turn ends.
+
+### 1. Create the configuration
+
+Create `.chrys/hooks/hooks.yaml`:
+
+```yaml
+hooks:
+  - id: record-turn
+    event: after_turn
+    run:
+      type: script
+      path: scripts/record_turn.py
+```
+
+`id` is the hook's stable identifier and must be unique within a configuration file. This example uses `record-turn`.
+
+This configuration runs `scripts/record_turn.py` when the `after_turn` event occurs. Relative script paths are resolved from the directory containing the hook configuration file, so this points to `.chrys/hooks/scripts/record_turn.py`, which you create in the next step.
+
+### 2. Create the script
+
+Create `.chrys/hooks/scripts/record_turn.py`:
+
+```python
+import json
+import os
+from pathlib import Path
+
+with open(os.environ["CHRYS_HOOK_PAYLOAD_FILE"], encoding="utf-8") as payload_file:
+    payload = json.load(payload_file)
+
+with Path("hook-events.log").open("a", encoding="utf-8") as log_file:
+    log_file.write(f"turn={payload['turn']} status={payload['status']}\n")
+```
+
+iCode provides the event's JSON input file through the `CHRYS_HOOK_PAYLOAD_FILE` environment variable. The input for `after_turn` includes `turn` and `status`, which contain the turn number and ending status. By default, the script runs in the current iCode session's working directory, so `hook-events.log` is also written there.
+
+### 3. Load and verify
+
+Project hooks are not loaded by default. In the terminal user interface (TUI), press **F10** to open **Settings**, then turn on **Load project hooks** in the **Project trust** section of **Security**. If it is already on, switch sessions or restart iCode to apply the configuration on disk.
+
+In the TUI, enter `/runtime` and open the **Hooks** tab. You should see `record-turn`. Submit a message and wait for the current turn to end, then check `hook-events.log` in the working directory. It should contain a line like this:
+
+```text
+turn=1 status=ok
+```
+
+## Example: block an operation based on tool arguments
+
+To check or reject an operation before a tool runs, use the `before_tool_call` event with blocking execution. This example prevents file-writing tools from modifying files named `.env`.
+
+First, add this entry to the `hooks` list in `.chrys/hooks/hooks.yaml`:
+
+```yaml
+  - id: protect-env
+    event: before_tool_call
+    match:
+      tool_kind: filesystem.write
+      args:
+        path:
+          regex: "(^|[\\\\/])\\.env$"
+    run:
+      type: script
+      path: scripts/protect_env.py
+    execution:
+      mode: blocking
+      timeout_seconds: 5
+      on_error: block
+```
+
+This configuration matches only `filesystem.write` tool calls that have a `path` argument whose path ends in `.env`. Blocking hooks finish before iCode continues processing the call.
+
+Then create `.chrys/hooks/scripts/protect_env.py`:
+
+```python
+import json
+import os
+
+with open(os.environ["CHRYS_HOOK_RESULT"], "w", encoding="utf-8") as result_file:
+    json.dump(
+        {"action": "block", "reason": "Modifying .env with file-writing tools is not allowed"},
+        result_file,
+        ensure_ascii=False,
+    )
+```
+
+The script returns `action: block` and the rejection reason through the result file specified by `CHRYS_HOOK_RESULT`. What a script prints to standard output or standard error is not read as a decision, and iCode keeps at most 256 KiB of each, from the beginning and the end.
+
+`on_error: block` also rejects the tool call if the script fails to start, times out, or returns a nonzero exit code. Use it for checks that must keep the restriction in place when they fail. This hook blocks only matching `filesystem.write` calls; shell commands are unaffected.
+
+After switching sessions or restarting iCode, create a dedicated test file, `hook-demo/.env`, with known content such as `HOOK_TEST=unchanged`. Ask the agent to attempt one modification using only `write_file` or `edit_file`, then stop after rejection without using the shell or another method. Check that the tool call is rejected before execution and displays the reason provided by the script. Then confirm that the file content is unchanged. You can delete `hook-demo/.env` after verification.
+
+## Example: add a system reminder for the model
+
+A `user_prompt_submit` hook can add instructions or hints for the model when a user submits a message. This example applies only to the Code agent and reminds it to run project tests after modifying Python files.
+
+First, add this entry to the `hooks` list in `.chrys/hooks/hooks.yaml`:
+
+```yaml
+  - id: remind-python-tests
+    event: user_prompt_submit
+    match:
+      profile: Code
+    run:
+      type: script
+      path: scripts/remind_python_tests.py
+    execution:
+      mode: blocking
+      timeout_seconds: 5
+```
+
+Then create `.chrys/hooks/scripts/remind_python_tests.py`:
+
+```python
+import json
+import os
+
+with open(os.environ["CHRYS_HOOK_RESULT"], "w", encoding="utf-8") as result_file:
+    json.dump(
+        {"system_reminder": "After modifying Python files, run the tests relevant to the changes."},
+        result_file,
+        ensure_ascii=False,
+    )
+```
+
+Switch sessions or restart iCode to apply the configuration. The system reminder takes effect only after the blocking hook finishes successfully. iCode wraps the reminder in `<system-reminder>` tags and sends it to the model along with the user's submitted message. The reminder does not appear in the TUI conversation and is not saved in session data.
+
+To confirm that a `user_prompt_submit` hook is working, or to inspect the actual system reminder sent to the model, check the raw HTTP log of model requests. This log contains unredacted API keys and full conversation content, so enable it only temporarily for troubleshooting. In the TUI, press **F10**, go to **Security** > **Diagnostics**, enable **Capture raw HTTP traffic**, and restart iCode. Submit a message using the Code agent, then search for the reminder text "After modifying Python files" in `llm_raw_http.jsonl` in the current session directory. For its location, see [Find the session ID and storage location](../daily-use/sessions.md#find-the-session-id-and-storage-location). After verification, disable raw HTTP traffic capture and restart iCode again.
+
+To add a reminder only for certain tasks, have the script read `text` (the message the user just submitted) from `CHRYS_HOOK_PAYLOAD_FILE` and write `system_reminder` to `CHRYS_HOOK_RESULT` only when the message meets your conditions.
+
+## Choose an execution mode
+
+For most hooks, choose an execution mode based on whether the current operation must wait for the result:
+
+| Need | Recommended mode | Behavior |
+| --- | --- | --- |
+| Check, reject, or modify an operation before it continues | `blocking` | iCode waits for the hook to finish; some events apply the action decision from the result file |
+| Continue the current operation immediately, but let iCode wait for a limited time when the current turn or session ends | `async` | iCode continues immediately, then waits for the hook to finish at applicable events, within the wait limit |
+| Send ordinary notifications or record information in a task that can be interrupted by exit | `fire_and_forget` | iCode continues immediately and does not wait when the current turn or session ends; this is the default mode |
+
+An asynchronous hook (`async`) does not delay the event that triggered it or the current operation. When the current turn or session ends, if an applicable asynchronous hook is still running, iCode waits for it to finish before ending the turn or session. iCode does not wait for asynchronous hooks triggered by `user_interrupt`. The wait limit at session end is configurable in [Global settings](../../reference/hooks.md#global-settings). To retry unfinished tasks after iCode exits, also configure `delivery: durable`.
+
+## Use global hooks
+
+The examples above all live in `.chrys/hooks` in the current working directory and apply only to that working directory. To use the same hook across all working directories, use global configuration:
+
+| Platform | Global configuration file |
+| --- | --- |
+| macOS and Linux | `~/.chrys/hooks/hooks.yaml` |
+| Windows | `%APPDATA%\chrys\hooks\hooks.yaml` |
+
+Project and global configurations can be loaded together. For execution order across both locations, duplicate IDs, and `settings` merge rules, see [Execution order and configuration merging for multiple hooks](../../reference/hooks.md#execution-order-and-configuration-merging-for-multiple-hooks).

chrys/app/tui/screens/guides/_docs/en/guides/extensions/mcp.md

@@ -0,0 +1,95 @@
+# Connect MCP servers
+
+Model Context Protocol (MCP) servers can provide iCode agents with external tools, prompt templates, and usage instructions. This guide explains how to connect HTTP or STDIO MCP servers in the terminal user interface (TUI), configure which tools are available, and control whether prompt templates are loaded and server instructions are included in the model context.
+
+Before connecting an MCP server, confirm that its source is trustworthy. The server may receive tool call arguments and access local files, network services, or account data. Its prompt templates and usage instructions may also affect the agent's behavior.
+
+## Add an MCP server configuration
+
+Enter `/agents mcp` in the input field to open the current agent's "MCP" tab. Added server configurations apply only to the current agent; they are not automatically applied to other agents.
+
+Each server has its own card. Saved servers are collapsed and show only their name; click the name to expand or collapse a card. If saving finds a problem, the card with the problem expands. To delete a server, click "✕" on its card and confirm.
+
+Click "+ Add", then fill in the following fields in the new card at the top of the list:
+
+1. Enter a "Server Name". This name identifies the server in the current agent's MCP configuration. Server names must be unique within an agent's MCP configuration, and are case-insensitive.
+2. Optionally enter a "Description" to note the server's purpose. This description is not provided to the agent as server instructions.
+
+HTTP header values and STDIO environment variable values can both use `{{ENV_VAR}}` to reference environment variables set before starting iCode. Variable names can contain only letters, digits, and underscores, and cannot start with a digit.
+
+Next, complete the HTTP or STDIO settings according to the server's connection method.
+
+### Connect over HTTP
+
+1. Set "Transport" to `HTTP`.
+2. Enter the server URL. The URL must begin with `http://` or `https://`.
+3. If the server requires authentication, add names and values under "Headers". Use `{{ENV_VAR}}` to reference environment variables set before starting iCode, for example:
+
+   ```text
+   Name: Authorization
+   Value: Bearer {{MCP_API_TOKEN}}
+   ```
+
+4. If the current network requires this server to connect without using the system proxy, enable "Bypass proxy".
+5. Keeping TLS certificate verification enabled is recommended. To connect to a self-signed server you have confirmed is trustworthy, you can enable "Skip TLS verification". When enabled, iCode does not verify the HTTPS server certificate and cannot confirm that it is connecting to the intended server.
+
+### Connect over STDIO
+
+1. Set "Transport" to `STDIO`.
+2. In "Command", enter the program name or path used to start the server, along with any required arguments. The TUI splits this line and saves it into the `command` and `args` fields in the agent YAML. When editing YAML by hand, put the executable in `command` and each argument in `args` as a separate item.
+3. Add any environment variables the process needs. Enter values directly or use `{{ENV_VAR}}` to reference environment variables set before starting iCode.
+
+A STDIO connection starts the specified program on the local machine. If the startup command downloads or runs third-party packages or scripts, confirm that their sources are trustworthy and review the relevant content first.
+
+## Configure instructions, tools, and request options
+
+The following settings apply to both HTTP and STDIO servers.
+
+### Server instructions and prompt templates
+
+- **Include server instructions in model context (if available)**: Enabled by default for new configurations. When enabled, server instructions are included in the model context and may affect the agent's behavior.
+- **Load server prompt templates as tools (if available)**: Enabled by default for new configurations. When enabled, prompt templates provided by the server are added to the model's tool list as callable tools.
+
+### Tool access
+
+- **Available Tool Scope**: Controls which server tools the agent may use. Choose "All server tools", "Only selected tools", or "No tools".
+
+When selecting "Only selected tools", enter a list of tool names separated by `,`. If you do not yet know which tool names the server provides, select "All server tools" first, then follow the steps in [Test and save](#test-and-save) to view the tool names in the connection report.
+
+### Tool loading
+
+- **Loading Strategy**: Controls when tools become available to the agent. With "Full — load all available tools", every tool within "Available Tool Scope" is available at the start of a task. With "On demand — load tools as needed", only the tools in "Initially Visible Tools (optional)" are available at the start, and the agent can load other tools within "Available Tool Scope" as needed. If a server provides many tools but only a few are used regularly, on-demand loading can reduce the tool information sent to the model at the start of a task.
+- **Initially Visible Tools (optional)**: With "On demand — load tools as needed", enter an optional list of tool names separated by `,`. These tools must be included in "Available Tool Scope".
+
+For example:
+
+- If a server provides only `search` and `read_file`, and both are used frequently, choose "Full — load all available tools".
+- If a server provides dozens of tools but you usually need only `search` and `read_file`, choose "On demand — load tools as needed" and enter these two tools in "Initially Visible Tools (optional)".
+
+With Claude Opus 5.5, Fable 5.1 and Sonnet 5.5, on-demand loading has a cost. These models tie the thinking they return to the conversation before it, including the tools available to the agent at that point. When the agent loads or unloads a tool, or the next task starts again with only the initially visible tools, that changes, and the model service may leave the earlier thinking out or refuse to read it back. If the service refuses, iCode sends the request once more without the earlier thinking, which costs one extra request. Whether the service leaves the thinking out or iCode resends without it, the model no longer sees that earlier reasoning. With `thinking_block_binding: error`, iCode reports the refusal instead of resending. For the settings involved, see [Claude thinking settings](../configuration/models.md#claude-thinking-settings).
+
+### Naming and limits
+
+- **Tool Name Prefix**: Adds a prefix to this server's tool names, joining the prefix and original name with `_`. For example, the prefix `github` displays the tool `search` as `github_search`. Use a prefix to avoid conflicts when different servers or built-in tools share the same tool name.
+- **MCP Request Timeout (seconds)**: Limits how long a single MCP request can wait. Leave blank to use the default shown in the interface.
+
+## Test and save
+
+1. **Enable or disable the server**: To enable an MCP server, keep "Enabled" checked at the bottom left of its configuration card. To keep the configuration but temporarily disable the server, uncheck it. A disabled server does not provide tools, prompt templates, or usage instructions to the agent.
+2. **Test the server connection**: Click "Test" at the bottom right of the server configuration card. iCode attempts to connect and displays the server's identity, advertised capabilities, and usage instructions in a connection report, along with the tools and prompt templates available under the current configuration.
+3. **Save the configuration**: Click "Save". If you are editing the agent used by the current session, the saved MCP configuration applies to subsequent requests.
+
+If the test fails:
+
+- For HTTP servers, check the URL, authentication headers, environment variables, and proxy and TLS settings.
+- For STDIO servers, first inspect the executable, working directory, process exit code, and tail of standard error shown in the connection error. Then check the command, arguments, and environment variables, and confirm that the command can start in the indicated working directory. iCode shows only a limited amount of standard error output. For complete logs, enable logging as described in the server's documentation. Remove sensitive information such as tokens and credentials before sharing diagnostics.
+
+## Verify MCP tool calls
+
+Close the agent configuration window and submit a low-risk task that needs one of the server's tools. For example, if the server provides a read-only search tool, ask the agent to search for a specific piece of data.
+
+The conversation should show the corresponding MCP tool call card and return data from the server. If an "Approval Required" dialog appears, check the tool name and arguments before deciding whether to approve. For approval modes, see [Configure approval modes](../configuration/approval.md).
+
+If a tool returns an image, audio clip, or file that iCode can't decode, the agent receives a short note in place of that item, along with the rest of the result. A link the tool returns reaches the agent as text (its name, address, and description).
+
+If the connection test succeeds but tools are unavailable in the conversation, check that the server is enabled, that the tools appear in the connection report, and that they are included in "Available Tool Scope".