iCode-TUI 0.29.1__py3-none-any.whl

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

@@ -0,0 +1,175 @@
+# Install and use skills
+
+A skill is a reusable set of instructions that can include reference materials and scripts to extend an agent's ability to handle specific tasks. This guide explains how to install skills for agents of the "Built-in" type, confirm that they have loaded, and use them. Support for skills and their configuration in external ACP agents is determined by the external agent.
+
+## Skill installation locations
+
+Choose an installation location based on where the skill should be available and whether it needs to be shared:
+
+| Location | When to use it | How iCode loads it |
+| --- | --- | --- |
+| iCode user skills directory | Make skills available to all agents of the "Built-in" type in iCode | Always loaded automatically |
+| Agent Skills shared directory | Share skills between iCode and other tools that support Agent Skills | Loaded automatically by default; can be disabled per agent |
+| `<working-directory>/.agents/skills` | Make skills available only in the current working directory | Loaded only after you turn on “Load project skills”; can also be disabled per agent |
+| Custom directory | Load skills from a specific location | Must be added manually to the corresponding agent's configuration |
+
+Here, `<working-directory>` is the current working directory. Skills in a working directory come with the repository, so iCode does not load them until you turn on “Load project skills” under “Settings → Security → Project trust” (`project.skills_enabled`). When the working directory has skills that are not loaded, iCode shows a notice. When you switch working directories, iCode reloads the skills from the new working directory.
+
+The two user-level skills directories have the following paths on each platform:
+
+| Directory | macOS and Linux | Windows |
+| --- | --- | --- |
+| iCode user skills directory | `~/.chrys/skills` | `%APPDATA%\chrys\skills` |
+| Agent Skills shared directory | `~/.agents/skills` | `%USERPROFILE%\.agents\skills` |
+
+For the first three installation locations, copy or move the skill directory to the corresponding location. For a custom directory, there is no need to move the skill; add its directory to the corresponding agent's configuration.
+
+iCode searches for `SKILL.md` files in configured skills directories and up to two levels of subdirectories. Once it finds a `SKILL.md`, it recognizes the containing directory as a skill directory and stops searching for nested skills within it.
+
+## Install and enable skills
+
+The iCode user skills directory is always loaded automatically. The Agent Skills shared directory is also loaded automatically by default. The current working directory's skills directory loads once “Load project skills” is on. If a source has been disabled in the agent's configuration, enable it again. For a custom directory, add it to the corresponding agent's configuration.
+
+To define an inline skill without files directly in an agent's YAML, see [Agent profile reference](../../reference/agent-profile.md#skillsinline).
+
+To check or adjust an agent's skill configuration:
+
+1. Enter `/agents skills` in the input field to open the current agent's "Skills" tab. To configure another agent, select it in the list on the left.
+2. Confirm that the source corresponding to the skill's location is enabled:
+
+   * "Load skills from user folder (if present)" corresponds to the Agent Skills shared directory.
+   * "Load skills from working folder (if present)" corresponds to `<working-directory>/.agents/skills`. It takes effect only while “Load project skills” is on in “Settings → Security → Project trust”.
+
+3. If the skill is in another directory, click "+ Add" and enter the directory containing the skill:
+
+   * For a path relative to the working directory, select "Workspace relative".
+   * For an absolute path, clear "Workspace relative".
+
+4. If the skill includes scripts, confirm that their extensions are listed in "Allowed Script Extensions". The defaults are `.py`, `.sh`, and `.ps1`; other available extensions include `.ts`, `.js`, and `.rb`. The interpreters required to run the scripts must already be installed.
+5. To adjust the maximum runtime for skill scripts, enter a positive integer in "Script Execution Timeout (seconds)".
+6. Click "Save".
+
+> **Note**: Skill scripts run as local processes without sandbox isolation. Before installing a third-party skill, inspect its `SKILL.md`, scripts, and other related files, and install skills only from trusted sources. iCode runs skill scripts through the `run_skill_script` tool. Whether this tool requires confirmation depends on the agent's approval rules and the [current approval mode](../configuration/approval.md).
+
+When a skill script prints more than 32 MiB to standard output or standard error, iCode keeps only the beginning and end of that output; the middle is not saved, and the result tells the agent how much was left out.
+
+## Confirm that skills have loaded
+
+After you save the agent's configuration and return to the session, iCode reloads its skills. If you add skill directories or change their files directly on disk, iCode does not monitor those changes in real time. The next time you send a message, iCode rescans the current agent's enabled skills directories before processing the message.
+
+Use either of the following methods to confirm that a skill has loaded:
+
+* Enter `/` in the input field, then start typing the skill name (for example, `/release-`). The autocomplete list filters matches as you type. If the skill name appears in the "Loaded Skills" group, it has loaded.
+* Enter `/runtime`, or click the skill count at the right end of the status bar above the input field, to open "Runtime Details". Check the skill name and source in the "Skills" tab.
+
+If the skill does not appear, check the following in order:
+
+* For the Agent Skills shared directory or working directory skills directory, confirm that the corresponding option is enabled (the working directory skills directory also needs “Load project skills”). For a custom directory, confirm that it has been added to the current agent.
+* Confirm that the skill directory is at the selected location or within at most two levels of subdirectories.
+* Confirm that the skill meets the [basic requirements for creating skills](#basic-requirements-for-creating-skills).
+
+## Use skills
+
+Skills usually do not need to be invoked manually. When a task matches a skill's description, the agent automatically loads its full instructions and follows them to complete the task. For example:
+
+```text
+Draft release notes based on the changes in the current repository since the previous release.
+```
+
+You can also explicitly invoke a loaded skill by starting a message with `/skill-name`. For example:
+
+```text
+/release-notes Draft release notes based on the changes in the current repository since the previous release.
+```
+
+If the skill name matches a built-in iCode slash command, you cannot invoke it explicitly with `/skill-name`. In that case, name the skill directly in your message, for example:
+
+```text
+Use the release-notes skill to draft release notes based on the changes in the current repository since the previous release.
+```
+
+The first time the skill loads in the current session, a `load_skill` tool call card appears with the skill name `release-notes`. The agent then follows the skill's instructions to complete the task.
+
+## Priority for skills with the same name
+
+Skills loaded from the [installation locations](#skill-installation-locations) listed earlier are directory-based skills, each containing a `SKILL.md`. iCode also supports inline skills defined directly in an agent profile. These do not require a skill directory or `SKILL.md`.
+
+If multiple skills have the same name, iCode loads only the one with the highest priority. Priority, from highest to lowest, is:
+
+1. Directories added manually in the agent's "Skills" tab, with those higher in the list taking priority (new directories are added at the top).
+2. The iCode user skills directory.
+3. The Agent Skills shared directory.
+4. Skills in the current working directory.
+5. Inline skills in the agent profile, in their definition order.
+
+If multiple skills with the same name exist within one installation location or custom directory, their discovery order is unspecified. To ensure that a particular version loads, keep only that version.
+
+## Appendix
+
+### Basic requirements for creating skills
+
+Each skill uses its own directory with a `SKILL.md` at the directory root. The following is a minimal skill that iCode can load:
+
+```markdown
+---
+name: release-notes
+description: Draft user-facing release notes from commit history
+---
+
+# Draft release notes
+
+1. Read the commit history since the previous release.
+2. Group changes into additions, fixes, and compatibility changes.
+3. Include only changes observable to users.
+```
+
+#### Write `SKILL.md`
+
+`SKILL.md` must use UTF-8 encoding. It starts with a YAML configuration block enclosed by `---`, also called frontmatter, followed by instructions for the agent. The frontmatter should be a valid YAML mapping; if it is not valid YAML, iCode tries to read it line by line and logs a warning. iCode validates the file as follows:
+
+| Content | Loading requirements |
+| --- | --- |
+| frontmatter | Required; the top-level content must be a YAML mapping, without anchors (`&`) or aliases (`*`), at most 16,384 characters long and nested at most 64 levels deep |
+| `name` | Required; must exactly match the skill directory name; 1-64 characters long; may contain only lowercase letters, digits, and hyphens (`-`). Uppercase letters, underscores (`_`), and other characters are not allowed. Must not start or end with a hyphen or contain consecutive hyphens |
+| `description` | Required; text of at most 1,024 characters. Describe both the skill's purpose and when to use it to help the agent decide when to load it |
+| `compatibility` | Optional; text of at most 500 characters |
+| `license`, `allowed-tools` | Optional; iCode reads their text without further validation |
+| `metadata` | Optional; must be a YAML mapping whose values are plain text or numbers, otherwise iCode does not retain this field |
+| Body | iCode imposes no additional length or structure restrictions |
+
+Use valid YAML for the frontmatter to ensure that the skill loads reliably. iCode does not load a skill if its frontmatter, `name`, or `description` is missing, or if field values fail the validation rules above. An optional field given as a list or mapping is ignored.
+
+The optional fields serve the following purposes:
+
+* `compatibility`: Describes the runtime environment the skill depends on, such as supported products, required system packages, or network access requirements.
+* `license`: Declares the skill's license. This can be a license name or the name of a license file in the skill directory.
+* `allowed-tools`: Declares tools that may be approved in advance under the Agent Skills specification. This field is still experimental. iCode currently only reads and retains its value; it does not automatically grant tool permissions based on it.
+
+iCode skill directories and the `SKILL.md` format follow the common Agent Skills specification. For details on these fields and the complete skill specification, see the [official Agent Skills specification](https://agentskills.io/specification).
+
+#### Add scripts and resources
+
+A skill can include scripts, reference materials, and other text resources as needed.
+
+For example:
+
+```text
+release-notes/
+├── SKILL.md
+├── scripts/
+│   └── collect.py
+├── references/
+│   └── style-guide.md
+└── assets/
+    └── template.html
+```
+
+iCode recognizes text files as skill resources only if they have one of these extensions: `.md`, `.txt`, `.rst`, `.html`, `.htm`, `.xml`, `.svg`, `.json`, `.jsonl`, `.yaml`, `.yml`, `.toml`, `.csv`, `.tsv`, `.ini`, `.cfg`, `.css`.
+
+Resource files must use UTF-8 encoding. In addition:
+
+* Script extensions must be listed in the agent configuration's "Allowed Script Extensions".
+* iCode reads only files at the skill directory root and in its immediate subdirectories. For example, it discovers `guide.md` and `references/guide.md`, but ignores `references/api/guide.md`.
+* Within a skill directory, iCode skips files and directories accessed through symbolic links or Windows directory junctions. Both point to other locations on disk. To use their contents, place the actual files in the skill directory.
+
+Files that do not meet the extension, directory depth, or link rules do not appear in the skill's resource or script list. Reading a resource fails if it is not valid UTF-8 text. These issues do not prevent an otherwise valid `SKILL.md` from loading.

chrys/app/tui/screens/guides/_docs/en/guides/running/icode-acp.md

@@ -0,0 +1,61 @@
+# Use the iCode ACP server
+
+Editors and development tools that support the Agent Client Protocol (ACP) can connect to iCode to use iCode agents in the client. The ACP client provides the interface, while iCode communicates with it over standard input and output (stdio), runs agents, executes tools, and saves sessions.
+
+Before you begin, install iCode and configure at least one model. For preparation steps, see [Getting started with iCode](../../start/getting-started.md) and [Configure models](../configuration/models.md).
+
+## Connect to iCode
+
+In the ACP client's "Add agent" or similar settings, enter the following:
+
+| Field | Value |
+| --- | --- |
+| Executable | `icode` |
+| Arguments | `acp` |
+
+This is equivalent to the client starting:
+
+```shell
+icode acp
+```
+
+If the client provides only a single launch command field, enter the full command, `icode acp`.
+
+After saving the configuration, verify the connection:
+
+1. Start or connect to iCode in the client.
+2. Create a session and send a message.
+3. Confirm that the client displays a reply from iCode. A reply means the connection is configured successfully.
+
+## Configure startup options
+
+`icode acp` supports the following startup options. If the client has separate executable and arguments fields, append these options after `acp`.
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `-a`, `--agent <agent>` | `Code` | Specify the built-in or custom agent for new sessions, by name, display name, or ID. Restored sessions keep the agent they were saved with. To create a custom agent, see [Configure agents](../configuration/agents.md). |
+| `--approval <mode>` | `manual` | Set the initial approval mode for every session this ACP server creates or restores: `manual`, `auto`, or `bypass`. The `bypass` approval mode skips approval and executes tool calls directly; use it with care. For the rules of each mode, see [Configure approval modes](../configuration/approval.md). |
+| `-C`, `--workdir <directory>` | None | Provide a default working directory for sessions where the client does not send one. |
+| `--ask-user-timeout <seconds>` | No time limit | Limit how long to wait for the client to answer an agent's question. Omit this option or set it to `0` or a negative value to wait without a time limit. |
+
+## Working directories and sessions
+
+When creating or restoring a session, the client can pass the project's working directory to iCode. The directory supplied by the client must be an existing absolute path. If the client does not provide a working directory, iCode uses the directory specified by `--workdir <project-directory>`. If both are provided, the client's working directory takes precedence.
+
+iCode checks `--workdir` at startup. The specified directory must exist even if the client will later provide a working directory; otherwise, iCode cannot start.
+
+Session data is saved in iCode's session storage directory, rather than the working directory. To find the actual location, see [Find the session ID and storage location](../daily-use/sessions.md#find-the-session-id-and-storage-location). iCode records the working directory when a session is created. Listing sessions through an ACP client shows only sessions that match the current working directory. iCode refuses to restore a session if the working directory does not match.
+
+Sessions used through an ACP client also appear in the TUI's "Chat Sessions" window once you check "ACP" there. See [Resume an existing session](../daily-use/sessions.md#resume-an-existing-session).
+
+## Interact through the client
+
+iCode sends agent replies and tool call status to the client. When the client cancels a task, iCode interrupts the current task.
+
+If the current model supports image input, a prompt can include images in PNG, JPEG, GIF, or WebP format. A prompt with an image in another format is rejected, and the client receives an error.
+
+If the client supports session management, a closed session can still be restored in the same working directory. Deleting a session removes the session record saved by iCode, and the session can no longer be restored in iCode.
+
+To use the question feature through an ACP client, the client must support iCode's `_chrys/request_input` extension request (shown as `chrys/request_input` in ACP SDKs that add the underscore prefix automatically). iCode uses this request to send the agent's questions to the client and receive the user's answers; a client that does not support it cannot complete tasks that require user answers. Use `--ask-user-timeout` to limit how long iCode waits for an answer.
+
+If the client supports switching approval modes or models, it can change the corresponding settings for the current session. These switches, like the initial mode set with `--approval`, are not written to iCode's local configuration. If the client uses iCode's extension requests to change settings or agent and model profiles, however, those changes are written to iCode's local configuration. The next time the ACP server starts, the initial approval mode still comes only from `--approval`; other initial settings are determined by the local configuration and the startup arguments for that launch. Model profiles and available agents remain managed through iCode's local configuration.

chrys/app/tui/screens/guides/_docs/en/guides/running/icode-run.md

@@ -0,0 +1,190 @@
+# Run headless tasks with icode run
+
+`icode run` runs a task in the terminal and returns the agent's final response when it finishes. It does not open the terminal user interface (TUI). While the task runs, it shows what the agent is doing, one line at a time, making it suitable for one-off tasks, scripts, and automated workflows.
+
+This guide explains how to specify a task, agent, model, working directory, and session for `icode run`, how to read or hide its progress, and how to obtain JSON output for use in programs.
+
+## Before you begin
+
+Before running a task:
+
+- Install iCode and configure at least one working model. See [Getting started with iCode](../../start/getting-started.md) and [Configure models](../configuration/models.md).
+- Choose an agent. The built-in `QA` agent appears as "Q&A Agent" in the TUI and is instructed not to modify anything, but it can run shell commands, and `icode run` does not ask for approval before running them; the `Code` agent can modify files and run commands. A custom agent's capabilities depend on its configuration. See [Configure agents](../configuration/agents.md).
+- If the task might modify files, save any work that has not been written to disk and run it in a working directory you can restore, such as a Git repository with the current changes committed.
+
+> **Note**
+>
+> `icode run` always bypasses tool approval. The agent does not wait for confirmation when calling the shell, writing files, or running skills. Only run trusted agents and tasks in trusted working directories.
+
+`icode run` cannot interact with a person while running; include the task requirements and necessary context in the prompt before starting.
+
+## Run a task
+
+Run the command in your project directory and specify an agent with `-a` or `--agent`. Enclose task text in quotes if it contains spaces:
+
+```shell
+icode run "Summarize this project's directory structure and main modules" --agent QA
+```
+
+While the task runs, iCode shows its progress. When the task finishes, it shows a summary line and then the agent's final response. For example:
+
+```text
+• Q&A Agent ready · Example Model · session 8de5057d58ff · ~/projects/demo
+I'll start with the top-level layout.
+→ shell  ls
+  ✓ 0.1s
+→ read   README.md
+  ✓ 0.0s
+
+✓ Done · 8.2s · 2 tool calls · session 8de5057d58ff
+The project has three main parts: ...
+```
+
+See [Read the progress](#read-the-progress) for what each line means. Control characters in the response that could change your terminal are shown as `�`; when you redirect the output to a file or another program, or add `--json`, the response is kept exactly as written. If the task fails, the error message is written to standard error (`stderr`), and the command exits with a nonzero status. When iCode can tell why a model request failed, the message says so, and a `detail:` line below it shows the original error text.
+
+Use `Code` when you need the agent to modify or verify code:
+
+```shell
+icode run "Fix the login form validation error and run the relevant tests" --agent Code
+```
+
+These tasks may modify files in the working directory and execute commands. Before running one, check that the prompt, agent, and current directory are what you intend.
+
+Run `icode run -h` or `icode run --help` to see the options supported by the current version.
+
+## Read the progress
+
+Progress lines are written to standard error (`stderr`); the final response is written to standard output (`stdout`). In a terminal you see both. When you save the response with `>` or pass it to another program, only the response goes there:
+
+```shell
+icode run "Write release notes for the latest changes" --agent QA > notes.md
+```
+
+Each line shows one step:
+
+| Line | Meaning |
+| --- | --- |
+| `• Q&A Agent ready · …` | The agent has started, with its model, session and working directory. |
+| Plain text | What the agent says between steps. |
+| `→ read   README.md` | The agent calls a tool: here, it reads a file. |
+| `✓ 0.1s` or `✗ exit 1 · 2.5s` | The tool finished, or failed with the reason, and how long it took. |
+| `↳ Explore → grep   TODO` | A sub-agent's step, named after the sub-agent. |
+| `↻ … Retrying in 7s (attempt 2/18)` | A model request failed for a temporary reason and will be tried again. |
+| `Todo 1/3 · → Running tests` | The agent's to-do list changed. |
+| `Warning: …` | Something worth knowing that does not stop the task. |
+| `✓ Done · 8.2s · 2 tool calls · session …` | The task finished: its duration, how many tools the agent called, and its session. |
+
+To see only warnings, errors and the final response, add `-q` or `--quiet`:
+
+```shell
+icode run "Summarize this project" --agent QA --quiet
+```
+
+## Specify a working directory
+
+Use `-C` or `--workdir` to specify the working directory the agent uses to handle files and execute commands, without first changing directories in the terminal:
+
+```shell
+icode run "Review the uncommitted changes and explain the risks" --agent QA --workdir <project-directory>
+```
+
+Replace `<project-directory>` with the actual project path. You can use an absolute path or a path relative to the directory where you run the command. The path must point to an existing directory.
+
+## Read a task from a file
+
+For tasks that are long, need version control, or are generated by a script, put the task in a text file and read it with `-t` or `--task`:
+
+```shell
+icode run --task prompts/review.md --agent Code --workdir <project-directory>
+```
+
+`--task` does not require a particular file extension. iCode reads the file's contents and uses them as the prompt for this task. The task file path can be absolute or relative. For a relative path, iCode looks for the file in the directory specified by `--workdir`, or in the directory where you run the command if `--workdir` is omitted.
+
+Each run accepts only one prompt source: either a prompt passed directly or a file specified with `--task`. You cannot use both together.
+
+## Choose an agent and model
+
+`icode run` requires an agent specified with `--agent`. Run `icode agents` to list the available agent profiles:
+
+```text
+Default  Name  Display Name  ID            Model
+   *     Code  Code Agent    b011c0de0001  active
+         QA    Q&A Agent     b0119a000005  Example Model
+```
+
+Some rows and columns are omitted from this example. `Example Model` is a fictional model profile.
+
+You can use `Name`, `Display Name`, or `ID` as the value of `--agent`. A `Model` value of `active` means the agent uses the currently active model profile; a specific name means it uses a bound model profile.
+
+For agents that use the `active` model, you can specify a model profile for this run with `-m` or `--model`. For agents with a bound model, `--model` has no effect.
+
+Run `icode models` to list the available model profiles:
+
+```text
+Active  ID            Name           Provider  API   Model          Context  Flags
+   *    0123456789ab  Example Model  openai    chat  example-model  200k     stream
+```
+
+The `*` in the `Active` column marks the model profile that is active by default. You can use either `ID` or `Name` as the value of `--model`.
+
+## Get JSON output
+
+With `--json`, successful results are written as JSON objects to standard output (`stdout`), and errors and warnings are written as JSON objects to standard error (`stderr`). No progress is shown. For example:
+
+```shell
+icode run "hello" -a QA --json
+```
+
+The following is actual output from a run:
+
+```json
+{"session_id": "8de5057d-58ff-477e-9158-2f1b8d8e9fc0", "result": "Hello! I'm iCode, a read-only Q&A assistant for this codebase. I can help you with questions about the code, architecture, APIs, conventions, and how things work — with file and line references so you can jump straight to the source.\n\nWhat would you like to know?", "duration": 9.018}
+```
+
+Here, `session_id` is the ID of the session this task belongs to, `result` is the agent's final response, and `duration` is the task's duration in seconds.
+
+When reading a task file that does not exist:
+
+```shell
+icode run --task missing.md -a QA --json
+```
+
+Standard error output:
+
+```json
+{"error": "Task file does not exist: missing.md", "code": "task_file_not_found"}
+```
+
+`error` describes the error, and `code` identifies the error category for use in programs. This error occurs before a session is created, so it has no `session_id`. If an error occurs after the task starts, such as a failed model request, the output also includes `session_id`.
+
+## Continue an existing session
+
+For an ongoing conversation, use `-s` or `--session` to resume an existing session and submit another task based on the conversation so far. Without `-C` or `--workdir`, the restored session uses its saved working directory rather than the directory where you run the command. `-C` or `--workdir` uses the directory you specify instead. For automation tasks that need a known working directory, specify `-C` or `--workdir` explicitly. If the session's saved working directory no longer exists, iCode stops with an error; use `-C` or `--workdir` to continue the session in another directory.
+
+In headless mode, get the session ID from the `session_id` field in the first turn's JSON output:
+
+```shell
+icode run "Review the current changes and list the tests that need to be added" --agent Code --json
+```
+
+Pass the returned session ID to the second turn:
+
+```shell
+icode run "Add the missing tests based on the previous turn's findings" --agent Code -s <session-id> --json
+```
+
+Replace `<session-id>` with the session ID returned by the first turn.
+
+Sessions created or continued with `icode run` also appear in the TUI's "Chat Sessions" window once you check "CLI" there. See [Resume an existing session](../daily-use/sessions.md#resume-an-existing-session).
+
+## Exit status
+
+Automation scripts can use the exit status to determine the outcome:
+
+| Status | Meaning |
+| --- | --- |
+| `0` | The agent completed normally and returned its final response. |
+| `1` | An error occurred with the configuration, task file, agent, model, session, or task execution. The specific reason is written to standard error. |
+| `2` | Invalid command-line arguments, such as a missing `--agent`, or both or neither of a prompt and `--task`. The usage message is written to standard error as plain text, even with `--json`. |
+| `124` | An internal operation timed out. `icode run` has no overall time limit for a task. |
+| `130` | The run was interrupted. |