Claude Code Windows Terminal Optimize

English | 中文

Complete Windows terminal optimization guide for Claude Code — from installation to production-ready setup.

---

English

What is this?

A complete optimization skill for running Claude Code on Windows. Covers everything from CLI installation to terminal beautification, encoding fixes, hook debugging, and taskbar flash notifications.

Based on real-world experience from a full day of debugging on Windows 10 Chinese edition (2026-06-11). 16 pitfalls documented with solutions.

Who is this for?

• Windows users setting up Claude Code for the first time
• Anyone getting garbled Chinese text in terminal
• Users with broken hooks (bash syntax, PSReadLine errors, variable expansion)
• People who want terminal beautification (Oh My Posh, PSReadLine, icons)
• Users who want taskbar flash notifications when Claude finishes

Quick Install

One-click install via Claude Code:

帮我从 https://github.com/chen1guan/claude-code-windows-optimize 安装 Windows 终端优化

Claude will automatically read the skill and guide you through the setup.

If Claude doesn't auto-execute, say: /cmd-optimize

What's included (6 phases)

Phase	What it does	Key pitfalls solved
1. Install CLI	Node.js + Claude Code via nvm	winget unavailable, old Node.js
2. Terminal beautification	Oh My Posh + Terminal-Icons + PSReadLine + FiraCode font	PSReadLine crashes in hooks
3. Windows Terminal	Portable install + wt command + working directory	MSIX corrupt, wt.cmd fails, wrong cwd
4. Encoding fix	UTF-8 for PowerShell + Python + .bat files	GBK default → Chinese garbled text
5. Hook fixes	bash incompatibility, variable loss, format errors	4 separate hook bugs
6. Taskbar flash	Smart foreground/background flash detection	4 flag iterations to get right

All 16 pitfalls

#	Pitfall	Symptom	Fix
1	Node.js too old	Can't install Claude Code	nvm install 20
2	Windows GBK encoding	Chinese text garbled	chcp 65001 + UTF-8 settings
3	PSReadLine in non-interactive hook	predictive suggestion feature cannot be enabled	UserInteractive check + try/catch
4	bash hooks in PowerShell	&& errors, garbled output	Delete incompatible skill (rename alone is NOT enough)
5	PowerShell variables in JSON	$PID becomes empty, params lost	Use external .ps1 file + -File parameter
6	Hook config format wrong	Hook never fires	Must use {matcher, hooks[]} nested format
7	Edit tool blocked by security	Can't modify .claude/settings.json	Use PowerShell Get-Content / WriteAllText
8	FLASHW_TIMERNOFG no flash in foreground	No response when user is watching	Use GetForegroundWindow() check
9	FLASHW_TIMER never stops	Keeps flashing after user returns	Use FLASHW_TIMERNOFG (auto-stops)
10	GetConsoleWindow() returns null in hook	Can't find terminal window	Search by process name
11	MSIX installer corrupt	Start menu click does nothing	Download portable version
12	wt.cmd wrapper fails	Explorer address bar error	Register via App Paths registry
13	Terminal working directory wrong	Opens at C:\Users\User	Set startingDirectory: null (not "null")
14	.bat file LF line endings	Batch file parsing error	Convert to CRLF
15	Python missing encoding declaration	Editor parses with wrong encoding	Add # -*- coding: utf-8 -*-
16	PPT Chinese text shows boxes	No Chinese font specified	run.font.name = '微软雅黑'

File structure

skills/cmd-optimize/
├── SKILL.md                              # Main skill (6 phases + troubleshooting)
├── references/
│   ├── flash-terminal.ps1                # Taskbar flash script (smart foreground/background)
│   └── Microsoft.PowerShell_profile.ps1  # Complete PowerShell profile (UTF-8 + beautification)
└── .claude-plugin/
    └── plugin.json                       # Metadata

Requirements

• Windows 10/11
• PowerShell 5.1+
• Claude Code CLI
• Node.js >= 18

Supported terminals

Terminal	Support
Windows Terminal	✅ Best experience
cmd.exe	✅
PowerShell window	✅
VS Code integrated terminal	⚠️ Flash targets VS Code window

Related projects

• claude-code-taskbar-flash — Standalone taskbar flash skill (subset of this project)

---

中文

这是什么？

Claude Code 在 Windows 上的完整优化方案。覆盖从安装 CLI、终端美化、乱码修复、Hook 调试到任务栏闪烁通知的全流程。

