@mmmbuto/qwen-code-termux 0.14.1-termux → 0.15.5-termux

package/bundled/qc-helper/docs/features/mcp.md

@@ -153,6 +153,84 @@ qwen mcp add --transport sse sseServer http://localhost:8080/sse --timeout 30000
 
 - **Server trust** (`trust: true`): bypasses confirmation prompts for that server (use sparingly).
 
+### OAuth authentication
+
+Qwen Code supports OAuth 2.0 authentication for MCP servers. This is useful when accessing remote servers that require authentication.
+
+#### Basic usage
+
+When you add an MCP server with OAuth credentials, Qwen Code will automatically handle the authentication flow:
+
+```bash
+qwen mcp add --transport sse oauth-server https://api.example.com/sse/ \
+  --oauth-client-id your-client-id \
+  --oauth-redirect-uri https://your-server.com/oauth/callback \
+  --oauth-authorization-url https://provider.example.com/authorize \
+  --oauth-token-url https://provider.example.com/token
+```
+
+#### Important: Redirect URI configuration
+
+The OAuth flow requires a redirect URI where the authorization provider sends the authentication code.
+
+- **Local development**: By default, Qwen Code uses `http://localhost:7777/oauth/callback`. This works when running Qwen Code on your local machine with a local browser.
+
+- **Remote/cloud deployments**: When running Qwen Code on remote servers, cloud IDEs, or web terminals, the default `localhost` redirect will NOT work. You MUST configure `--oauth-redirect-uri` to point to a publicly accessible URL that can receive the OAuth callback.
+
+Example for remote servers:
+
+```bash
+qwen mcp add --transport sse remote-server https://api.example.com/sse/ \
+  --oauth-redirect-uri https://your-remote-server.example.com/oauth/callback
+```
+
+#### Manual configuration via settings.json
+
+You can also configure OAuth by editing `settings.json` directly:
+
+```json
+{
+  "mcpServers": {
+    "oauthServer": {
+      "url": "https://api.example.com/sse/",
+      "oauth": {
+        "enabled": true,
+        "clientId": "your-client-id",
+        "clientSecret": "your-client-secret",
+        "authorizationUrl": "https://provider.example.com/authorize",
+        "tokenUrl": "https://provider.example.com/token",
+        "redirectUri": "https://your-server.com/oauth/callback",
+        "scopes": ["read", "write"]
+      }
+    }
+  }
+}
+```
+
+OAuth configuration properties:
+
+| Property           | Description                                                                                                           |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `enabled`          | Enable OAuth for this server (boolean)                                                                                |
+| `clientId`         | OAuth client identifier (string, optional with dynamic registration)                                                  |
+| `clientSecret`     | OAuth client secret (string, optional for public clients)                                                             |
+| `authorizationUrl` | OAuth authorization endpoint (string, auto-discovered if omitted)                                                     |
+| `tokenUrl`         | OAuth token endpoint (string, auto-discovered if omitted)                                                             |
+| `scopes`           | Required OAuth scopes (array of strings)                                                                              |
+| `redirectUri`      | Custom redirect URI (string). **Critical for remote deployments**. Defaults to `http://localhost:7777/oauth/callback` |
+| `tokenParamName`   | Query parameter name for tokens in SSE URLs (string)                                                                  |
+| `audiences`        | Audiences the token is valid for (array of strings)                                                                   |
+
+#### Token management
+
+OAuth tokens are automatically:
+
+- **Stored securely** in `~/.qwen/mcp-oauth-tokens.json`
+- **Refreshed** when expired (if refresh tokens are available)
+- **Validated** before each connection attempt
+
+Use the `/mcp auth` command within Qwen Code to manage OAuth authentication interactively.
+
 ### Tool filtering (allow/deny tools per server)
 
 Use `includeTools` / `excludeTools` to restrict tools exposed by a server (from Qwen Code’s perspective).
