@anh3d0nic/qwen-code-termux-ice 1.0.0

package/docs/developers/tools/memory.md

@@ -0,0 +1,44 @@
+# Memory Tool (`save_memory`)
+
+This document describes the `save_memory` tool for Qwen Code.
+
+## Description
+
+Use `save_memory` to save and recall information across your Qwen Code sessions. With `save_memory`, you can direct the CLI to remember key details across sessions, providing personalized and directed assistance.
+
+### Arguments
+
+`save_memory` takes one argument:
+
+- `fact` (string, required): The specific fact or piece of information to remember. This should be a clear, self-contained statement written in natural language.
+
+## How to use `save_memory` with Qwen Code
+
+The tool appends the provided `fact` to your context file in the user's home directory (`~/.qwen/QWEN.md` by default). This filename can be configured via `contextFileName`.
+
+Once added, the facts are stored under a `## Qwen Added Memories` section. This file is loaded as context in subsequent sessions, allowing the CLI to recall the saved information.
+
+Usage:
+
+```
+save_memory(fact="Your fact here.")
+```
+
+### `save_memory` examples
+
+Remember a user preference:
+
+```
+save_memory(fact="My preferred programming language is Python.")
+```
+
+Store a project-specific detail:
+
+```
+save_memory(fact="The project I'm currently working on is called 'qwen-code'.")
+```
+
+## Important notes
+
+- **General usage:** This tool should be used for concise, important facts. It is not intended for storing large amounts of data or conversational history.
+- **Memory file:** The memory file is a plain text Markdown file, so you can view and edit it manually if needed.

package/docs/developers/tools/multi-file.md

@@ -0,0 +1,69 @@
+# Multi File Read Tool (`read_many_files`)
+
+This document describes the `read_many_files` tool for Qwen Code.
+
+## Description
+
+Use `read_many_files` to read content from multiple files specified by paths or glob patterns. The behavior of this tool depends on the provided files:
+
+- For text files, this tool concatenates their content into a single string.
+- For image (e.g., PNG, JPEG), PDF, audio (MP3, WAV), and video (MP4, MOV) files, it reads and returns them as base64-encoded data, provided they are explicitly requested by name or extension.
+
+`read_many_files` can be used to perform tasks such as getting an overview of a codebase, finding where specific functionality is implemented, reviewing documentation, or gathering context from multiple configuration files.
+
+**Note:** `read_many_files` looks for files following the provided paths or glob patterns. A directory path such as `"/docs"` will return an empty result; the tool requires a pattern such as `"/docs/*"` or `"/docs/*.md"` to identify the relevant files.
+
+### Arguments
+
+`read_many_files` takes the following arguments:
+
+- `paths` (list[string], required): An array of glob patterns or paths relative to the tool's target directory (e.g., `["src/**/*.ts"]`, `["README.md", "docs/*", "assets/logo.png"]`).
+- `exclude` (list[string], optional): Glob patterns for files/directories to exclude (e.g., `["**/*.log", "temp/"]`). These are added to default excludes if `useDefaultExcludes` is true.
+- `include` (list[string], optional): Additional glob patterns to include. These are merged with `paths` (e.g., `["*.test.ts"]` to specifically add test files if they were broadly excluded, or `["images/*.jpg"]` to include specific image types).
+- `recursive` (boolean, optional): Whether to search recursively. This is primarily controlled by `**` in glob patterns. Defaults to `true`.
+- `useDefaultExcludes` (boolean, optional): Whether to apply a list of default exclusion patterns (e.g., `node_modules`, `.git`, non image/pdf binary files). Defaults to `true`.
+- `respect_git_ignore` (boolean, optional): Whether to respect .gitignore patterns when finding files. Defaults to true.
+
+## How to use `read_many_files` with Qwen Code
+
+`read_many_files` searches for files matching the provided `paths` and `include` patterns, while respecting `exclude` patterns and default excludes (if enabled).
+
+- For text files: it reads the content of each matched file (attempting to skip binary files not explicitly requested as image/PDF) and concatenates it into a single string, with a separator `--- {filePath} ---` between the content of each file. Uses UTF-8 encoding by default.
+- The tool inserts a `--- End of content ---` after the last file.
+- For image and PDF files: if explicitly requested by name or extension (e.g., `paths: ["logo.png"]` or `include: ["*.pdf"]`), the tool reads the file and returns its content as a base64 encoded string.
+- The tool attempts to detect and skip other binary files (those not matching common image/PDF types or not explicitly requested) by checking for null bytes in their initial content.
+
+Usage:
+
+```
+read_many_files(paths=["Your files or paths here."], include=["Additional files to include."], exclude=["Files to exclude."], recursive=False, useDefaultExcludes=false, respect_git_ignore=true)
+```
+
+## `read_many_files` examples
+
+Read all TypeScript files in the `src` directory:
+
+```
+read_many_files(paths=["src/**/*.ts"])
+```
+
+Read the main README, all Markdown files in the `docs` directory, and a specific logo image, excluding a specific file:
+
+```
+read_many_files(paths=["README.md", "docs/**/*.md", "assets/logo.png"], exclude=["docs/OLD_README.md"])
+```
+
+Read all JavaScript files but explicitly include test files and all JPEGs in an `images` folder:
+
+```
+read_many_files(paths=["**/*.js"], include=["**/*.test.js", "images/**/*.jpg"], useDefaultExcludes=False)
+```
+
+## Important notes
+
+- **Binary file handling:**
+  - **Image/PDF/Audio/Video files:** The tool can read common image types (PNG, JPEG, etc.), PDF, audio (mp3, wav), and video (mp4, mov) files, returning them as base64 encoded data. These files _must_ be explicitly targeted by the `paths` or `include` patterns (e.g., by specifying the exact filename like `video.mp4` or a pattern like `*.mov`).
+  - **Other binary files:** The tool attempts to detect and skip other types of binary files by examining their initial content for null bytes. The tool excludes these files from its output.
+- **Performance:** Reading a very large number of files or very large individual files can be resource-intensive.
+- **Path specificity:** Ensure paths and glob patterns are correctly specified relative to the tool's target directory. For image/PDF files, ensure the patterns are specific enough to include them.
+- **Default excludes:** Be aware of the default exclusion patterns (like `node_modules`, `.git`) and use `useDefaultExcludes=False` if you need to override them, but do so cautiously.

