iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/tui/screens/diff/screen.tcss

@@ -0,0 +1,104 @@
+/* DiffScreen — full-screen diff viewer layout. */
+
+DiffScreen {
+    layout: vertical;
+    background: $background;
+}
+
+#diff-container {
+    height: 1fr;
+    border: round $tui-border-primary $border-opacity;
+    border-title-color: $primary;
+    border-subtitle-color: $primary;
+    background: $surface;
+}
+
+#diff-container > #diff-loading-state {
+    width: 100%;
+    height: 1fr;
+    align: center middle;
+}
+
+#diff-container > #diff-loading-state > #diff-loading {
+    width: 12;
+    height: 1;
+    color: $primary;
+}
+
+#diff-container > .diff-screen-content {
+    width: 100%;
+    height: 1fr;
+}
+
+#diff-container > .diff-screen-content > TabbedContent {
+    height: 1fr;
+}
+
+#diff-load-error {
+    width: 100%;
+    height: 1fr;
+    content-align: center middle;
+    text-align: center;
+    color: $error;
+    padding: 0 1;
+}
+
+DiffScreen TabPane {
+    height: 1fr;
+    padding: 0;
+}
+
+DiffPeriodPane {
+    height: 1fr;
+}
+
+.diff-body {
+    height: 1fr;
+}
+
+.diff-changelist {
+    width: 1fr;
+    max-width: 25%;
+    border: round $tui-border-primary $border-opacity;
+    border-title-color: $primary 90%;
+    border-subtitle-color: $primary 90%;
+}
+
+.diff-changelist Tree {
+    scrollbar-size-vertical: 1;
+}
+
+.diff-changelist .workspace-tree {
+    height: 1fr;
+}
+
+.diff-changelist .external-tree {
+    height: auto;
+    max-height: 50%;
+    border-top: solid $tui-border-primary 30%;
+}
+
+.diff-content {
+    width: 3fr;
+    height: 1fr;
+    border: round $tui-border-primary $border-opacity;
+    border-title-color: $primary 90%;
+    border-subtitle-color: $primary 90%;
+}
+
+.diff-content DiffView {
+    height: 1fr;
+}
+
+.diff-content .diff-message {
+    width: 1fr;
+    height: 1fr;
+    content-align: center middle;
+    color: $text-muted;
+    padding: 0 1;
+}
+
+/* Narrow DiffView vertical scrollbar to 1 cell */
+DiffScreen CodeColumn {
+    scrollbar-size: 1 1;
+}

chrys/app/tui/screens/guides/__init__.py