@@ -259,20 +337,28 @@ You can always configure MCP servers by manually editing `settings.json`, but th
 qwen mcp add [options] <name> <commandOrUrl> [args...]
 ```
 
-| Argument/Option     | Description                                                         | Default            | Example                                   |
-| ------------------- | ------------------------------------------------------------------- | ------------------ | ----------------------------------------- |
-| `<name>`            | A unique name for the server.                                       | —                  | `example-server`                          |
-| `<commandOrUrl>`    | The command to execute (for `stdio`) or the URL (for `http`/`sse`). | —                  | `/usr/bin/python` or `http://localhost:8` |
-| `[args...]`         | Optional arguments for a `stdio` command.                           | —                  | `--port 5000`                             |
-| `-s`, `--scope`     | Configuration scope (user or project).                              | `project`          | `-s user`                                 |
-| `-t`, `--transport` | Transport type (`stdio`, `sse`, `http`).                            | `stdio`            | `-t sse`                                  |
-| `-e`, `--env`       | Set environment variables.                                          | —                  | `-e KEY=value`                            |
-| `-H`, `--header`    | Set HTTP headers for SSE and HTTP transports.                       | —                  | `-H "X-Api-Key: abc123"`                  |
-| `--timeout`         | Set connection timeout in milliseconds.                             | —                  | `--timeout 30000`                         |
-| `--trust`           | Trust the server (bypass all tool call confirmation prompts).       | — (`false`)        | `--trust`                                 |
-| `--description`     | Set the description for the server.                                 | —                  | `--description "Local tools"`             |
-| `--include-tools`   | A comma-separated list of tools to include.                         | all tools included | `--include-tools mytool,othertool`        |
-| `--exclude-tools`   | A comma-separated list of tools to exclude.                         | none               | `--exclude-tools mytool`                  |
+| Argument/Option             | Description                                                         | Default                                | Example                                                            |
+| --------------------------- | ------------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------ |
+| `<name>`                    | A unique name for the server.                                       | —                                      | `example-server`                                                   |
+| `<commandOrUrl>`            | The command to execute (for `stdio`) or the URL (for `http`/`sse`). | —                                      | `/usr/bin/python` or `http://localhost:8`                          |
+| `[args...]`                 | Optional arguments for a `stdio` command.                           | —                                      | `--port 5000`                                                      |
+| `-s`, `--scope`             | Configuration scope (user or project).                              | `project`                              | `-s user`                                                          |
+| `-t`, `--transport`         | Transport type (`stdio`, `sse`, `http`).                            | `stdio`                                | `-t sse`                                                           |
+| `-e`, `--env`               | Set environment variables.                                          | —                                      | `-e KEY=value`                                                     |
+| `-H`, `--header`            | Set HTTP headers for SSE and HTTP transports.                       | —                                      | `-H "X-Api-Key: abc123"`                                           |
+| `--timeout`                 | Set connection timeout in milliseconds.                             | —                                      | `--timeout 30000`                                                  |
+| `--trust`                   | Trust the server (bypass all tool call confirmation prompts).       | — (`false`)                            | `--trust`                                                          |
+| `--description`             | Set the description for the server.                                 | —                                      | `--description "Local tools"`                                      |
+| `--include-tools`           | A comma-separated list of tools to include.                         | all tools included                     | `--include-tools mytool,othertool`                                 |
+| `--exclude-tools`           | A comma-separated list of tools to exclude.                         | none                                   | `--exclude-tools mytool`                                           |
+| `--oauth-client-id`         | OAuth client ID for MCP server authentication.                      | —                                      | `--oauth-client-id your-client-id`                                 |
+| `--oauth-client-secret`     | OAuth client secret for MCP server authentication.                  | —                                      | `--oauth-client-secret your-client-secret`                         |
+| `--oauth-redirect-uri`      | OAuth redirect URI for authentication callback.                     | `http://localhost:7777/oauth/callback` | `--oauth-redirect-uri https://your-server.com/oauth/callback`      |
+| `--oauth-authorization-url` | OAuth authorization URL.                                            | —                                      | `--oauth-authorization-url https://provider.example.com/authorize` |
+| `--oauth-token-url`         | OAuth token URL.                                                    | —                                      | `--oauth-token-url https://provider.example.com/token`             |
+| `--oauth-scopes`            | OAuth scopes (comma-separated).                                     | —                                      | `--oauth-scopes scope1,scope2`                                     |
+
+> `--oauth-*` flags apply only to `--transport sse` and `--transport http`. Combining them with `--transport stdio` is rejected.
 
 #### Removing a server (`qwen mcp remove`)
 