package/docs/developers/tools/sandbox.md

@@ -0,0 +1,91 @@
+## Customizing the sandbox environment (Docker/Podman)
+
+### Currently, the project does not support the use of the BUILD_SANDBOX function after installation through the npm package
+
+1. To build a custom sandbox, you need to access the build scripts (scripts/build_sandbox.js) in the source code repository.
+2. These build scripts are not included in the packages released by npm.
+3. The code contains hard-coded path checks that explicitly reject build requests from non-source code environments.
+
+If you need extra tools inside the container (e.g., `git`, `python`, `rg`), create a custom Dockerfile, The specific operation is as follows
+
+#### 1、Clone qwen code project first, https://github.com/QwenLM/qwen-code.git
+
+#### 2、Make sure you perform the following operation in the source code repository directory
+
+```bash
+# 1. First, install the dependencies of the project
+npm install
+
+# 2. Build the Qwen Code project
+npm run build
+
+# 3. Verify that the dist directory has been generated
+ls -la packages/cli/dist/
+
+# 4. Create a global link in the CLI package directory
+cd packages/cli
+npm link
+
+# 5. Verification link (it should now point to the source code)
+which qwen
+# Expected output: /xxx/xxx/.nvm/versions/node/v24.11.1/bin/qwen
+# Or similar paths, but it should be a symbolic link
+
+# 6. For details of the symbolic link, you can see the specific source code path
+ls -la $(dirname $(which qwen))/../lib/node_modules/@qwen-code/qwen-code
+# It should show that this is a symbolic link pointing to your source code directory
+
+# 7.Test the version of qwen
+qwen -v
+# npm link will overwrite the global qwen. To avoid being unable to distinguish the same version number, you can uninstall the global CLI first
+
+```
+
+#### 3、Create your sandbox Dockerfile under the root directory of your own project
+
+- Path: `.qwen/sandbox.Dockerfile`
+
+- Official mirror image address:https://github.com/QwenLM/qwen-code/pkgs/container/qwen-code
+
+```bash
+# Based on the official Qwen sandbox image (It is recommended to explicitly specify the version)
+FROM ghcr.io/qwenlm/qwen-code:sha-570ec43
+# Add your extra tools here
+RUN apt-get update && apt-get install -y \
+    git \
+    python3 \
+    ripgrep
+```
+
+#### 4、Create the first sandbox image under the root directory of your project
+
+```bash
+QWEN_SANDBOX=docker BUILD_SANDBOX=1 qwen -s
+# Observe whether the sandbox version of the tool you launched is consistent with the version of your custom image. If they are consistent, the startup will be successful
+```
+
+This builds a project-specific image based on the default sandbox image.
+
+#### Remove npm link
+
+- If you want to restore the official CLI of qwen, please remove the npm link
+
+```bash
+# Method 1: Unlink globally
+npm unlink -g @qwen-code/qwen-code
+
+# Method 2: Remove it in the packages/cli directory
+cd packages/cli
+npm unlink
+
+# Verification has been lifted
+which qwen
+# It should display "qwen not found"
+
+# Reinstall the global version if necessary
+npm install -g @qwen-code/qwen-code
+
+# Verification Recovery
+which qwen
+qwen --version
+```

