diff --git a/docs/users/configuration/themes.md b/docs/users/configuration/themes.md index e74cfe0279..093634c923 100644 --- a/docs/users/configuration/themes.md +++ b/docs/users/configuration/themes.md @@ -36,6 +36,45 @@ Selected themes are saved in Qwen Code's [configuration](../configuration/settin --- +## Auto Theme Detection + +When the theme is set to `"auto"` (or left unset), Qwen Code automatically detects whether your terminal uses a dark or light background and selects the matching Qwen theme (`Qwen Dark` or `Qwen Light`). + +### How to enable + +Set the theme to `"auto"` in `settings.json`: + +```json +{ + "ui": { + "theme": "auto" + } +} +``` + +Or select **Auto** in the `/theme` dialog. This is the default behavior when no theme is explicitly configured. + +### Detection methods + +Qwen Code uses multiple detection methods in a fallback chain. At startup (async path), the order is: + +| Priority | Method | Platform | How it works | +| -------- | ----------------------- | ---------- | ---------------------------------------------------------------------------------------------------- | +| 1 | `COLORFGBG` | All | Reads the `COLORFGBG` environment variable (set by terminals like iTerm2, rxvt, Konsole) | +| 2 | OSC 11 | All (TTY) | Sends an `ESC]11;?` query to the terminal and parses the background color from the response (~200ms) | +| 3 | macOS system appearance | macOS only | Runs `defaults read -g AppleInterfaceStyle` to check if macOS Dark Mode is active | +| 4 | Default | All | Falls back to dark theme if no method succeeds | + +The first method that returns a result wins. The detected value is cached for the session so subsequent theme resolutions (e.g. reselecting Auto in the `/theme` dialog) stay consistent. + +### When to use Auto + +- **Most users** — Auto works well if your terminal background matches your OS appearance or if your terminal sets `COLORFGBG` / supports OSC 11. +- **tmux / screen users** — OSC 11 may not pass through multiplexers. Detection falls back to `COLORFGBG` or macOS system appearance. If neither is available, the default dark theme is used. Set a specific theme if auto-detection gives the wrong result. +- **SSH sessions** — detection depends on the remote environment. If `COLORFGBG` is not forwarded and the remote terminal doesn't respond to OSC 11, the default dark theme is used. + +--- + ## Custom Color Themes Qwen Code allows you to create your own custom color themes by specifying them in your `settings.json` file. This gives you full control over the color palette used in the CLI. diff --git a/docs/users/features/commands.md b/docs/users/features/commands.md index ed1da80878..f6b8b31f28 100644 --- a/docs/users/features/commands.md +++ b/docs/users/features/commands.md @@ -31,15 +31,16 @@ These commands help you save, restore, and summarize work progress. Commands for adjusting interface appearance and work environment. -| Command | Description | Usage Examples | -| ------------ | ---------------------------------------- | ----------------------------- | -| `/clear` | Clear terminal screen content | `/clear` (shortcut: `Ctrl+L`) | -| `/context` | Show context window usage breakdown | `/context` | -| → `detail` | Show per-item context usage breakdown | `/context detail` | -| `/theme` | Change Qwen Code visual theme | `/theme` | -| `/vim` | Turn input area Vim editing mode on/off | `/vim` | -| `/directory` | Manage multi-directory support workspace | `/dir add ./src,./tests` | -| `/editor` | Open dialog to select supported editor | `/editor` | +| Command | Description | Usage Examples | +| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | +| `/clear` | Clear terminal screen content | `/clear` (shortcut: `Ctrl+L`) | +| `/context` | Show context window usage breakdown | `/context` | +| → `detail` | Show per-item context usage breakdown | `/context detail` | +| `/diff` | Open an interactive diff viewer showing uncommitted changes and per-turn diffs. Use ←/→ to switch between current git diff and individual conversation turns, ↑/↓ to browse files | `/diff` | +| `/theme` | Change Qwen Code visual theme | `/theme` | +| `/vim` | Turn input area Vim editing mode on/off | `/vim` | +| `/directory` | Manage multi-directory support workspace | `/dir add ./src,./tests` | +| `/editor` | Open dialog to select supported editor | `/editor` | ### 1.3 Language Settings @@ -209,7 +210,59 @@ this setting. > `general.showSessionRecap` to `false` to opt out of the auto-trigger > while keeping the manual command available. -### 1.8 Information, Settings, and Help +### 1.8 Diff Viewer (`/diff`) + +The `/diff` command opens an interactive diff viewer showing uncommitted changes and per-turn diffs. Use ←/→ to switch between the current git diff and individual conversation turns, ↑/↓ to browse files, and Enter to view inline diffs. + +**How it works:** + +In interactive mode, `/diff` opens a dialog with a **source picker** along the top: + +- **Current** — working tree vs HEAD (`git diff HEAD`). Shows all uncommitted changes including staged, unstaged, and untracked files. +- **T1, T2, T3, …** — per-turn diffs, one tab per model turn that modified files. Most recent turns appear first. Each tab shows a preview of the original prompt for context. + +The file list displays per-file stats (lines added/removed) with tags for special states (`new`, `deleted`, `untracked`, `binary`, `truncated`, `oversized`). Press Enter on a file to view its inline diff with syntax-highlighted hunks. + +Per-turn diffs require [file checkpointing](./checkpointing) to be enabled (on by default in interactive mode). When file checkpointing is off, only the "Current" source is available. + +**Keyboard shortcuts:** + +| Key | Action | +| --------- | ------------------------------------------- | +| `←` / `→` | Switch between sources (Current / T1 / T2…) | +| `↑` / `↓` | Navigate file list | +| `j` / `k` | Navigate file list (vim-style) | +| Enter | View inline diff for selected file | +| `←` / Esc | Return to file list from inline diff view | +| Esc | Close the dialog | + +**Example:** + +``` +┌ /diff · Turn 3 "refactor the auth middleware" ──── 3 files +45 -12 ┐ +│ │ +│ ◀ Current · T3 · T2 · T1 ▶ │ +│ │ +│ › src/utils/parser.ts +30 -8 │ +│ src/utils/parser.test.ts +12 -2 │ +│ README.md +3 -2 │ +│ │ +│ ←/→ source · ↑/↓ file · Enter view · Esc close │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +**Non-interactive mode:** + +In headless (`--prompt`) or non-interactive contexts, `/diff` prints a plain-text summary of the working tree vs HEAD. Per-turn navigation is not available. + +``` +3 files changed, +45 / -12 + +30 -8 src/utils/parser.ts + +12 -2 src/utils/parser.test.ts + +3 -2 README.md +``` + +### 1.9 Information, Settings, and Help Commands for obtaining information and performing system settings. @@ -225,7 +278,7 @@ Commands for obtaining information and performing system settings. | `/copy` | Copy last output content to clipboard | `/copy` | | `/quit` | Exit Qwen Code immediately | `/quit` or `/exit` | -### 1.9 Common Shortcuts +### 1.10 Common Shortcuts | Shortcut | Function | Note | | ------------------ | ----------------------- | ---------------------- | @@ -235,7 +288,7 @@ Commands for obtaining information and performing system settings. | `Ctrl/cmd+Z` | Undo input | Text editing | | `Ctrl/cmd+Shift+Z` | Redo input | Text editing | -### 1.10 Authentication Commands +### 1.11 Authentication Commands Use `/auth` inside a Qwen Code session to configure authentication. Use `/doctor` to inspect the current authentication and environment status.