package/bundled/qc-helper/docs/features/memory.md

@@ -0,0 +1,168 @@
+# Memory
+
+Every Qwen Code session starts with a fresh context window. Two mechanisms carry knowledge across sessions so you don't have to re-explain yourself every time:
+
+- **QWEN.md** — instructions _you_ write once and Qwen reads every session
+- **Auto-memory** — notes Qwen writes itself based on what it learns from you
+
+---
+
+## QWEN.md: your instructions to Qwen
+
+QWEN.md is a plain text file where you write things Qwen should always know about your project or your preferences. Think of it as a permanent briefing that loads at the start of every conversation.
+
+### What to put in QWEN.md
+
+Add things you'd otherwise have to repeat every session:
+
+- Build and test commands (`npm run test`, `make build`)
+- Coding conventions your team follows ("all new files must have JSDoc comments")
+- Architectural decisions ("we use the repository pattern, never call the database directly from controllers")
+- Personal preferences ("always use pnpm, not npm")
+
+Don't include things Qwen can figure out by reading your code. QWEN.md works best when it's short and specific — the longer it gets, the less reliably Qwen follows it.
+
+### Where to create QWEN.md
+
+| File                          | Who it applies to                             |
+| ----------------------------- | --------------------------------------------- |
+| `~/.qwen/QWEN.md`             | You, across all your projects                 |
+| `QWEN.md` in the project root | Your whole team (commit it to source control) |
+
+You can have both. Qwen loads all QWEN.md files it finds when you start a session — your personal one plus any in the project.
+
+If your repository already has an `AGENTS.md` file for other AI tools, Qwen reads that too. No need to duplicate instructions.
+
+### Generate one automatically with `/init`
+
+Run `/init` and Qwen will analyze your codebase to create a starter QWEN.md with build commands, test instructions, and conventions it finds. If one already exists, it suggests additions instead of overwriting.
+
+### Reference other files
+
+You can point QWEN.md at other files so Qwen reads them too:
+
+```markdown
+See @README.md for project overview.
+
+# Conventions
+
+- Git workflow: @docs/git-workflow.md
+```
+
+Use `@path/to/file` anywhere in QWEN.md. Relative paths resolve from the QWEN.md file itself.
+
+---
+
+## Auto-memory: what Qwen learns about you
+
+Auto-memory runs in the background. After each of your conversations, Qwen quietly saves useful things it learned — your preferences, feedback you gave, project context — so it can use them in future sessions without you repeating yourself.
+
+This is different from QWEN.md: you don't write it, Qwen does.
+
+### What Qwen saves
+
+Qwen looks for four kinds of things worth remembering:
+
+| What                    | Examples                                                 |
+| ----------------------- | -------------------------------------------------------- |
+| **About you**           | Your role, background, how you like to work              |
+| **Your feedback**       | Corrections you made, approaches you confirmed           |
+| **Project context**     | Ongoing work, decisions, goals not obvious from the code |
+| **External references** | Dashboards, ticket trackers, docs links you mentioned    |
+
+Qwen doesn't save everything — only things that would actually be useful next time.
+
+### Where it's stored
+
+Auto-memory files live at `~/.qwen/projects/<project>/memory/`. All branches and worktrees of the same repository share the same memory folder, so what Qwen learns in one branch is available in others.
+
+Everything saved is plain markdown — you can open, edit, or delete any file at any time.
+
+### Periodic cleanup
+
+Qwen periodically goes through its saved memories to remove duplicates and clean up outdated entries. This runs automatically in the background once a day after enough sessions have accumulated. You can trigger it manually with `/dream` if you want it to run now.
+
+While cleanup is running, **✦ dreaming** appears in the corner of the screen. Your session continues normally.
+
+### Turning it on or off
+
+Auto-memory is on by default. To toggle it, open `/memory` and use the switches at the top. You can turn off just the automatic saving, just the periodic cleanup, or both.
+
+You can also set them in `~/.qwen/settings.json` (applies to all projects) or `.qwen/settings.json` (this project only):
+
+```json
+{
+  "memory": {
+    "enableManagedAutoMemory": true,
+    "enableManagedAutoDream": true
+  }
+}
+```
+
+---
+
+## Commands
+
+### `/memory`
+
+Opens the Memory panel. From here you can:
+
+- Turn auto-memory saving on or off
+- Turn periodic cleanup (dream) on or off
+- Open your personal QWEN.md (`~/.qwen/QWEN.md`)
+- Open the project QWEN.md
+- Browse the auto-memory folder
+
+### `/init`
+
+Generates a starter QWEN.md for your project. Qwen reads your codebase and fills in build commands, test instructions, and conventions it discovers.
+
+### `/remember <text>`
+
+Immediately saves something to auto-memory without waiting for Qwen to pick it up automatically:
+
+```
+/remember always use snake_case for Python variable names
+/remember the staging environment is at staging.example.com
+```
+
+### `/forget <text>`
+
+Removes auto-memory entries that match your description:
+
+```
+/forget old workaround for the login bug
+```
+
+### `/dream`
+
+Runs the memory cleanup now instead of waiting for the automatic schedule:
+
+```
+/dream
+```
+
+---
+
+## Troubleshooting
+
+### Qwen isn't following my QWEN.md
+
+Open `/memory` to see which files are loaded. If your file isn't listed, Qwen can't see it — make sure it's in the project root or `~/.qwen/`.
+
+Instructions work better when they're specific:
+
+- ✓ `Use 2-space indentation for TypeScript files`
+- ✗ `Format code nicely`
+
+If you have multiple QWEN.md files with conflicting instructions, Qwen may behave inconsistently. Review them and remove any contradictions.
+
+### I want to see what Qwen has saved
+
+Run `/memory` and select **Open auto-memory folder**. All saved memories are readable markdown files you can browse, edit, or delete.
+
+### Qwen keeps forgetting things
+
+If auto-memory is on but Qwen doesn't seem to remember things across sessions, try running `/dream` to force a cleanup pass. Also check `/memory` to confirm both toggles are enabled.
+
+For things you always want Qwen to remember, add them to QWEN.md instead — auto-memory is best-effort, QWEN.md is guaranteed.