package/docs/developers/tools/shell.md

@@ -0,0 +1,259 @@
+# Shell Tool (`run_shell_command`)
+
+This document describes the `run_shell_command` tool for Qwen Code.
+
+## Description
+
+Use `run_shell_command` to interact with the underlying system, run scripts, or perform command-line operations. `run_shell_command` executes a given shell command, including interactive commands that require user input (e.g., `vim`, `git rebase -i`) if the `tools.shell.enableInteractiveShell` setting is set to `true`.
+
+On Windows, commands are executed with `cmd.exe /c`. On other platforms, they are executed with `bash -c`.
+
+### Arguments
+
+`run_shell_command` takes the following arguments:
+
+- `command` (string, required): The exact shell command to execute.
+- `description` (string, optional): A brief description of the command's purpose, which will be shown to the user.
+- `directory` (string, optional): The directory (relative to the project root) in which to execute the command. If not provided, the command runs in the project root.
+- `is_background` (boolean, required): Whether to run the command in background. This parameter is required to ensure explicit decision-making about command execution mode. Set to true for long-running processes like development servers, watchers, or daemons that should continue running without blocking further commands. Set to false for one-time commands that should complete before proceeding.
+
+## How to use `run_shell_command` with Qwen Code
+
+When using `run_shell_command`, the command is executed as a subprocess. You can control whether commands run in background or foreground using the `is_background` parameter, or by explicitly adding `&` to commands. The tool returns detailed information about the execution, including:
+
+### Required Background Parameter
+
+The `is_background` parameter is **required** for all command executions. This design ensures that the LLM (and users) must explicitly decide whether each command should run in the background or foreground, promoting intentional and predictable command execution behavior. By making this parameter mandatory, we avoid unintended fallback to foreground execution, which could block subsequent operations when dealing with long-running processes.
+
+### Background vs Foreground Execution
+
+The tool intelligently handles background and foreground execution based on your explicit choice:
+
+**Use background execution (`is_background: true`) for:**
+
+- Long-running development servers: `npm run start`, `npm run dev`, `yarn dev`
+- Build watchers: `npm run watch`, `webpack --watch`
+- Database servers: `mongod`, `mysql`, `redis-server`
+- Web servers: `python -m http.server`, `php -S localhost:8000`
+- Any command expected to run indefinitely until manually stopped
+
+**Use foreground execution (`is_background: false`) for:**
+
+- One-time commands: `ls`, `cat`, `grep`
+- Build commands: `npm run build`, `make`
+- Installation commands: `npm install`, `pip install`
+- Git operations: `git commit`, `git push`
+- Test runs: `npm test`, `pytest`
+
+### Execution Information
+
+The tool returns detailed information about the execution, including:
+
+- `Command`: The command that was executed.
+- `Directory`: The directory where the command was run.
+- `Stdout`: Output from the standard output stream.
+- `Stderr`: Output from the standard error stream.
+- `Error`: Any error message reported by the subprocess.
+- `Exit Code`: The exit code of the command.
+- `Signal`: The signal number if the command was terminated by a signal.
+- `Background PIDs`: A list of PIDs for any background processes started.
+
+Usage:
+
+```bash
+run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.", is_background=false)
+```
+
+**Note:** The `is_background` parameter is required and must be explicitly specified for every command execution.
+
+## `run_shell_command` examples
+
+List files in the current directory:
+
+```bash
+run_shell_command(command="ls -la", is_background=false)
+```
+
+Run a script in a specific directory:
+
+```bash
+run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script", is_background=false)
+```
+
+Start a background development server (recommended approach):
+
+```bash
+run_shell_command(command="npm run dev", description="Start development server in background", is_background=true)
+```
+
+Start a background server (alternative with explicit &):
+
+```bash
+run_shell_command(command="npm run dev &", description="Start development server in background", is_background=false)
+```
+
+Run a build command in foreground:
+
+```bash
+run_shell_command(command="npm run build", description="Build the project", is_background=false)
+```
+
+Start multiple background services:
+
+```bash
+run_shell_command(command="docker-compose up", description="Start all services", is_background=true)
+```
+
+## Configuration
+
+You can configure the behavior of the `run_shell_command` tool by modifying your `settings.json` file or by using the `/settings` command in the Qwen Code.
+
+### Enabling Interactive Commands
+
+To enable interactive commands, you need to set the `tools.shell.enableInteractiveShell` setting to `true`. This will use `node-pty` for shell command execution, which allows for interactive sessions. If `node-pty` is not available, it will fall back to the `child_process` implementation, which does not support interactive commands.
+
+**Example `settings.json`:**
+
+```json
+{
+  "tools": {
+    "shell": {
+      "enableInteractiveShell": true
+    }
+  }
+}
+```
+
+### Showing Color in Output
+
+To show color in the shell output, you need to set the `tools.shell.showColor` setting to `true`. **Note: This setting only applies when `tools.shell.enableInteractiveShell` is enabled.**
+
+**Example `settings.json`:**
+
+```json
+{
+  "tools": {
+    "shell": {
+      "showColor": true
+    }
+  }
+}
+```
+
+### Setting the Pager
+
+You can set a custom pager for the shell output by setting the `tools.shell.pager` setting. The default pager is `cat`. **Note: This setting only applies when `tools.shell.enableInteractiveShell` is enabled.**
+
+**Example `settings.json`:**
+
+```json
+{
+  "tools": {
+    "shell": {
+      "pager": "less"
+    }
+  }
+}
+```
+
+## Interactive Commands
+
+The `run_shell_command` tool now supports interactive commands by integrating a pseudo-terminal (pty). This allows you to run commands that require real-time user input, such as text editors (`vim`, `nano`), terminal-based UIs (`htop`), and interactive version control operations (`git rebase -i`).
+
+When an interactive command is running, you can send input to it from the Qwen Code. To focus on the interactive shell, press `ctrl+f`. The terminal output, including complex TUIs, will be rendered correctly.
+
+## Important notes
+
+- **Security:** Be cautious when executing commands, especially those constructed from user input, to prevent security vulnerabilities.
+- **Error handling:** Check the `Stderr`, `Error`, and `Exit Code` fields to determine if a command executed successfully.
+- **Background processes:** When `is_background=true` or when a command contains `&`, the tool will return immediately and the process will continue to run in the background. The `Background PIDs` field will contain the process ID of the background process.
+- **Background execution choices:** The `is_background` parameter is required and provides explicit control over execution mode. You can also add `&` to the command for manual background execution, but the `is_background` parameter must still be specified. The parameter provides clearer intent and automatically handles the background execution setup.
+- **Command descriptions:** When using `is_background=true`, the command description will include a `[background]` indicator to clearly show the execution mode.
+
+## Environment Variables
+
+When `run_shell_command` executes a command, it sets the `QWEN_CODE=1` environment variable in the subprocess's environment. This allows scripts or tools to detect if they are being run from within the CLI.
+
+## Command Restrictions
+
+You can restrict the commands that can be executed by the `run_shell_command` tool by using the `tools.core` and `tools.exclude` settings in your configuration file.
+
+- `tools.core`: To restrict `run_shell_command` to a specific set of commands, add entries to the `core` list under the `tools` category in the format `run_shell_command(<command>)`. For example, `"tools": {"core": ["run_shell_command(git)"]}` will only allow `git` commands. Including the generic `run_shell_command` acts as a wildcard, allowing any command not explicitly blocked.
+- `tools.exclude`: To block specific commands, add entries to the `exclude` list under the `tools` category in the format `run_shell_command(<command>)`. For example, `"tools": {"exclude": ["run_shell_command(rm)"]}` will block `rm` commands.
+
+The validation logic is designed to be secure and flexible:
+
+1.  **Command Chaining Disabled**: The tool automatically splits commands chained with `&&`, `||`, or `;` and validates each part separately. If any part of the chain is disallowed, the entire command is blocked.
+2.  **Prefix Matching**: The tool uses prefix matching. For example, if you allow `git`, you can run `git status` or `git log`.
+3.  **Blocklist Precedence**: The `tools.exclude` list is always checked first. If a command matches a blocked prefix, it will be denied, even if it also matches an allowed prefix in `tools.core`.
+
+### Command Restriction Examples
+
+**Allow only specific command prefixes**
+
+To allow only `git` and `npm` commands, and block all others:
+
+```json
+{
+  "tools": {
+    "core": ["run_shell_command(git)", "run_shell_command(npm)"]
+  }
+}
+```
+
+- `git status`: Allowed
+- `npm install`: Allowed
+- `ls -l`: Blocked
+
+**Block specific command prefixes**
+
+To block `rm` and allow all other commands:
+
+```json
+{
+  "tools": {
+    "core": ["run_shell_command"],
+    "exclude": ["run_shell_command(rm)"]
+  }
+}
+```
+
+- `rm -rf /`: Blocked
+- `git status`: Allowed
+- `npm install`: Allowed
+
+**Blocklist takes precedence**
+
+If a command prefix is in both `tools.core` and `tools.exclude`, it will be blocked.
+
+```json
+{
+  "tools": {
+    "core": ["run_shell_command(git)"],
+    "exclude": ["run_shell_command(git push)"]
+  }
+}
+```
+
+- `git push origin main`: Blocked
+- `git status`: Allowed
+
+**Block all shell commands**
+
+To block all shell commands, add the `run_shell_command` wildcard to `tools.exclude`:
+
+```json
+{
+  "tools": {
+    "exclude": ["run_shell_command"]
+  }
+}
+```
+
+- `ls -l`: Blocked
+- `any other command`: Blocked
+
+## Security Note for `excludeTools`
+
+Command-specific restrictions in `excludeTools` for `run_shell_command` are based on simple string matching and can be easily bypassed. This feature is **not a security mechanism** and should not be relied upon to safely execute untrusted code. It is recommended to use `coreTools` to explicitly select commands
+that can be executed.