@@ -0,0 +1,7 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""User guide dialog — docs index, markdown reader, and the modal itself."""
+
+from chrys.app.tui.screens.guides.screen import GuideDialog
+
+__all__ = ["GuideDialog"]

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

@@ -0,0 +1,178 @@
+# Configure agents
+
+iCode uses agent profiles to define an agent's name, instructions, model, available tools, sub-agents, and other settings. This guide explains how to create, clone, edit, reset, switch, and delete agent profiles in the terminal user interface (TUI), and how to configure models and sub-agents for an agent.
+
+## Open the agent configuration window
+
+Open the **Agent Configuration** window in any of these ways:
+
+- Press **F2**.
+- Click `f2 Agents` at the bottom of the interface.
+- Enter `/agents` in the input field, press **Space** or **Enter** to display the list of tabs, then select the tab to open.
+
+The **Agent Configuration** window lists existing agent profiles on the left. Tabs on the right show the settings for the selected agent.
+
+Add a tab name after `/agents` to open that tab directly:
+
+| Command | Tab opened |
+| --- | --- |
+| `/agents basic` | Basic |
+| `/agents instructions` | Instructions |
+| `/agents tools` | Tools |
+| `/agents sub-agents` | Sub-Agents |
+| `/agents skills` | Skills |
+| `/agents mcp` | MCP |
+| `/agents memory` | Memory |
+| `/agents compaction` | Compaction |
+
+While a task is running, the **Agent Configuration** window opens in read-only mode. You cannot edit or save profiles. Wait for the task to finish before changing the configuration.
+
+## Manage agent profiles
+
+### Create an agent profile
+
+The following steps create an agent of the **Built-in** type. To connect an external program as a sub-agent, see [Configure external ACP agents](../extensions/external-acp-agents.md).
+
+1. Click **New**.
+
+2. Configure the agent's basic information on the **Basic** tab:
+    - Enter a name, display name, and description. All three fields are required. **Name** identifies the agent profile; **Display Name** appears in agent selection lists and the main interface. **Name** must start with a letter or digit and contain only English letters, digits, hyphens (`-`), and underscores (`_`); it must be unique, ignoring case.
+    - Select **Sub-Agent only** if appropriate for your use case. For the distinction between main agents and sub-agents, see [Main agents and sub-agents](#main-agents-and-sub-agents).
+    - Set the model the agent uses as needed. By default, it uses the active model profile. To bind a specific model profile, see [Set the model an agent uses](#set-the-model-an-agent-uses).
+
+3. On the **Instructions** tab, enter system instructions to define the agent's behavior. System instructions cannot be empty.
+
+4. Configure the other tabs as needed:
+    - **Tools**: Select the built-in tools the agent can call. See [Configure tools](./tools.md).
+    - **Sub-Agents**: Add sub-agents this agent can call. See [Configure sub-agents for an agent](#configure-sub-agents-for-an-agent).
+    - **Skills**: Configure where the agent loads skills from. See [Install and use skills](../extensions/skills.md).
+    - **MCP**: Connect MCP servers and configure the MCP tools the agent can use. See [Connect MCP servers](../extensions/mcp.md).
+    - **Memory**: Add files or folders to load into context automatically. See [Configure memory](./memory.md).
+    - **Compaction**: Adjust how context is compacted as the conversation grows. New agent profiles use the default context compaction settings, which usually do not need changing. To change them, see [Configure context compaction](./compaction.md).
+
+5. Click **Save**.
+
+### Clone an agent profile
+
+Use cloning to create a new profile based on an existing agent. Cloning creates an independent copy without changing the original profile. When you clone a built-in agent, iCode creates a custom agent copy that you can edit independently.
+
+1. Select the agent to clone in the list on the left.
+2. Click **Clone**.
+3. iCode copies the agent's configuration, generates unique values for its name and display name, and selects the new copy.
+4. Review and adjust the copy's name, display name, and other settings as needed.
+5. Click **Save** to finish creating it.
+
+**Notes:**
+
+- Clicking **Clone** creates a temporary copy for editing in the current configuration window. The profile is only created and retained when you click **Save**.
+- After editing a profile, click **Save** to apply the changes. Changes left unsaved when you close the agent configuration window do not take effect.
+
+### Edit an agent profile
+
+1. Select the agent to edit in the list on the left.
+2. Adjust its settings on the relevant tabs.
+3. Click **Save** to apply the changes.
+
+**Notes:**
+
+- You cannot change **Name** or **Agent Type** for the built-in agents included with iCode, such as Code Agent and Q&A Agent. Other settings can be adjusted as needed.
+- After editing a profile, click **Save** to apply the changes. Changes left unsaved when you close the agent configuration window do not take effect.
+- If you edit the agent used by the current session, the saved configuration takes effect for subsequent requests.
+
+### Delete a custom agent profile
+
+Deleting a custom agent also removes its configuration stored on your machine. This cannot be undone in iCode. Built-in agents cannot be deleted.
+
+Before deleting a custom agent, ensure that:
+
+- At least one usable main agent remains.
+- Any other agents that reference this agent as a sub-agent have had those references removed.
+
+To delete a custom agent:
+
+1. Select the custom agent to delete in the list on the left.
+2. Click **Delete**.
+3. Check the agent name in the confirmation window, then confirm deletion.
+
+If you delete the agent currently in use, iCode automatically switches to another available main agent when you close the configuration window.
+
+### Reset a built-in agent profile
+
+The built-in agents included with iCode cannot be deleted.
+
+When you edit and save a built-in agent, iCode creates a user profile file with the same name, such as `Code.yaml`, in the [user agent profile directory](../../reference/agent-profile.md#user-agent-profile-directory). This file stores both your changes and the other settings in effect at that time. For example, if you only add an MCP server, the saved profile contains that server and retains the current values of the other settings.
+
+At startup, iCode gives precedence to the user profile file with the same name, instead of merging user and built-in settings field by field. As a result, after an iCode upgrade, updates to built-in defaults such as agent instructions are not automatically applied to that agent.
+
+To adopt the built-in defaults from the current version, reset the built-in agent. Resetting preserves only skills, MCP server, and memory settings. Instructions, compaction, and all other settings return to the current version's built-in defaults.
+
+To reset an agent:
+
+1. Select the built-in agent to reset in the list on the left.
+2. Click **Reset**, then click **Reset** again in the confirmation window.
+3. If **Save** is enabled, click it to apply the reset. If it is disabled, the current configuration already matches the reset result described above, so there is nothing to save.
+
+Reset changes remain pending in the configuration window until saved. Closing the window discards unsaved changes.
+
+After a reset, if the user profile file with the same name no longer exists, future upgrades use the new built-in configuration directly. If the file remains because it preserves custom skills, MCP server, or memory settings, you still need to reset the agent again after future upgrades to adopt updated built-in defaults.
+
+## Configure models and sub-agents
+
+### Set the model an agent uses
+
+New agents use the active model profile by default. When you switch the active model, the agent's model changes with it.
+
+To make an agent always use a specific model profile:
+
+1. Select the agent in the list on the left, then open the **Basic** tab.
+2. Clear **Use active model profile** (the label also shows the current profile).
+3. Select the model profile to bind from the dropdown. To add or edit a model profile, see [Configure models](./models.md).
+4. Click **Save**, then close the configuration window.
+
+If the current main agent is bound to a specific model profile, the model profile name in the status bar is grayed out. Clicking it does not switch models; instead, a notice tells you which model the agent is bound to.
+
+To switch models through the status bar again, select **Use active model profile** on the agent's **Basic** tab, click **Save**, then close the configuration window.
+
+### Main agents and sub-agents
+
+A main agent interacts directly with the user. A sub-agent is called by another agent to handle delegated tasks.
+
+An agent profile can be used both as a main agent and as a sub-agent called by other agents. Selecting **Sub-Agent only** prevents the agent from being selected as a main agent; it can only be called by other agents.
+
+The Code Agent and Q&A Agent included with iCode can serve as main agents. Explore and General are sub-agents only. External ACP agents are also sub-agents only. To configure them, see [Configure external ACP agents](../extensions/external-acp-agents.md).
+
+### Configure sub-agents for an agent
+
+After you add sub-agents to an agent, it can call them as needed to handle parts of a task.
+
+In the agent configuration window:
+
+1. Select the agent to configure in the list on the left.
+2. Open the **Sub-Agents** tab.
+3. Click **+ Add** and select the sub-agent to add.
+4. Set the sub-agent's **Tool Name**, **Tool Description**, and **Max Concurrency**.
+5. Adjust **Max Total Concurrency** at the top of the tab as needed.
+6. Click **Save**.
+
+These settings work as follows:
+
+- **Tool Name** and **Tool Description** help the agent identify and use a sub-agent. When left blank, they default to the sub-agent's own profile name and description, respectively.
+- **Max Concurrency** limits simultaneous calls to a single sub-agent. **Max Total Concurrency** limits simultaneous calls across all sub-agents.
+
+During a task, the agent uses each sub-agent's tool name and description to decide whether to delegate work to it. You can also request a specific sub-agent in the input field, for example: `Call <tool name> to complete <task>`. A successful result from the corresponding sub-agent tool confirms that the configuration has taken effect.
+
+A sub-agent returns its final reply to the agent that called it. Text it writes between tool calls appears on its card but is not returned. If the final reply has no text, all the text the sub-agent wrote is returned, in order. If the sub-agent fails, its card shows the reason. An external ACP agent returns what its **Result** setting selects; see [Set the result and timeouts](../extensions/external-acp-agents.md#set-the-result-and-timeouts).
+
+**Notes:**
+
+- After adding, removing, or editing sub-agent settings, you must click **Save** for the changes to take effect. Closing the agent configuration window without saving discards the changes.
+- An agent cannot list itself as a sub-agent, and the same sub-agent cannot be added more than once to a profile.
+
+## Switch the current agent
+
+You can switch the current agent through the input field or the status bar:
+
+- **Through the input field**: Enter `#` to display a list of available agents above the input field. Click an agent, or select one with the up and down arrow keys and press **Enter** to confirm.
+- **Through the status bar**: Click the agent name in the status bar above the input field to open the agent picker, then select the agent to use.
+
+After switching, iCode immediately uses the selected agent for subsequent requests. The current agent is grayed out in the list, with a hollow circle before its name. The list shows only profiles that can serve as main agents.

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

@@ -0,0 +1,117 @@
+# Configure approval modes
+
+When an agent makes a tool call, such as running a Shell command or writing a file, iCode may require approval first. This guide explains how to choose an approval mode and handle approval requests in the terminal user interface (TUI), as well as how approval settings differ across ways of running iCode.
+
+## Understand the three approval modes
+
+The approval mode determines how iCode handles tool calls that require approval. Which calls require approval depends on both the `approval` policy in the agent profile and iCode's safety rules. See the [approval field in the agent profile reference](../../reference/agent-profile.md#approval).
+
+The three approval modes behave as follows:
+
+| Mode | Behavior |
+| --- | --- |
+| MANUAL | Tool calls that require approval open a dialog and wait for a person to approve or decline. |
+| AUTO | An approval judge model evaluates tool calls. Calls judged safe are approved automatically; suspicious calls are flagged for a person to decide. |
+| BYPASS | Tool calls run without asking, even when the agent configuration or safety rules require approval. |
+
+**Approval judge model**: In automatic mode, iCode calls the approval judge model and sends it the current time, the workspace directories, all user prompts of the current turn and the latest of them, and the tool name, tool kind, and arguments. By default, the approval judge uses the current session's model. To change it, press **F10** to open **Settings**, select the **Models & Agents** tab, and change **Approval judge model** in the **Model roles** section.
+
+> **Tip**
+>
+> **Manual mode does not mean every tool call opens a dialog.** It means that calls requiring approval are decided by the user. Calls that do not require approval or qualify for automatic approval run directly. See [Understand automatic approval and safety protections](#understand-automatic-approval-and-safety-protections).
+
+## Switch approval modes in the TUI
+
+Use either of these methods to switch the current approval mode in the TUI:
+
+- Type `/approval` in the input field, then press **Space** or **Enter** to open the approval mode list and choose a mode. You can also specify a mode directly, for example `/approval auto`.
+- Click the approval mode label in the upper-right corner of the interface and choose a mode in the **Approval Mode** dialog.
+
+You can switch modes while a task is running. Approval requests that are already open are unaffected; subsequent tool calls use the new mode.
+
+### Set the default approval mode
+
+With the default settings unchanged, the TUI starts in manual approval mode on its first launch. Switching the current approval mode also updates the default for the next launch: choosing manual or automatic mode saves that mode as the default. Choosing bypass mode applies only to the current run; to avoid continuing to bypass approval protections after a restart, the default for the next launch is saved as automatic mode.
+
+To change only the default for the next launch without changing the current approval mode, press **F10** to open **Settings** and change **Default approval mode** on the **Security** tab. **Settings** does not offer bypass mode as a default that can be saved.
+
+## Handle approval requests in the TUI
+
+Tool calls that require approval open an **Approval Required** dialog showing the tool name and call arguments. For file edits, it also shows the planned diff so you can review changes before they are made.
+
+- Press **Y** to approve or **N** to decline, or click the corresponding button. You cannot close the dialog with **Esc**; you must explicitly approve or decline.
+- When declining, you can provide a reason. The reason is sent to the agent to help it adjust its next steps. Once a reason is entered, the approve button is disabled.
+- In automatic mode, no dialog opens while the approval judge model evaluates a call; **Reviewing** appears, after a spinning icon, to the left of the approval mode label in the upper-right corner. Calls the model judges safe run without a dialog. If the model judges a call suspicious, the dialog opens with the title **Flagged by Auto-Review**, shows the reason, and waits for a person to decide. The cursor starts in the reason field so that a stray key press does not approve the call: type a reason and decline, or press **Tab** to move to the buttons. If the approval judge model is unavailable, or evaluation fails or times out, the dialog opens for a person to decide instead of approving the tool call automatically.
+- To see each call while it is evaluated, press **F10** to open **Settings** and turn off **Show the approval dialog only when Auto-Review flags a call** on the **Security** tab. The dialog then opens at once and shows **Evaluating**: it closes by itself if the model judges the call safe, and you can approve or decline before evaluation finishes.
+
+## Remember approvals
+
+You can let iCode remember a Shell command or a file change you approve, so the same request does not ask you again. The approval dialog for a Shell command or a file write or edit shows a **Remember Approval** box:
+
+1. Check **Don't ask again for this command** (for files: **Don't ask again to modify these files**).
+2. Choose **This session** or **This project**. **This session** also applies after you restore the session; **This project** also applies in your other sessions in the same project.
+3. Select **Approve**.
+
+The next time the agent makes the same request, it runs without a dialog. Only that command, or those files, are remembered; other operations still ask. Approving without checking the box approves this one call only. A few cases are never remembered:
+
+- A call that the approval judge model approves in automatic mode. A call that Auto-Review flags still offers the box, and you can remember it when you approve it.
+- A request you edit in the dialog: the edited call runs once.
+- A command for which the agent names the folder to run in, and requests that touch sensitive files such as credentials or SSH keys.
+- Sub-agents, workflows, MCP tools and other tools.
+
+If a folder or file link changes between your approval and the run, so that the call would act on a different place, the call stops with an error instead of running there.
+
+For a simple command, **Advanced options** offers **Allow arguments added to the end of this command**. Then the remembered command also runs without asking when the agent adds more arguments to its end. Remembering `git push origin main` this way also allows `git push origin main --force`, so the dialog shows a warning. Leave this unchecked unless you trust every argument that could be added.
+
+If iCode cannot save your choice, the call still runs once and a notice says that the approval was not remembered.
+
+### Manage remembered approvals
+
+Use the `icode approvals` command to see and remove what you have remembered:
+
+```bash
+icode approvals list                         # everything you have remembered
+icode approvals list --project /work/demo    # only one project
+icode approvals list --session SESSION_ID --json
+icode approvals revoke GRANT_ID              # remove one approval by its ID from the list
+icode approvals clear --project /work/demo   # remove all approvals for one project
+icode approvals clear --session SESSION_ID   # remove all approvals for one session
+icode approvals clear --all                  # remove everything
+```
+
+Approvals for a session are deleted with that session and are not copied to a branch you create with `/fork`. Approvals for a project stay until you remove them.
+
+## Understand automatic approval and safety protections
+
+The following operations usually run without an approval dialog:
+
+- Safe, read-only Shell commands that do not access sensitive targets, such as `ls`, `cat`, and `grep`.
+- File writes within the working directory's Git repository that do not access sensitive targets.
+
+Shell commands and file reads or writes that access sensitive targets such as `.env` files, credentials, and private keys still go through approval, even for read-only operations or writes within a Git working directory. This protection applies in manual and automatic modes. Bypass mode skips these approval protections.
+
+Skill scripts run locally with the current user's permissions, without sandbox isolation, so they request approval by default. When the session uses bypass mode, skill scripts run without asking. Before installing or running a third-party skill, review its `SKILL.md`, scripts, and related files to make sure they are trustworthy.
+
+Web tools send requests to outside services, so the `web_search` and `web_fetch` kinds also request approval by default, even when the agent's `approval.default` is `auto`. Explicit `approval.overrides` rules for these kinds or tool names still take precedence. In automatic mode the approval judge model may approve them, and in bypass mode they run without asking. See [Configure web tools](./web-tools.md#approve-web-tool-calls).
+
+## Verify approval modes in the TUI
+
+Select the built-in Code agent, then submit this request:
+
+```text
+Use the Shell tool to run icode --version
+```
+
+This command only displays the version and does not modify files, but it is not among the read-only Shell commands approved automatically. Expect the following results:
+
+- In manual mode, the **Approval Required** dialog opens. After approval, the iCode version is displayed.
+- In automatic mode, **Reviewing** appears to the left of the approval mode label while the approval judge model evaluates the command. The model will usually judge it safe, and the iCode version is displayed without an approval dialog. If the model flags it as suspicious, the dialog shows the evaluation reason and waits for a decision.
+- In bypass mode, the command runs and displays the iCode version without an approval dialog.
+
+## Approval modes in other ways of running iCode
+
+Other ways of running iCode use the following approval modes and switching methods:
+
+- **Headless CLI (`icode run`)**: Always bypasses approval and provides no approval-related options.
+- **iCode ACP server**: Defaults to manual mode. Use `icode acp --approval manual|auto|bypass` to set the initial mode. ACP clients that support this capability can also switch the current session's mode.
+- **Browser-hosted TUI (`icode serve`)**: Use the TUI operations described earlier to switch approval modes and handle approval requests.