package/bundled/qc-helper/docs/features/sandbox.md

@@ -103,8 +103,16 @@ qwen -p "run the test suite"
 
 - **CLI flag**: `--sandbox-image <image>`
 - **Environment variable**: `QWEN_SANDBOX_IMAGE=<image>`
+- **Settings file**: `tools.sandboxImage` in your `settings.json` (e.g., `{"tools": {"sandboxImage": "ghcr.io/qwenlm/qwen-code:0.14.1"}}`)
 
-If you don’t set either, Qwen Code uses the default image configured in the CLI package (for example `ghcr.io/qwenlm/qwen-code:<version>`).
+Priority order (highest to lowest):
+
+1. `--sandbox-image`
+2. `QWEN_SANDBOX_IMAGE`
+3. `tools.sandboxImage`
+4. Built-in default image from the CLI package (for example `ghcr.io/qwenlm/qwen-code:<version>`)
+
+`settings.env.QWEN_SANDBOX_IMAGE` also works as a generic env injection mechanism, but `tools.sandboxImage` is the preferred persistent setting.
 
 ### macOS Seatbelt profiles
 

package/bundled/qc-helper/docs/features/status-line.md

@@ -0,0 +1,261 @@
+# Status Line
+
+> Display custom information in the footer using a shell command.
+
+The status line lets you run a shell command whose output is displayed in the footer's left section. The command receives structured JSON context via stdin, so it can show session-aware information like the current model, token usage, git branch, or anything else you can script.
+
+```
+Single-line status (default approval mode — 1 row):
+┌─────────────────────────────────────────────────────────────────┐
+│  user@host ~/project (main) ctx:34%   🔒 docker | Debug | 67%  │  ← status line
+└─────────────────────────────────────────────────────────────────┘
+
+Multi-line status (up to 2 lines — 2 rows):
+┌─────────────────────────────────────────────────────────────────┐
+│  user@host ~/project (main) ctx:34%   🔒 docker | Debug | 67%  │  ← status line 1
+│  ████████░░░░░░░░░░ 34% context                                │  ← status line 2
+└─────────────────────────────────────────────────────────────────┘
+
+Multi-line status + non-default mode (3 rows max):
+┌─────────────────────────────────────────────────────────────────┐
+│  user@host ~/project (main) ctx:34%   🔒 docker | Debug | 67%  │  ← status line 1
+│  ████████░░░░░░░░░░ 34% context                                │  ← status line 2
+│  auto-accept edits (shift + tab to cycle)                       │  ← mode indicator
+└─────────────────────────────────────────────────────────────────┘
+```
+
+When configured, the status line replaces the default "? for shortcuts" hint. High-priority messages (Ctrl+C/D exit prompts, Esc, vim INSERT mode) temporarily override the status line. The status line text is truncated to fit within the available width.
+
+## Prerequisites
+
+- [`jq`](https://jqlang.github.io/jq/) is recommended for parsing the JSON input (install via `brew install jq`, `apt install jq`, etc.)
+- Simple commands that don't need JSON data (e.g. `git branch --show-current`) work without `jq`
+
+## Quick setup
+
+The easiest way to configure a status line is the `/statusline` command. It launches a setup agent that reads your shell PS1 configuration and generates a matching status line:
+
+```
+/statusline
+```
+
+You can also give it specific instructions:
+
+```
+/statusline show model name and context usage percentage
+```
+
+## Manual configuration
+
+Add a `statusLine` object under the `ui` key in `~/.qwen/settings.json`:
+
+```json
+{
+  "ui": {
+    "statusLine": {
+      "type": "command",
+      "command": "input=$(cat); model=$(echo \"$input\" | jq -r '.model.display_name'); pct=$(echo \"$input\" | jq -r '.context_window.used_percentage'); echo \"$model  ctx:${pct}%\""
+    }
+  }
+}
+```
+
+| Field             | Type        | Required | Description                                                                                                                       |
+| ----------------- | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `type`            | `"command"` | Yes      | Must be `"command"`                                                                                                               |
+| `command`         | string      | Yes      | Shell command to execute. Receives JSON via stdin, stdout is displayed (up to 2 lines).                                           |
+| `refreshInterval` | number      | No       | Re-run the command every N seconds (minimum 1). Useful for data that changes without an Agent state event (clock, quota, uptime). |
+
+## JSON input
+
+The command receives a JSON object via stdin with the following fields:
+
+```json
+{
+  "session_id": "abc-123",
+  "version": "0.14.1",
+  "model": {
+    "display_name": "qwen-3-235b"
+  },
+  "context_window": {
+    "context_window_size": 131072,
+    "used_percentage": 34.3,
+    "remaining_percentage": 65.7,
+    "current_usage": 45000,
+    "total_input_tokens": 30000,
+    "total_output_tokens": 5000
+  },
+  "workspace": {
+    "current_dir": "/home/user/project"
+  },
+  "git": {
+    "branch": "main"
+  },
+  "metrics": {
+    "models": {
+      "qwen-3-235b": {
+        "api": {
+          "total_requests": 10,
+          "total_errors": 0,
+          "total_latency_ms": 5000
+        },
+        "tokens": {
+          "prompt": 30000,
+          "completion": 5000,
+          "total": 35000,
+          "cached": 10000,
+          "thoughts": 2000
+        }
+      }
+    },
+    "files": {
+      "total_lines_added": 120,
+      "total_lines_removed": 30
+    }
+  },
+  "vim": {
+    "mode": "INSERT"
+  }
+}
+```
+
+| Field                                 | Type             | Description                                                                        |
+| ------------------------------------- | ---------------- | ---------------------------------------------------------------------------------- |
+| `session_id`                          | string           | Unique session identifier                                                          |
+| `version`                             | string           | Qwen Code version                                                                  |
+| `model.display_name`                  | string           | Current model name                                                                 |
+| `context_window.context_window_size`  | number           | Total context window size in tokens                                                |
+| `context_window.used_percentage`      | number           | Context window usage as percentage (0–100)                                         |
+| `context_window.remaining_percentage` | number           | Context window remaining as percentage (0–100)                                     |
+| `context_window.current_usage`        | number           | Token count from the last API call (current context size)                          |
+| `context_window.total_input_tokens`   | number           | Total input tokens consumed this session                                           |
+| `context_window.total_output_tokens`  | number           | Total output tokens consumed this session                                          |
+| `workspace.current_dir`               | string           | Current working directory                                                          |
+| `git`                                 | object \| absent | Present only inside a git repository.                                              |
+| `git.branch`                          | string           | Current branch name                                                                |
+| `metrics.models.<id>.api`             | object           | Per-model API stats: `total_requests`, `total_errors`, `total_latency_ms`          |
+| `metrics.models.<id>.tokens`          | object           | Per-model token usage: `prompt`, `completion`, `total`, `cached`, `thoughts`       |
+| `metrics.files`                       | object           | File change stats: `total_lines_added`, `total_lines_removed`                      |
+| `vim`                                 | object \| absent | Present only when vim mode is enabled. Contains `mode` (`"INSERT"` or `"NORMAL"`). |
+
+> **Important:** stdin can only be read once. Always store it in a variable first: `input=$(cat)`.
+
+## Examples
+
+### Model and token usage
+
+```json
+{
+  "ui": {
+    "statusLine": {
+      "type": "command",
+      "command": "input=$(cat); model=$(echo \"$input\" | jq -r '.model.display_name'); pct=$(echo \"$input\" | jq -r '.context_window.used_percentage'); echo \"$model  ctx:${pct}%\""
+    }
+  }
+}
+```
+
+Output: `qwen-3-235b  ctx:34%`
+
+### Git branch + directory
+
+```json
+{
+  "ui": {
+    "statusLine": {
+      "type": "command",
+      "command": "input=$(cat); branch=$(echo \"$input\" | jq -r '.git.branch // empty'); dir=$(basename \"$(echo \"$input\" | jq -r '.workspace.current_dir')\"); echo \"$dir${branch:+ ($branch)}\""
+    }
+  }
+}
+```
+
+Output: `my-project (main)`
+
+> Note: The `git.branch` field is provided directly in the JSON input — no need to shell out to `git`.
+
+### File change stats
+
+```json
+{
+  "ui": {
+    "statusLine": {
+      "type": "command",
+      "command": "input=$(cat); added=$(echo \"$input\" | jq -r '.metrics.files.total_lines_added'); removed=$(echo \"$input\" | jq -r '.metrics.files.total_lines_removed'); echo \"+$added/-$removed lines\""
+    }
+  }
+}
+```
+
+Output: `+120/-30 lines`
+
+### Live clock and git branch
+
+Use `refreshInterval` when the statusline shows data that changes without an Agent event (e.g. the clock, uptime, or rate-limit counters):
+
+```json
+{
+  "ui": {
+    "statusLine": {
+      "type": "command",
+      "command": "input=$(cat); branch=$(echo \"$input\" | jq -r '.git.branch // \"no-git\"'); echo \"$(date +%H:%M:%S)  ($branch)\"",
+      "refreshInterval": 1
+    }
+  }
+}
+```
+
+Output (refreshed every second): `14:32:07  (main)`
+
+### Script file for complex commands
+
+For longer commands, save a script file at `~/.qwen/statusline-command.sh`:
+
+```bash
+#!/bin/bash
+input=$(cat)
+model=$(echo "$input" | jq -r '.model.display_name')
+pct=$(echo "$input" | jq -r '.context_window.used_percentage')
+branch=$(echo "$input" | jq -r '.git.branch // empty')
+added=$(echo "$input" | jq -r '.metrics.files.total_lines_added')
+removed=$(echo "$input" | jq -r '.metrics.files.total_lines_removed')
+
+parts=()
+[ -n "$model" ] && parts+=("$model")
+[ -n "$branch" ] && parts+=("($branch)")
+[ "$pct" != "0" ] 2>/dev/null && parts+=("ctx:${pct}%")
+([ "$added" -gt 0 ] || [ "$removed" -gt 0 ]) 2>/dev/null && parts+=("+${added}/-${removed}")
+
+echo "${parts[*]}"
+```
+
+Then reference it in settings:
+
+```json
+{
+  "ui": {
+    "statusLine": {
+      "type": "command",
+      "command": "bash ~/.qwen/statusline-command.sh"
+    }
+  }
+}
+```
+
+## Behavior
+
+- **Update triggers**: The status line updates when the model changes, a new message is sent (token count changes), vim mode is toggled, git branch changes, tool calls complete, or file changes occur. Updates are debounced (300ms). Set `refreshInterval` (seconds) to additionally re-run the command on a timer — useful for data that changes without an Agent event (clock, rate limits, build status).
+- **Timeout**: Commands that take longer than 5 seconds are killed. The status line clears on failure.
+- **Output**: Multi-line output is supported (up to 2 lines; extra lines are discarded). Each line is rendered as a separate row with dimmed colors in the footer's left section. Lines that exceed the available width are truncated.
+- **Hot reload**: Changes to `ui.statusLine` in settings take effect immediately — no restart required.
+- **Shell**: Commands run via `/bin/sh` on macOS/Linux. On Windows, `cmd.exe` is used by default — wrap POSIX commands with `bash -c "..."` or point to a bash script (e.g. `bash ~/.qwen/statusline-command.sh`).
+- **Removal**: Delete the `ui.statusLine` key from settings to disable. The "? for shortcuts" hint returns.
+
+## Troubleshooting
+
+| Problem                 | Cause                  | Fix                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ----------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Status line not showing | Config at wrong path   | Must be under `ui.statusLine`, not root-level `statusLine`                                                                                                                                                                                                                                                                                                                                             |
+| Empty output            | Command fails silently | Test manually: `echo '{"session_id":"test","version":"0.14.1","model":{"display_name":"test"},"context_window":{"context_window_size":0,"used_percentage":0,"remaining_percentage":100,"current_usage":0,"total_input_tokens":0,"total_output_tokens":0},"workspace":{"current_dir":"/tmp"},"metrics":{"models":{},"files":{"total_lines_added":0,"total_lines_removed":0}}}' \| sh -c 'your_command'` |
+| Stale data              | No trigger fired       | Send a message or switch models to trigger an update — or set `refreshInterval` to re-run the command on a timer                                                                                                                                                                                                                                                                                       |
+| Command too slow        | Complex script         | Optimize the script or move heavy work to a background cache                                                                                                                                                                                                                                                                                                                                           |