package/docs/developers/tools/task.md

@@ -0,0 +1,145 @@
+# Task Tool (`task`)
+
+This document describes the `task` tool for Qwen Code.
+
+## Description
+
+Use `task` to launch a specialized subagent to handle complex, multi-step tasks autonomously. The Task tool delegates work to specialized agents that can work independently with access to their own set of tools, allowing for parallel task execution and specialized expertise.
+
+### Arguments
+
+`task` takes the following arguments:
+
+- `description` (string, required): A short (3-5 word) description of the task for user visibility and tracking purposes.
+- `prompt` (string, required): The detailed task prompt for the subagent to execute. Should contain comprehensive instructions for autonomous execution.
+- `subagent_type` (string, required): The type of specialized agent to use for this task. Must match one of the available configured subagents.
+
+## How to use `task` with Qwen Code
+
+The Task tool dynamically loads available subagents from your configuration and delegates tasks to them. Each subagent runs independently and can use its own set of tools, allowing for specialized expertise and parallel execution.
+
+When you use the Task tool, the subagent will:
+
+1. Receive the task prompt with full autonomy
+2. Execute the task using its available tools
+3. Return a final result message
+4. Terminate (subagents are stateless and single-use)
+
+Usage:
+
+```
+task(description="Brief task description", prompt="Detailed task instructions for the subagent", subagent_type="agent_name")
+```
+
+## Available Subagents
+
+The available subagents depend on your configuration. Common subagent types might include:
+
+- **general-purpose**: For complex multi-step tasks requiring various tools
+- **code-reviewer**: For reviewing and analyzing code quality
+- **test-runner**: For running tests and analyzing results
+- **documentation-writer**: For creating and updating documentation
+
+You can view available subagents by using the `/agents` command in Qwen Code.
+
+## Task Tool Features
+
+### Real-time Progress Updates
+
+The Task tool provides live updates showing:
+
+- Subagent execution status
+- Individual tool calls being made by the subagent
+- Tool call results and any errors
+- Overall task progress and completion status
+
+### Parallel Execution
+
+You can launch multiple subagents concurrently by calling the Task tool multiple times in a single message, allowing for parallel task execution and improved efficiency.
+
+### Specialized Expertise
+
+Each subagent can be configured with:
+
+- Specific tool access permissions
+- Specialized system prompts and instructions
+- Custom model configurations
+- Domain-specific knowledge and capabilities
+
+## `task` examples
+
+### Delegating to a general-purpose agent
+
+```
+task(
+  description="Code refactoring",
+  prompt="Please refactor the authentication module in src/auth/ to use modern async/await patterns instead of callbacks. Ensure all tests still pass and update any related documentation.",
+  subagent_type="general-purpose"
+)
+```
+
+### Running parallel tasks
+
+```
+# Launch code review and test execution in parallel
+task(
+  description="Code review",
+  prompt="Review the recent changes in the user management module for code quality, security issues, and best practices compliance.",
+  subagent_type="code-reviewer"
+)
+
+task(
+  description="Run tests",
+  prompt="Execute the full test suite and analyze any failures. Provide a summary of test coverage and recommendations for improvement.",
+  subagent_type="test-runner"
+)
+```
+
+### Documentation generation
+
+```
+task(
+  description="Update docs",
+  prompt="Generate comprehensive API documentation for the newly implemented REST endpoints in the orders module. Include request/response examples and error codes.",
+  subagent_type="documentation-writer"
+)
+```
+
+## When to Use the Task Tool
+
+Use the Task tool when:
+
+1. **Complex multi-step tasks** - Tasks requiring multiple operations that can be handled autonomously
+2. **Specialized expertise** - Tasks that benefit from domain-specific knowledge or tools
+3. **Parallel execution** - When you have multiple independent tasks that can run simultaneously
+4. **Delegation needs** - When you want to hand off a complete task rather than micromanaging steps
+5. **Resource-intensive operations** - Tasks that might take significant time or computational resources
+
+## When NOT to Use the Task Tool
+
+Don't use the Task tool for:
+
+- **Simple, single-step operations** - Use direct tools like Read, Edit, etc.
+- **Interactive tasks** - Tasks requiring back-and-forth communication
+- **Specific file reads** - Use Read tool directly for better performance
+- **Simple searches** - Use Grep or Glob tools directly
+
+## Important Notes
+
+- **Stateless execution**: Each subagent invocation is independent with no memory of previous executions
+- **Single communication**: Subagents provide one final result message - no ongoing communication
+- **Comprehensive prompts**: Your prompt should contain all necessary context and instructions for autonomous execution
+- **Tool access**: Subagents only have access to tools configured in their specific configuration
+- **Parallel capability**: Multiple subagents can run simultaneously for improved efficiency
+- **Configuration dependent**: Available subagent types depend on your system configuration
+
+## Configuration
+
+Subagents are configured through Qwen Code's agent configuration system. Use the `/agents` command to:
+
+- View available subagents
+- Create new subagent configurations
+- Modify existing subagent settings
+- Set tool permissions and capabilities
+
+For more information on configuring subagents, refer to the subagents documentation.

