iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/tui/screens/guides/_docs/en/reference/tool-kinds-and-names.md

@@ -0,0 +1,58 @@
+# Tool kinds and names
+
+iCode uses tool kinds (`tool_kind`) to group tools with similar purposes or sources, and tool names (`tool_name`) to identify individual tools. A kind can contain multiple tools. For example, `filesystem.write` includes `write_file` and `edit_file`.
+
+In the terminal user interface (TUI), enter `/runtime` in the input field, or click the tool count at the right end of the status bar above the input field, to open the "Runtime Details" dialog. The "Tools" tab lists built-in tools grouped by kind, plus sub-agent tools; the "MCP" tab lists MCP tool names grouped by server. Skill and context tools are not listed in the dialog. An agent can only call tools that are currently loaded.
+
+## Overview of kinds and names
+
+"Built-in" means that the kind can be enabled through the `tools.builtins` field in an agent profile.
+
+| Tool kind | Built-in | Purpose or source | Tool names |
+| --- | --- | --- | --- |
+| `shell` | Yes | Run shell commands | The name of the current shell; also includes `git_bash` on Windows when Git Bash is detected, and `list_workspace_dirs` in ACP sessions |
+| `filesystem.read` | Yes | Read files and view images | `read_file`, `view_image` |
+| `filesystem.write` | Yes | Create, overwrite, and edit files | `write_file`, `edit_file` |
+| `search` | Yes | Search file contents and filenames | `grep`, `glob` |
+| `web_search` | Yes | Search the web for URLs and summaries | `web_search` |
+| `web_fetch` | Yes | Read a web page by URL | `web_fetch` |
+| `ask_user` | Yes | Ask the user questions during a task | `ask_user` |
+| `sleep` | Yes | Wait | `sleep` |
+| `doc_converter` | Yes | Convert PDF and Office documents | `convert_document` |
+| `todo` | Yes | Maintain to-do items | `todo_write` |
+| `sub_agent` | No | Call sub-agents | Determined by the agent profile |
+| `mcp` | No | MCP server tools and on-demand loading controls | Determined by the MCP server and its configuration |
+| `skill` | No | Load skills, read resources, and run scripts | `load_skill`, `read_skill_resource`, `run_skill_script` |
+| `context` | No | Compact and query conversation context | `compress_context`, `recall_context`, `list_compressed_contexts` |
+
+Tool availability also depends on the current agent, model capabilities, and how iCode is run. For example, `view_image` is only provided to models that support image input, and the headless CLI mode `icode run` does not provide `ask_user`.
+
+`web_search` and `web_fetch` are not enabled in any agent shipped with iCode. When an agent includes them, either tool is left out while its mode is `off` or if the model's provider runs a web tool of the same name. See [Configure web tools](../guides/configuration/web-tools.md).
+
+## Shell tool names
+
+The main tool in the `shell` kind uses the name of the current shell, such as `zsh`, `bash`, `pwsh`, `powershell`, or `cmd`. On Windows, when Git Bash is detected, iCode also provides a `git_bash` tool alongside the main shell tool. The actual names depend on the operating system and the shells detected by iCode.
+
+ACP sessions also provide `list_workspace_dirs`, which lists the primary working directory and any additional working directories provided by the ACP client.
+
+## Sub-agent tool names
+
+In the `sub_agent` kind, each tool corresponds to a callable sub-agent. Its tool name is determined by [`sub_agents.agents[].tool_name`](./agent-profile.md#sub_agents) in the agent profile. If this field is omitted, the sub-agent's profile name is used by default.
+
+An explicitly set `tool_name` must start with a letter or underscore, followed only by letters, digits, or underscores. When `tool_name` is omitted, the profile name is used as is, so the tool name may contain hyphens or start with a digit. Tool names must be unique within the same parent agent.
+
+## MCP tool names
+
+The `mcp` kind includes tools provided by MCP servers. iCode first replaces any characters in a tool name other than English letters, digits, underscores, and hyphens with hyphens. If `tool_name_prefix` is not set, this processed name is used directly.
+
+When `tool_name_prefix` is set, iCode also removes leading underscores and hyphens from the processed name, then combines it as `<prefix>_<tool_name>`. If removing these characters leaves an empty name, only the prefix is used. For example, if a server provides `search` or `_search` and the prefix is `github`, the final name is `github_search` in both cases.
+
+When configuring `approval.overrides` or a hook's `match.tool_name`, **use the actual tool name shown in the "MCP" tab of the "Runtime Details" dialog**.
+
+When on-demand loading is enabled, iCode also provides three control tools:
+
+- `<prefix>_list_mcp_tools`
+- `<prefix>_load_tool`
+- `<prefix>_unload_tool`
+
+If `tool_name_prefix` is not configured, the control tools use the prefix `mcp_` followed by the MCP server name. Every character in the server name other than an ASCII letter or digit is encoded as `-<hex code>-`; for example, server `my-server` gives `mcp_my-2d-server_list_mcp_tools`. Very long server names are shortened and end with a hash. Control tools are not listed in the "MCP" tab of the "Runtime Details" dialog.

chrys/app/tui/screens/guides/_docs/en/reference/tui-slash-commands.md

@@ -0,0 +1,76 @@
+# TUI slash command reference
+
+Slash commands are shortcuts entered in the terminal user interface (TUI) input field. Use them to manage sessions, switch configurations, view information, and open feature dialogs.
+
+## Enter slash commands
+
+A slash command must start at the beginning of the input, with the command and its arguments on the same line.
+
+- Valid example: `/diff` runs as a command.
+- Invalid example: `Please run /diff` does not trigger a command.
+
+After you type `/`, a command suggestion list appears above the input field. Keep typing to filter commands; press **Tab** to complete the selected command. If a command does not show argument suggestions, you can press **Enter** immediately after completing it to run it. If it accepts arguments, you can also continue typing arguments before pressing **Enter**.
+
+The following commands show argument suggestions: `/theme`, `/language`, `/approval`, `/buddy`, `/agents`, `/settings`, and `/man`. The list opens when you complete one of these commands with **Tab**, or when you type the full command and press **Space** or **Enter**.
+
+- Example: type `/approval` and press **Space** to see `Manual`, `Auto`, and `Bypass`.
+
+Once the argument suggestion list appears, use the up and down arrow keys to select an item and press **Enter** to run it, or click the item with the mouse.
+
+## View command help
+
+Enter `/man` to view help for built-in slash commands:
+
+- `/man`: press **Space** or **Enter** to show the list of commands with help available. Select a command to open its detailed help.
+- `/man <command>`: open detailed help for a specific command. `command` can be a command name or alias, such as `/man theme`, `/man diff`, or `/man quit`.
+
+## Command reference
+
+The following table lists the built-in slash commands in iCode.
+
+In this table:
+
+- `<arg>` denotes a required argument; `[arg]` denotes an optional argument.
+- `|` separates alternative values. For example, `[N|all]` accepts a positive integer or `all`.
+- `<`, `>`, `[`, and `]` are argument notation and should not be typed as part of the command.
+
+| Command and usage | Aliases | Description | Options |
+| --- | --- | --- | --- |
+| `/new` | — | Start a new session and keep the current session. See [Switch to a new session](../guides/daily-use/sessions.md#switch-to-a-new-session). | — |
+| `/clear` | — | Delete the current session and start a new one. This cannot be undone after confirmation. See [Switch to a new session](../guides/daily-use/sessions.md#switch-to-a-new-session). | — |
+| `/exit` | `/quit` | Exit iCode and return to the terminal. | — |
+| `/resume` | — | Restore the most recent chat session; workflow sessions are skipped. See [Resume an existing session](../guides/daily-use/sessions.md#resume-an-existing-session). | — |
+| `/fork` | — | Create an independent branch of the current session. After creation, the current window stays in the original session. You can choose to stay there or switch to the branch. | — |
+| `/rename [title]` | — | Set or clear the session title. See [Change the session title](../guides/daily-use/sessions.md#change-the-session-title). | `title`: a custom title to apply immediately. Omit it or enter only whitespace to open the title editor. |
+| `/sessions` | — | Open the session dialog to browse, restore, or delete sessions. See [Manage and resume sessions](../guides/daily-use/sessions.md). | — |
+| `/theme [theme]` | — | Switch the interface theme. See [Appearance](../guides/configuration/settings.md#appearance). | `theme`: switch directly to the specified theme. With no argument, press **Space** or **Enter** to show available themes. |
+| `/language [locale]` | — | Switch the interface language. See [Appearance](../guides/configuration/settings.md#appearance). | `locale`: switch directly to the specified language. Supported values are `system` (follow the system), `en` (English), and `zh-Hans` (Simplified Chinese). With no argument, press **Space** or **Enter** to show available values. |
+| `/chdir [path]` | `/cd` | Switch the working directory for the current session. See [Switch working directories in a session](../guides/daily-use/workspaces.md#change-the-working-directory-during-a-session). | `path`: an existing target directory, specified as an absolute path or a path relative to the current working directory. Omit it to open the directory picker. |
+| `/copy [N]`<br>`/copy agent [N\|all]`<br>`/copy user [N\|all]`<br>`/copy all` | — | Copy conversation content to the clipboard. | No argument: copy the most recent agent message (text the agent shows between tool calls counts as a separate message).<br>`N`: the number of recent agent messages to copy; must be a positive integer. `/copy N` is shorthand for `/copy agent N`.<br>`agent [N\|all]`: copy the most recent `N` agent messages or all agent messages. If no count is given, copy the most recent one.<br>`user [N\|all]`: copy the most recent `N` user messages or all user messages. If no count is given, copy the most recent one.<br>`all`: copy the full conversation history. |
+| `/fold` | — | Collapse or expand all tool call groups in the current conversation. Collapsed groups show only their summary headers, making long sessions easier to browse. | — |
+| `/diff` | — | Open the diff view to see files added, modified, and deleted during the current session line by line, so you can review the agent's changes. | — |
+| `/rollback`<br>`/rollback <N>`<br>`/rollback to <N>` | — | Roll back the conversation while keeping current file changes, or roll back the conversation and restore the file changes that iCode can recover. Rollback cannot be undone. | No argument: open the rollback picker, with the most recent available target selected by default. The file restoration option in the lower-left corner of the "Rollback" dialog (its label includes the file count) controls whether file changes are also restored.<br>`N`: immediately discard the most recent `N` turns; must be a positive integer. A turn starts with a user submission and ends when that agent run finishes.<br>`to N`: keep turns 1 through `N` and discard later turns. `N` must be a nonnegative integer; `0` returns to the start of the session.<br>Both `/rollback N` and `/rollback to N` run immediately and restore the file changes from the discarded turns that iCode can recover. |
+| `/approval [manual\|auto\|bypass]` | — | Switch the current approval mode. The chosen mode is also saved as the default for the next launch (`bypass` is saved as `auto`). See [Configure approval modes](../guides/configuration/approval.md). | `manual`: the user decides on calls that require approval.<br>`auto`: the approval judge model decides; calls it cannot confirm are safe still go to the user.<br>`bypass`: skip approval for tool calls.<br>No argument: press **Space** or **Enter** to show approval mode suggestions. |
+| `/models` | — | Open the model configuration dialog. See [Configure models](../guides/configuration/models.md). | — |
+| `/buddy [command]` | — | Manage your Buddy companion. Only `hatch` is available before hatching; the other options become available afterward. | No argument: press **Space** or **Enter** to show available commands.<br>`hatch`: hatch a new companion.<br>`info`: show companion information.<br>`pet`: interact with the companion and generate a response.<br>`mute`: toggle companion notifications.<br>`name <new-name>`: rename the companion to `new-name`. |
+| `/agents [target]` | `/agent`<br>`/config` | Open the agent configuration dialog. See [Open the agent configuration window](../guides/configuration/agents.md#open-the-agent-configuration-window). | No argument: press **Space** or **Enter** to show available tabs.<br>`target`: open a specific tab directly. Available values are `basic`, `instructions`, `tools`, `sub-agents`, `skills`, `mcp`, `memory`, and `compaction`.<br>Argument aliases: `subagents` is equivalent to `sub-agents`; `skill` is equivalent to `skills`. |
+| `/runtime` | `/details` | Open the "Runtime Details" dialog to view the current model profile and model ID, built-in tools grouped by tool kind, sub-agent tools, MCP tools grouped by server, skills grouped by source, loaded hooks, and preconfigured memory files. | — |
+| `/settings [tab]` | — | Open the settings dialog. See [Configure iCode settings](../guides/configuration/settings.md#settings-dialog). | `tab`: open a specific tab directly. Available values are `general`, `models`, `security`, `sessions`, `tools`, and `notifications`. With no argument, press **Space** or **Enter** to show available tabs. |
+| `/workflow` | — | Open Workflow mode and select a workflow. See [Create and run workflows](../guides/running/workflows.md). | — |
+| `/help` | — | Open the "iCode User Guide" dialog, which shows this documentation. You can also press **F8** or click `f8 Help` in the footer. | — |
+| `/man [command]` | — | Show iCode command help. | No argument: press **Space** or **Enter** to show commands with help available.<br>`command`: a command name or alias. Show the specified command's name, usage, description, aliases, and options. |
+
+## Skill commands
+
+Skills loaded at runtime can be invoked using `/skill-name`. When you submit a skill command, iCode asks the agent to use that skill for the current turn's task.
+
+You can optionally add a task description after the skill name. It is submitted along with the skill command, and the skill's instructions determine how it is handled.
+
+For example, with a skill named `review` loaded:
+
+- `/review`: invoke the skill.
+- `/review Check the current changes for potential issues`: invoke the skill and describe the task.
+
+Skill commands are not built-in iCode commands. If a skill has the same name as a built-in command, the built-in command takes precedence.
+
+For instructions on installing and using skills, see [Install and use skills](../guides/extensions/skills.md#use-skills).