基于 2026-06-11 在 Windows 10 中文版上一整天的真实调试经验，记录了 16 个踩坑点和对应的解决方案。

适合谁？

• 第一次在 Windows 上配置 Claude Code 的用户
• 终端出现中文乱码的用户
• Hook 报错的用户（bash 语法、PSReadLine 错误、变量展开失败）
• 想美化终端的用户（Oh My Posh、PSReadLine、图标）
• 想要任务栏闪烁提醒的用户

一句话安装

在 Claude Code 中直接说：

帮我从 https://github.com/chen1guan/claude-code-windows-optimize 安装 Windows 终端优化

Claude 会自动读取 skill 并引导你完成配置。

如果 Claude 没有自动执行，补充一句：/cmd-optimize

包含内容（6 个阶段）

阶段	做什么	解决的坑
1. 安装 CLI	通过 nvm 安装 Node.js + Claude Code	winget 不可用、Node.js 版本过低
2. 终端美化	Oh My Posh + Terminal-Icons + PSReadLine + FiraCode 字体	PSReadLine 在 Hook 中崩溃
3. Windows Terminal	便携版安装 + wt 命令 + 工作目录修复	MSIX 损坏、wt.cmd 不工作、目录不对
4. 编码修复	PowerShell + Python + .bat 文件的 UTF-8 设置	Windows 默认 GBK → 中文乱码
5. Hook 修复	bash 不兼容、变量丢失、格式错误	4 个独立的 Hook bug
6. 任务栏闪烁	智能前台/后台闪烁检测	4 次标志迭代才调通

全部 16 个踩坑点

#	坑	现象	解法
1	Node.js 版本过低	Claude Code 无法安装	nvm install 20
2	Windows 默认 GBK 编码	中文错误信息乱码	chcp 65001 + UTF-8 设置
3	PSReadLine 非交互报错	predictive suggestion feature cannot be enabled	UserInteractive 检查 + try/catch
4	bash 语法 Hook 在 PowerShell 中执行	&& 报错、乱码	删除不兼容 skill（仅重命名不够，必须删除）
5	JSON 中嵌入 PowerShell 变量	$PID 变空、参数丢失	改用外部 .ps1 文件 + -File 参数
6	Hook 配置格式错误	Hook 不触发	必须用 {matcher, hooks[]} 嵌套格式
7	Edit 工具被安全策略阻止	无法修改 .claude/settings.json	用 PowerShell Get-Content / WriteAllText
8	FLASHW_TIMERNOFG 前台不闪	用户在看终端时无反应	用 GetForegroundWindow() 判断，前台用 FLASHW_ALL
9	FLASHW_TIMER 永远不停	用户切回来后还在闪	后台用 FLASHW_TIMERNOFG（自动停止）
10	GetConsoleWindow() 在 Hook 中返回空	找不到终端窗口	按进程名搜索
11	MSIX 安装包损坏	开始菜单点击无反应	下载便携版
12	wt.cmd 包装器不工作	资源管理器地址栏报错	通过注册表 App Paths 注册
13	Windows Terminal 工作目录不对	打开后是 C:\Users\User	startingDirectory 设为 null（不是字符串）
14	.bat 文件 LF 换行	批处理解析异常	转换为 CRLF
15	Python 文件缺少编码声明	编辑器/工具用错误编码解析	第一行添加 # -*- coding: utf-8 -*-
16	PPT 中文字符显示方块	未指定中文字体	run.font.name = '微软雅黑'

文件结构

skills/cmd-optimize/
├── SKILL.md                              # 主 skill（6 阶段 + 排查指南）
├── references/
│   ├── flash-terminal.ps1                # 闪烁脚本（智能前台/后台切换）
│   └── Microsoft.PowerShell_profile.ps1  # 完整 Profile（UTF-8 + 美化）
└── .claude-plugin/
    └── plugin.json                       # 元数据

环境要求

• Windows 10/11
• PowerShell 5.1+
• Claude Code CLI
• Node.js >= 18

支持的终端

终端	支持
Windows Terminal	✅ 最佳体验
cmd.exe	✅
PowerShell 窗口	✅
VS Code 集成终端	⚠️ 闪烁目标是 VS Code 窗口

相关项目

• claude-code-taskbar-flash — 独立的任务栏闪烁 skill（本项目的子集）

---

License

MIT