package/docs/developers/tools/todo-write.md

@@ -0,0 +1,63 @@
+# Todo Write Tool (`todo_write`)
+
+This document describes the `todo_write` tool for Qwen Code.
+
+## Description
+
+Use `todo_write` to create and manage a structured task list for your current coding session. This tool helps the AI assistant track progress and organize complex tasks, providing you with visibility into what work is being performed.
+
+### Arguments
+
+`todo_write` takes one argument:
+
+- `todos` (array, required): An array of todo items, where each item contains:
+  - `content` (string, required): The description of the task.
+  - `status` (string, required): The current status (`pending`, `in_progress`, or `completed`).
+  - `activeForm` (string, required): The present continuous form describing what is being done (e.g., "Running tests", "Building the project").
+
+## How to use `todo_write` with Qwen Code
+
+The AI assistant will automatically use this tool when working on complex, multi-step tasks. You don't need to explicitly request it, but you can ask the assistant to create a todo list if you want to see the planned approach for your request.
+
+The tool stores todo lists in your home directory (`~/.qwen/todos/`) with session-specific files, so each coding session maintains its own task list.
+
+## When the AI uses this tool
+
+The assistant uses `todo_write` for:
+
+- Complex tasks requiring multiple steps
+- Feature implementations with several components
+- Refactoring operations across multiple files
+- Any work involving 3 or more distinct actions
+
+The assistant will not use this tool for simple, single-step tasks or purely informational requests.
+
+### `todo_write` examples
+
+Creating a feature implementation plan:
+
+```
+todo_write(todos=[
+  {
+    "content": "Create user preferences model",
+    "status": "pending",
+    "activeForm": "Creating user preferences model"
+  },
+  {
+    "content": "Add API endpoints for preferences",
+    "status": "pending",
+    "activeForm": "Adding API endpoints for preferences"
+  },
+  {
+    "content": "Implement frontend components",
+    "status": "pending",
+    "activeForm": "Implementing frontend components"
+  }
+])
+```
+
+## Important notes
+
+- **Automatic usage:** The AI assistant manages todo lists automatically during complex tasks.
+- **Progress visibility:** You'll see todo lists updated in real-time as work progresses.
+- **Session isolation:** Each coding session has its own todo list that doesn't interfere with others.