下午三点我正在 Windows 11 上用 Claude Code 重构一个老项目的模块VS Code 占着左半屏Windows Terminal 在右半屏跑 Claude Code。我盯着它生成了几秒钟代码切回编辑器看上下文没过两分钟又忍不住切回终端——它已经跑完一段了正在等我敲 y 确认。就这样来来回回切了一个下午脖子不酸心累。频繁切换窗口这件事在 AI 编程时代被无限放大了因为 Claude Code 这类终端级 Agent 不像图形化 IDE 有醒目的进度条状态全藏在那一屏幕滚动的文本里。这篇文章就是来解决这个问题的在 Windows 11 上给 Claude Code 配一个桌面悬浮球让它把正在干活 / 思考中 / 等审批 / 已经空闲这几个状态用颜色和文字直接挂在屏幕角落你用余光一扫就知道该不该切回去省掉八九成的无效切换。我会把做法拆成几层来讲先分析这个痛点的来源再对比各种方案为什么悬浮球最省事然后是核心的状态感知逻辑怎么做、悬浮球窗口本身怎么实现最后是我实测两周踩过的坑以及一个不写代码也能用的 AHK 简版。内容偏 Windows 11 Claude Code 场景但思路可以平移到任何跑在终端里的 AI 编程工具上。1. Claude Code 的终端工作方式决定了你一定会频繁切窗口1.1 它的交互节奏和 IDE 完全不一样用过 Claude Code 的人应该都有同感它的主战场是终端不是编辑器。你在终端里给一句把这个模块的 API 改成异步并把调用方全部同步改掉它先会输出一段思路分析然后开始创建或修改文件、执行命令、跑测试每一步都会在终端里打出一堆日志和 diff 片段。麻烦的地方在于这个过程中你不会一直盯着终端。正常人的用法是切回编辑器看它改得对不对然后等它跑完给反馈。可问题来了——它什么时候跑完等审批的时候显示的是什么有没有卡在某个错误上终端窗口不会主动知会你任何事于是只能靠手动切回去瞄一眼瞄完再切回来继续写。一个高频的 20 分钟编码过程里面可能有七八次这种无效切窗。很多人在 VS Code 里用 Copilot 或 Cline 时没这个感觉因为它们的状态是嵌在编辑器侧边栏/面板里的你本来就盯着编辑器。Claude Code 是独立于编辑器的终端进程中间隔着一个窗口边界状态就断了。1.2 你需要的不是多开窗口而是状态出口有人会说分屏不就完了左边编辑器右边终端都摆在桌面上不用切。但实际做过开发就知道窗口多了之后Claude Code 的终端经常被其他窗口盖住打几个字、开个文档、看个浏览器它又被压到底下了。Windows 11 的任务视图和 Snap Layouts 能缓解但不能解决我要第一时间知道Agent状态这件事。更本质地说切窗口问题的核心不是窗口数量而是缺少一个状态出口。我们想要的状态提示应该是系统级的、常驻的、不占注意力的。悬浮球就是最典型的形式一个几十像素的小球贴在屏幕右上角绿色代表空闲黄色代表它在思考或跑工具红色代表它在等确认或者报错了。你不需要切窗口余光一扫就知道现在该不该回终端。这里还要说明一下为什么单独为 Claude Code 做悬浮球而不是直接选那种自带状态浮窗的 AI 编程工具。现在的 AI 编程工具大致分两派一派是 IDE 插件Copilot、Cline、Continue状态天然在编辑器里另一派是终端 AgentClaude Code、Gemini CLI 这类跑在终端里、可以用任意编辑器、操作的是整个项目而不仅是当前文件。终端派自由度太高注定了它不会主动给你画一个状态球。所以想省心就得自己在系统层加一点外挂。2. 悬浮球方案对比改终端、加显示器还是系统层擦玻璃2.1 几种常见思路的真实体验我给周边同事推荐过几类方案先说结论它们都能缓解切窗口但性价比差别很大。第一种是编辑器内嵌终端。VS Code 自带终端面板把 Claude Code 跑在里面这样至少切换距离短了。问题是终端面板被压在编辑器下方Agent 执行命令时输出区空间小得一屏放不下几行而且你还是得把注意力从代码区移到下方才能看到状态本质上没解决状态无感知。第二种是双屏。如果你有两个显示器一个放编辑器、一个放终端切窗口压力确实小很多。但双屏对居家办公和笔记本用户不现实而且人眼的注意力不会因为屏幕变了就自动分配很多时候还是会全神贯注地盯编辑器终端那屏成了摆设。第三种是改动 Claude Code 的插件或 Hook让它在任务完成时发系统通知。这个思路很接近正确答案Claude Code 本身也有流程控制脚本和消息解析接口可以拿到它的生命周期状态。但问题是Agent 在一个长任务里可能会连续调用十几次工具完成一次工具调用和整段任务完成是两码事通知反而会变得更吵。悬浮球是状态量不是事件量它不会打断你只看颜色就知道大约进行到哪一步。所以最终我选择第四种在操作系统层做一个常驻悬浮球和 Claude Code 的进程、日志解耦。它不侵入 Claude Code只是被动感知运行状态。这种方案的好处是即使哪天你换了一个终端 Agent悬浮球改一下检测逻辑照样能用。2.2 开发技术选型Python、AutoHotkey 还是 Tauri确定要做悬浮球之后还有一个技术选型问题。我重点对比了几个能在 Windows 11 上实现无边框 透明 置顶窗口的方案方案开发成本依赖体积置顶/透明适合人群AutoHotkey极低极小支持只需要简单状态灯PowerShell WinForms中系统自带支持不想装额外运行时Python tkinter中低需装 Python支持还要解析 JSON 日志Tauri / Electron高大支持想做完整产品我的选择是 Python tkinter。原因很直接悬浮球本身不是难点难的是感知 Claude Code 状态而这个状态藏在它本地会话日志的 JSONL 文件里。Python 处理 JSON、文件监控、进程检测是最顺手的标准库 tkinter 又刚好能画出透明置顶窗口不需要单独引入重量级 GUI 框架。你要是电脑上还没装 Python装一个 3.11 或 3.12 版本即可这一步并不复杂。3. 状态感知悬浮球怎么知道 Claude Code 正在干活3.1 方案一读 Claude Code 的本地会话日志Claude Code 每跑一个项目都会在用户目录下的.claude\projects里留下一堆 JSONL 会话日志。Windows 11 上的完整路径一般是C:\Users\你的用户名\.claude\projects\每个项目目录以项目路径的转义字符串命名目录里的.jsonl文件就是一次会话的记录每一行是一个 JSON 对象记录了时间戳、角色、消息内容、工具调用信息等等。悬浮球要做的核心事情就是找到当前最近被写入的那个 jsonl 文件然后看它的最近写入时间和最后几行内容推断出 Claude Code 当前处于什么状态。判断逻辑我设计了三个状态空闲绿色日志文件超过 35 秒没有新增内容且最后一条不是 assistant 正在输出。思考中/工具执行中黄色日志文件在最近 8 秒内有写入最后一条消息来自 assistant说明它还在持续产出。需要关注红色日志文件最近 8 秒没有写入但 Claude Code 进程还在大概率是在等你审批、或者卡在某条命令上。这个状态要结合进程检测才能更准。下面是读取日志并做基础状态判断的 Python 片段import json import os import time LOG_ROOT os.path.expanduser(~/.claude/projects) def latest_log_file(): 找到最近写入的会话日志文件 files [] for root, dirs, names in os.walk(LOG_ROOT): for name in names: if name.endswith(.jsonl): path os.path.join(root, name) files.append((os.path.getmtime(path), path)) if not files: return None files.sort(reverseTrue) return files[0][1] def eva_status(log_path, work_age8, idle_age35): 根据日志文件的修改时间判断状态 try: mtime os.path.getmtime(log_path) age time.time() - mtime except FileNotFoundError: return 0 if age work_age: # 最近有写入再确认最后一条是否来自 assistant try: with open(log_path, r, encodingutf-8) as f: lines [line for line in f if line.strip()] last json.loads(lines[-1]) if last.get(message, {}).get(role) assistant: return 1 # 思考中 except Exception: pass return 1 if age idle_age: return 1 return 0 # 空闲这段代码骨架看着简单但有两个容易翻车的细节。第一Claude Code 的日志是持续追加的不一定每个事件都立刻刷盘所以状态判断要有时间容忍度不能卡得太死8 秒和 35 秒这两个阈值是我反复试出来的写文档用途时可以直接抄。第二判断是否在思考不能只看文件有没有更新还要看最后一行 JSON 的角色因为有些写入是系统提示或者 tool 结果不代表 assistant 正在生成。3.2 方案二兜底检测进程和窗口标题日志方案已经能覆盖 90% 场景但它有一个盲区如果 Claude Code 正在等待用户审批日志可能不会频繁写入文件年龄会慢慢超过 8 秒状态就从黄色跌回空闲。所以我还加了一个兜底——检测进程是否存活。Claude Code 在 Windows 上多以 Node 进程方式运行进程名可能是node.exe命令行参数里包含claude。用 psutil 可以拿到进程列表并按 cmdline 过滤import psutil def is_claude_running(): for proc in psutil.process_iter([name, cmdline]): try: name (proc.info[name] or ).lower() cmdline .join(proc.info[cmdline] or []).lower() if claude in name or (node.exe in name and claude in cmdline): return True except Exception: continue return False这里要提醒一句不能写成只要看到 node.exe 就算 Claude 在跑否则你本地其他 Node 服务也会触发误报。命令行参数里带claude这个关键词才是最可靠的因为 Claude Code 实际是通过 node 加载 cli.js 启动的。窗口标题兜底也值得一提。Windows Terminal 在多标签场景下每个终端标签的标题会随前台程序变化。如果你用的是 Windows Terminal并且给它配置了动态标题那么在 Claude Code 运行期间终端标签页的标题往往会包含当前运行的命令或目录。可以用系统 API 枚举顶层窗口找到标题里带 claude 或项目名的窗口判断它是否在前台。不过窗口标题方案依赖终端配置通用性不如进程检测我的习惯是把它作为第二兜底。3.3 状态判定的工程取舍我把三个信号按优先级排了一下日志文件状态最准进程检测最稳窗口标题最弱但能辅助判断用户是不是正对着终端。实际轮询周期设在 1 秒一次不费 CPU肉眼看起来状态变化也够跟手。这里有一个不得不接受的现实Claude Code 内部的状态机比如正在思考和正在写文件其实分得很细但从外部通过日志倒推只能得到一个模糊状态。悬浮球是给你瞥一眼用的不是给 CI 系统用的所以模糊判断完全够用。你要是真的需要精确到它在调用哪个工具往下读第 4 章日志里其实有 tool_use 字段可以解析出来显示在悬浮球文字提示里但那属于进阶玩法别为了完美状态机反而把自己绕进去。4. 悬浮球本球用 Python 做一个右上角置顶状态小球4.1 准备运行环境写悬浮球之前先在 Windows 11 上确认三件事Python 已安装、能访问用户目录、tkinter 可用。tkinter 是 Python 默认带的普通安装包就包含不需要额外 pip。要装的第三方包只有 psutil 和 dll 头文件用到的 ctypesctypes 也是标准库所以实际只有一条命令pip install psutil推荐用 3.11 或 3.12。太老的 Python 版本在高 DPI 支持上不如新版悬浮球显示位置会莫名其妙偏半个屏幕。4.2 画一个无边框、置顶、透明背景的球tkinter 的overrideredirect(True)可以去掉标题栏和边框attributes(-topmost, True)让窗口永远置顶attributes(-transparentcolor, color)可以把指定颜色变成全透明。我的做法是设一个几乎不会用的颜色#010203作为窗口背景再把它设为透明色然后在这个透明窗口上画一个圆球。窗口默认位置放在屏幕右上角离边缘留 50 像素左右避免遮挡关闭按钮。import tkinter as tk import ctypes # 让窗口坐标按物理像素计算避免 Windows 11 缩放出问题 try: ctypes.windll.shcore.SetProcessDpiAwareness(1) except Exception: pass class StatusBall: COLORS { 0: #2ecc71, # 空闲绿 1: #f1c40f, # 思考中黄 2: #e74c3c, # 需关注红 } def __init__(self): self.root tk.Tk() self.root.overrideredirect(True) self.root.attributes(-topmost, True) self.root.attributes(-transparentcolor, #010203) self.root.configure(bg#010203) self.canvas tk.Canvas( self.root, width36, height36, bg#010203, highlightthickness0 ) self.canvas.pack() # 初始位置屏幕右上角 screen_w self.root.winfo_screenwidth() self.win_x screen_w - 60 self.win_y 70 self.root.geometry(f36x36{self.win_x}{self.win_y}) self._draw(0) self.root.mainloop() def _draw(self, status): self.canvas.delete(all) # 球体底色加一圈浅色描边 self.canvas.create_oval(2, 2, 34, 34, fillself.COLORS[status], outline#ffffff, width2)透明色窗口注意一个细节transparentcolor设置的透明色是全窗口级别的也就是说只要 canvas 上某个像素颜色等于这个值那几个像素就完全不参与显示和点击。所以球体以外的部分要留成透明这正好省了我做不规则窗口的麻烦。4.3 把状态轮询接进 tkinter 主循环悬浮球的状态不能阻塞 UI 主线程否则球会卡住拖不动。tkinter 里最简单的方式是用after定时器每 1000ms 调一次检查函数更新颜色和悬浮文字。class StatusBall: def __init__(self): # ... 前面的初始化 ... self.current_status 0 self.poll() def poll(self): newest latest_log_file() status eva_status(newest) if newest else 0 if not is_claude_running(): # Claude Code 完全没启动球收起来或显示灰色 status 0 if status ! self.current_status: self.current_status status self._draw(status) self.root.after(1000, self.poll)after的好处是不会在两次更新之间占用 CPU轮询一秒钟一次整体占用可以忽略。我实测同时开着 VS Code、Windows Terminal 和浏览器悬浮球进程内存占用不到 30MBCPU 基本为 0。4.4 拖拽、鼠标穿透、系统托盘这些交互细节悬浮球除了看状态还要允许用户把它拖到别的位置。tkinter 的 Canvas 绑定鼠标事件很简单def _on_press(self, event): self._drag_offset_x event.x self._drag_offset_y event.y def _on_drag(self, event): new_x self.root.winfo_pointerx() - self._drag_offset_x new_y self.root.winfo_pointery() - self._drag_offset_y self.root.geometry(f36x36{new_x}{new_y})还有一个高频需求是鼠标穿透。当悬浮球放在代码编辑区附近、挡住内容的时候你可能希望它不拦截鼠标点击。Windows 对窗口有一个扩展样式WS_EX_TRANSPARENT加上之后该窗口不会再接收鼠标事件相当于变成玻璃上的一张贴纸。配合右键菜单可以在可交互和完全穿透之间切换import ctypes GWL_EXSTYLE -20 WS_EX_LAYERED 0x00080000 WS_EX_TRANSPARENT 0x00000020 def set_click_through(hwnd, enabled): style ctypes.windll.user32.GetWindowLongW(hwnd, GWL_EXSTYLE) if enabled: style | WS_EX_LAYERED | WS_EX_TRANSPARENT else: style ~WS_EX_TRANSPARENT ctypes.windll.user32.SetWindowLongW(hwnd, GWL_EXSTYLE, style)右键菜单我用 tkinter 的Menu直接做菜单项包括打开 Claude Code 项目日志目录、暂停监控、切换鼠标穿透、退出。系统托盘可以做也可以不做。我给悬浮球加了一个最小化到托盘的行为用的库是pystraypip install pystray pillow托盘图标和悬浮球颜色保持同步。这样当你不小心把球关掉之后可以从托盘重新唤出不用再重启脚本。这一步属于锦上添花嫌麻烦可以先不加。4.5 性能与体积整套脚本加起来大概 200 行左右没有外部服务、没有后台任务就是一个纯粹的本地状态显示。它不向任何地方发送数据Claude Code 的会话日志也只是被读取最后几行。这个方案对隐私的侵入性很低比那些需要装 IDE 插件、会上传代码上下文的方案要轻得多。5. 实测两周的体验与踩坑记录5.1 踩坑 1-transparentcolor的透明色把球也变没了第一次画球的时候我把窗口背景色设成白色#ffffff并设为透明色然后 canvas 画球时也想用白色填充高光部分。结果球上凡是有白色的像素全部透明整个球坑坑洼洼。后来才意识到transparentcolor是基于像素值精确匹配的画球时所有色值必须和透明色完全不同。我的解决方法是透明色选#010203球体填充色用标准化色板描边用#ffffff只要不用#010203就不会出问题。5.2 踩坑 2日志文件轮换导致监控失效Claude Code 不是永远往同一个 jsonl 文件里写。新开会话、主动/clear、或者项目切换都会生成新文件。我的第一版监控只用latest_log_file()取一次文件句柄结果一开会话文件变了悬浮球还盯着旧文件状态永远停在绿色。修复方案是每次 poll 都重新扫描目录重新找最新的 jsonl 文件。成本很低但确实容易漏。另外Windows 上日志文件被占用的情况不算多Claude Code 用的是追加写模式Python 以只读方式打开不会撞锁不需要特殊处理。5.3 踩坑 3Windows 11 高 DPI 下的坐标漂移这是最有 Windows 味的一个坑。Windows 11 默认 150% 缩放tkinter 如果不在初始化时设置进程级 DPI 感知窗口坐标和鼠标坐标走的是两套单位拖拽时球会飘——你按住球往右拖它却往右下角窜。解决方式就是在创建 tkinter 窗口之前强制设置 DPI 感知ctypes.windll.shcore.SetProcessDpiAwareness(1)设置之后geometry 的坐标系和winfo_screenwidth()返回的值会保持一致。多显示器环境下最好用虚拟屏幕坐标winfo_screenwidth()拿到的只是主显示器宽度副屏上的默认落点会不准这一点笔记本外接屏幕用户尤其要当心。5.4 踩坑 4鼠标穿透之后拖不回来了开了鼠标穿透后窗口完全不接收鼠标事件自然也没法通过拖拽取消穿透。我一开始没做热键结果球卡在屏幕角落死掉了只能杀掉进程重启。后来加了两个出口一个是右键菜单在穿透模式下仍可用因为WS_EX_TRANSPARENT只影响鼠标点击穿透对右键菜单这种系统交互不一定拦截另一个是全局热键——在穿透模式下按CtrlAltB强制关闭穿透并恢复可拖拽。Windows 上注册全局热键可以用keyboard库也可以直接用RegisterHotKey我更推荐后者少一个 pip 依赖。5.5 实测结论值不值得装用了两周最直接的感受是切终端的次数至少降了一半。以前写一个多文件重构任务每隔几分钟就切回去看一眼进度现在只要余光扫一下右上角黄色说明还在跑绿色说明停了该切回去给指令或者确认结果。悬浮球不是万能的它不能告诉你这次改动改坏了哪一行但它把是否要切窗口这个决策成本降到了最低。另外我把它和 Claude Code 的 session 管理配合起来用红色闪烁时直接单击球体会触发一个脚本把 Windows Terminal 切到前台并激活 Claude Code 的会话窗口。这个比手动从任务栏点要顺手得多算是悬浮球最有增值空间的扩展点。6. 不写代码版用 AutoHotkey 二十行实现简版悬浮灯Python 方案适合愿意维护脚本的人。如果你只是想要一个能用的状态灯不想装 Python 也不想碰 JSONAutoHotkey 可以用二十行脚本解决问题。AHK 的思路简单粗暴每隔几秒检测一次指定窗口或进程是否存在然后修改球的颜色。如果你把 Claude Code 跑在一个固定的 Windows Terminal 标签页里可以检测该标签页的窗口标题是否包含项目名也可以直接检测node.exe进程是否存在但这样误报率会高一些。下面是我实际用过的简版脚本#Persistent #SingleInstance Force ; 初始悬浮球 Gui, New, AlwaysOnTop -Caption ToolWindow Gui, Color, 2EFF2E Gui, Show, x1520 y80 w25 h25, ClaudeStatusBall SetTimer, CheckStatus, 5000 return CheckStatus: ; 检测窗口标题里是否含 claude按你终端标签实际标题改 WinGet, activeWinList, List, claude if (activeWinList 0) Gui, Color, 2EFF2E ; 有相关窗口绿色 else Gui, Color, FF4444 ; 没找着红色 return ^b:: Gui, Cancel ExitApp return这个版本不是真正识别 Claude Code 的运行状态它只是检测有没有相关窗口/进程存活所以更准确的名字是窗口存在性指示灯。好处是零依赖、秒启动、不占内存适合开会时给旁边的人看我现在 AI 正在干活别打断我。AHK 版还能进一步加一点状态感用Gosub配合SetTimer做颜色呼吸效果或者用Gui, LastFoundWinSet, Transparent调整透明度。但核心局限很明显——它读不到日志内容无法区分思考中和等审批。如果你的工作流里 Claude Code 频繁需要审批确认AHK 简版会频繁显示同一种颜色参考价值不大。7. 从悬浮球到完整工作流几个我仍在用的扩展方向文章写到这悬浮球本身的功能就讲完了。额外说几个我还在调试的扩展方向给想折腾的读者当参考。第一个方向是给悬浮球加文本气泡提示。日志里有 tool_use 字段能拿到当前调用的是 Read、Edit 还是 Bash把工具名显示在球旁边。我试过用 tkinter 的Label做动态文字状态切换时闪一下正在 Edit 文件 xxx比单纯颜色更直观。注意别让气泡挡住代码区我把它放在球的下方停留 2 秒自动消失。第二个方向是把状态通过 WebSocket 或 MQTT 推给手机/其他电脑。这样人在客厅、机器在书房跑长任务时手机看一眼就能知道跑完没有。这个方案我还没完全稳定因为要额外起一个本地 WebSocket 服务悬浮球作为客户端连接复杂度比纯本地高一个台阶。第三个方向是让悬浮球反向控制 Claude Code。Claude Code 支持非交互式运行模式可以claude -p ...直接给指令。悬浮球上做一个输入框按快捷键弹出输入内容后直接以非交互模式发给正在运行的会话相当于给你的终端 Agent 加了一个悬浮快捷指令入口。这个玩法还没有成熟但因为 Claude Code 的命令行协议是开放的实现路径已经比较清晰。如果你只需要解决频繁切窗口这一个问题第一版 Python 悬浮球完全够用——它稳定、轻量、逻辑透明代码也不长。我在实际使用中的体会是工具越简单越好修别在第一天就把功能堆满先让球亮起来、转起来再根据自己真正的使用节奏往里加交互。等跑两三周你会发现那些看着酷炫的花活大部分都用不上真正高频的其实就三件事绿色、黄色、红色外加一键切回终端。 
长河君 · 2026/9/18 8:09:11 · 阅读 1.2k 用悬浮球解决Claude Code频繁切窗口烦恼：Windows 11上的AI编程状态感知方案
下午三点我正在 Windows 11 上用 Claude Code 重构一个老项目的模块VS Code 占着左半屏Windows Terminal 在右半屏跑 Claude Code。我盯着它生成了几秒钟代码切回编辑器看上下文没过两分钟又忍不住切回终端——它已经跑完一段了正在等我敲 y 确认。就这样来来回回切了一个下午脖子不酸心累。频繁切换窗口这件事在 AI 编程时代被无限放大了因为 Claude Code 这类终端级 Agent 不像图形化 IDE 有醒目的进度条状态全藏在那一屏幕滚动的文本里。这篇文章就是来解决这个问题的在 Windows 11 上给 Claude Code 配一个桌面悬浮球让它把正在干活 / 思考中 / 等审批 / 已经空闲这几个状态用颜色和文字直接挂在屏幕角落你用余光一扫就知道该不该切回去省掉八九成的无效切换。我会把做法拆成几层来讲先分析这个痛点的来源再对比各种方案为什么悬浮球最省事然后是核心的状态感知逻辑怎么做、悬浮球窗口本身怎么实现最后是我实测两周踩过的坑以及一个不写代码也能用的 AHK 简版。内容偏 Windows 11 Claude Code 场景但思路可以平移到任何跑在终端里的 AI 编程工具上。1. Claude Code 的终端工作方式决定了你一定会频繁切窗口1.1 它的交互节奏和 IDE 完全不一样用过 Claude Code 的人应该都有同感它的主战场是终端不是编辑器。你在终端里给一句把这个模块的 API 改成异步并把调用方全部同步改掉它先会输出一段思路分析然后开始创建或修改文件、执行命令、跑测试每一步都会在终端里打出一堆日志和 diff 片段。麻烦的地方在于这个过程中你不会一直盯着终端。正常人的用法是切回编辑器看它改得对不对然后等它跑完给反馈。可问题来了——它什么时候跑完等审批的时候显示的是什么有没有卡在某个错误上终端窗口不会主动知会你任何事于是只能靠手动切回去瞄一眼瞄完再切回来继续写。一个高频的 20 分钟编码过程里面可能有七八次这种无效切窗。很多人在 VS Code 里用 Copilot 或 Cline 时没这个感觉因为它们的状态是嵌在编辑器侧边栏/面板里的你本来就盯着编辑器。Claude Code 是独立于编辑器的终端进程中间隔着一个窗口边界状态就断了。1.2 你需要的不是多开窗口而是状态出口有人会说分屏不就完了左边编辑器右边终端都摆在桌面上不用切。但实际做过开发就知道窗口多了之后Claude Code 的终端经常被其他窗口盖住打几个字、开个文档、看个浏览器它又被压到底下了。Windows 11 的任务视图和 Snap Layouts 能缓解但不能解决我要第一时间知道Agent状态这件事。更本质地说切窗口问题的核心不是窗口数量而是缺少一个状态出口。我们想要的状态提示应该是系统级的、常驻的、不占注意力的。悬浮球就是最典型的形式一个几十像素的小球贴在屏幕右上角绿色代表空闲黄色代表它在思考或跑工具红色代表它在等确认或者报错了。你不需要切窗口余光一扫就知道现在该不该回终端。这里还要说明一下为什么单独为 Claude Code 做悬浮球而不是直接选那种自带状态浮窗的 AI 编程工具。现在的 AI 编程工具大致分两派一派是 IDE 插件Copilot、Cline、Continue状态天然在编辑器里另一派是终端 AgentClaude Code、Gemini CLI 这类跑在终端里、可以用任意编辑器、操作的是整个项目而不仅是当前文件。终端派自由度太高注定了它不会主动给你画一个状态球。所以想省心就得自己在系统层加一点外挂。2. 悬浮球方案对比改终端、加显示器还是系统层擦玻璃2.1 几种常见思路的真实体验我给周边同事推荐过几类方案先说结论它们都能缓解切窗口但性价比差别很大。第一种是编辑器内嵌终端。VS Code 自带终端面板把 Claude Code 跑在里面这样至少切换距离短了。问题是终端面板被压在编辑器下方Agent 执行命令时输出区空间小得一屏放不下几行而且你还是得把注意力从代码区移到下方才能看到状态本质上没解决状态无感知。第二种是双屏。如果你有两个显示器一个放编辑器、一个放终端切窗口压力确实小很多。但双屏对居家办公和笔记本用户不现实而且人眼的注意力不会因为屏幕变了就自动分配很多时候还是会全神贯注地盯编辑器终端那屏成了摆设。第三种是改动 Claude Code 的插件或 Hook让它在任务完成时发系统通知。这个思路很接近正确答案Claude Code 本身也有流程控制脚本和消息解析接口可以拿到它的生命周期状态。但问题是Agent 在一个长任务里可能会连续调用十几次工具完成一次工具调用和整段任务完成是两码事通知反而会变得更吵。悬浮球是状态量不是事件量它不会打断你只看颜色就知道大约进行到哪一步。所以最终我选择第四种在操作系统层做一个常驻悬浮球和 Claude Code 的进程、日志解耦。它不侵入 Claude Code只是被动感知运行状态。这种方案的好处是即使哪天你换了一个终端 Agent悬浮球改一下检测逻辑照样能用。2.2 开发技术选型Python、AutoHotkey 还是 Tauri确定要做悬浮球之后还有一个技术选型问题。我重点对比了几个能在 Windows 11 上实现无边框 透明 置顶窗口的方案方案开发成本依赖体积置顶/透明适合人群AutoHotkey极低极小支持只需要简单状态灯PowerShell WinForms中系统自带支持不想装额外运行时Python tkinter中低需装 Python支持还要解析 JSON 日志Tauri / Electron高大支持想做完整产品我的选择是 Python tkinter。原因很直接悬浮球本身不是难点难的是感知 Claude Code 状态而这个状态藏在它本地会话日志的 JSONL 文件里。Python 处理 JSON、文件监控、进程检测是最顺手的标准库 tkinter 又刚好能画出透明置顶窗口不需要单独引入重量级 GUI 框架。你要是电脑上还没装 Python装一个 3.11 或 3.12 版本即可这一步并不复杂。3. 状态感知悬浮球怎么知道 Claude Code 正在干活3.1 方案一读 Claude Code 的本地会话日志Claude Code 每跑一个项目都会在用户目录下的.claude\projects里留下一堆 JSONL 会话日志。Windows 11 上的完整路径一般是C:\Users\你的用户名\.claude\projects\每个项目目录以项目路径的转义字符串命名目录里的.jsonl文件就是一次会话的记录每一行是一个 JSON 对象记录了时间戳、角色、消息内容、工具调用信息等等。悬浮球要做的核心事情就是找到当前最近被写入的那个 jsonl 文件然后看它的最近写入时间和最后几行内容推断出 Claude Code 当前处于什么状态。判断逻辑我设计了三个状态空闲绿色日志文件超过 35 秒没有新增内容且最后一条不是 assistant 正在输出。思考中/工具执行中黄色日志文件在最近 8 秒内有写入最后一条消息来自 assistant说明它还在持续产出。需要关注红色日志文件最近 8 秒没有写入但 Claude Code 进程还在大概率是在等你审批、或者卡在某条命令上。这个状态要结合进程检测才能更准。下面是读取日志并做基础状态判断的 Python 片段import json import os import time LOG_ROOT os.path.expanduser(~/.claude/projects) def latest_log_file(): 找到最近写入的会话日志文件 files [] for root, dirs, names in os.walk(LOG_ROOT): for name in names: if name.endswith(.jsonl): path os.path.join(root, name) files.append((os.path.getmtime(path), path)) if not files: return None files.sort(reverseTrue) return files[0][1] def eva_status(log_path, work_age8, idle_age35): 根据日志文件的修改时间判断状态 try: mtime os.path.getmtime(log_path) age time.time() - mtime except FileNotFoundError: return 0 if age work_age: # 最近有写入再确认最后一条是否来自 assistant try: with open(log_path, r, encodingutf-8) as f: lines [line for line in f if line.strip()] last json.loads(lines[-1]) if last.get(message, {}).get(role) assistant: return 1 # 思考中 except Exception: pass return 1 if age idle_age: return 1 return 0 # 空闲这段代码骨架看着简单但有两个容易翻车的细节。第一Claude Code 的日志是持续追加的不一定每个事件都立刻刷盘所以状态判断要有时间容忍度不能卡得太死8 秒和 35 秒这两个阈值是我反复试出来的写文档用途时可以直接抄。第二判断是否在思考不能只看文件有没有更新还要看最后一行 JSON 的角色因为有些写入是系统提示或者 tool 结果不代表 assistant 正在生成。3.2 方案二兜底检测进程和窗口标题日志方案已经能覆盖 90% 场景但它有一个盲区如果 Claude Code 正在等待用户审批日志可能不会频繁写入文件年龄会慢慢超过 8 秒状态就从黄色跌回空闲。所以我还加了一个兜底——检测进程是否存活。Claude Code 在 Windows 上多以 Node 进程方式运行进程名可能是node.exe命令行参数里包含claude。用 psutil 可以拿到进程列表并按 cmdline 过滤import psutil def is_claude_running(): for proc in psutil.process_iter([name, cmdline]): try: name (proc.info[name] or ).lower() cmdline .join(proc.info[cmdline] or []).lower() if claude in name or (node.exe in name and claude in cmdline): return True except Exception: continue return False这里要提醒一句不能写成只要看到 node.exe 就算 Claude 在跑否则你本地其他 Node 服务也会触发误报。命令行参数里带claude这个关键词才是最可靠的因为 Claude Code 实际是通过 node 加载 cli.js 启动的。窗口标题兜底也值得一提。Windows Terminal 在多标签场景下每个终端标签的标题会随前台程序变化。如果你用的是 Windows Terminal并且给它配置了动态标题那么在 Claude Code 运行期间终端标签页的标题往往会包含当前运行的命令或目录。可以用系统 API 枚举顶层窗口找到标题里带 claude 或项目名的窗口判断它是否在前台。不过窗口标题方案依赖终端配置通用性不如进程检测我的习惯是把它作为第二兜底。3.3 状态判定的工程取舍我把三个信号按优先级排了一下日志文件状态最准进程检测最稳窗口标题最弱但能辅助判断用户是不是正对着终端。实际轮询周期设在 1 秒一次不费 CPU肉眼看起来状态变化也够跟手。这里有一个不得不接受的现实Claude Code 内部的状态机比如正在思考和正在写文件其实分得很细但从外部通过日志倒推只能得到一个模糊状态。悬浮球是给你瞥一眼用的不是给 CI 系统用的所以模糊判断完全够用。你要是真的需要精确到它在调用哪个工具往下读第 4 章日志里其实有 tool_use 字段可以解析出来显示在悬浮球文字提示里但那属于进阶玩法别为了完美状态机反而把自己绕进去。4. 悬浮球本球用 Python 做一个右上角置顶状态小球4.1 准备运行环境写悬浮球之前先在 Windows 11 上确认三件事Python 已安装、能访问用户目录、tkinter 可用。tkinter 是 Python 默认带的普通安装包就包含不需要额外 pip。要装的第三方包只有 psutil 和 dll 头文件用到的 ctypesctypes 也是标准库所以实际只有一条命令pip install psutil推荐用 3.11 或 3.12。太老的 Python 版本在高 DPI 支持上不如新版悬浮球显示位置会莫名其妙偏半个屏幕。4.2 画一个无边框、置顶、透明背景的球tkinter 的overrideredirect(True)可以去掉标题栏和边框attributes(-topmost, True)让窗口永远置顶attributes(-transparentcolor, color)可以把指定颜色变成全透明。我的做法是设一个几乎不会用的颜色#010203作为窗口背景再把它设为透明色然后在这个透明窗口上画一个圆球。窗口默认位置放在屏幕右上角离边缘留 50 像素左右避免遮挡关闭按钮。import tkinter as tk import ctypes # 让窗口坐标按物理像素计算避免 Windows 11 缩放出问题 try: ctypes.windll.shcore.SetProcessDpiAwareness(1) except Exception: pass class StatusBall: COLORS { 0: #2ecc71, # 空闲绿 1: #f1c40f, # 思考中黄 2: #e74c3c, # 需关注红 } def __init__(self): self.root tk.Tk() self.root.overrideredirect(True) self.root.attributes(-topmost, True) self.root.attributes(-transparentcolor, #010203) self.root.configure(bg#010203) self.canvas tk.Canvas( self.root, width36, height36, bg#010203, highlightthickness0 ) self.canvas.pack() # 初始位置屏幕右上角 screen_w self.root.winfo_screenwidth() self.win_x screen_w - 60 self.win_y 70 self.root.geometry(f36x36{self.win_x}{self.win_y}) self._draw(0) self.root.mainloop() def _draw(self, status): self.canvas.delete(all) # 球体底色加一圈浅色描边 self.canvas.create_oval(2, 2, 34, 34, fillself.COLORS[status], outline#ffffff, width2)透明色窗口注意一个细节transparentcolor设置的透明色是全窗口级别的也就是说只要 canvas 上某个像素颜色等于这个值那几个像素就完全不参与显示和点击。所以球体以外的部分要留成透明这正好省了我做不规则窗口的麻烦。4.3 把状态轮询接进 tkinter 主循环悬浮球的状态不能阻塞 UI 主线程否则球会卡住拖不动。tkinter 里最简单的方式是用after定时器每 1000ms 调一次检查函数更新颜色和悬浮文字。class StatusBall: def __init__(self): # ... 前面的初始化 ... self.current_status 0 self.poll() def poll(self): newest latest_log_file() status eva_status(newest) if newest else 0 if not is_claude_running(): # Claude Code 完全没启动球收起来或显示灰色 status 0 if status ! self.current_status: self.current_status status self._draw(status) self.root.after(1000, self.poll)after的好处是不会在两次更新之间占用 CPU轮询一秒钟一次整体占用可以忽略。我实测同时开着 VS Code、Windows Terminal 和浏览器悬浮球进程内存占用不到 30MBCPU 基本为 0。4.4 拖拽、鼠标穿透、系统托盘这些交互细节悬浮球除了看状态还要允许用户把它拖到别的位置。tkinter 的 Canvas 绑定鼠标事件很简单def _on_press(self, event): self._drag_offset_x event.x self._drag_offset_y event.y def _on_drag(self, event): new_x self.root.winfo_pointerx() - self._drag_offset_x new_y self.root.winfo_pointery() - self._drag_offset_y self.root.geometry(f36x36{new_x}{new_y})还有一个高频需求是鼠标穿透。当悬浮球放在代码编辑区附近、挡住内容的时候你可能希望它不拦截鼠标点击。Windows 对窗口有一个扩展样式WS_EX_TRANSPARENT加上之后该窗口不会再接收鼠标事件相当于变成玻璃上的一张贴纸。配合右键菜单可以在可交互和完全穿透之间切换import ctypes GWL_EXSTYLE -20 WS_EX_LAYERED 0x00080000 WS_EX_TRANSPARENT 0x00000020 def set_click_through(hwnd, enabled): style ctypes.windll.user32.GetWindowLongW(hwnd, GWL_EXSTYLE) if enabled: style | WS_EX_LAYERED | WS_EX_TRANSPARENT else: style ~WS_EX_TRANSPARENT ctypes.windll.user32.SetWindowLongW(hwnd, GWL_EXSTYLE, style)右键菜单我用 tkinter 的Menu直接做菜单项包括打开 Claude Code 项目日志目录、暂停监控、切换鼠标穿透、退出。系统托盘可以做也可以不做。我给悬浮球加了一个最小化到托盘的行为用的库是pystraypip install pystray pillow托盘图标和悬浮球颜色保持同步。这样当你不小心把球关掉之后可以从托盘重新唤出不用再重启脚本。这一步属于锦上添花嫌麻烦可以先不加。4.5 性能与体积整套脚本加起来大概 200 行左右没有外部服务、没有后台任务就是一个纯粹的本地状态显示。它不向任何地方发送数据Claude Code 的会话日志也只是被读取最后几行。这个方案对隐私的侵入性很低比那些需要装 IDE 插件、会上传代码上下文的方案要轻得多。5. 实测两周的体验与踩坑记录5.1 踩坑 1-transparentcolor的透明色把球也变没了第一次画球的时候我把窗口背景色设成白色#ffffff并设为透明色然后 canvas 画球时也想用白色填充高光部分。结果球上凡是有白色的像素全部透明整个球坑坑洼洼。后来才意识到transparentcolor是基于像素值精确匹配的画球时所有色值必须和透明色完全不同。我的解决方法是透明色选#010203球体填充色用标准化色板描边用#ffffff只要不用#010203就不会出问题。5.2 踩坑 2日志文件轮换导致监控失效Claude Code 不是永远往同一个 jsonl 文件里写。新开会话、主动/clear、或者项目切换都会生成新文件。我的第一版监控只用latest_log_file()取一次文件句柄结果一开会话文件变了悬浮球还盯着旧文件状态永远停在绿色。修复方案是每次 poll 都重新扫描目录重新找最新的 jsonl 文件。成本很低但确实容易漏。另外Windows 上日志文件被占用的情况不算多Claude Code 用的是追加写模式Python 以只读方式打开不会撞锁不需要特殊处理。5.3 踩坑 3Windows 11 高 DPI 下的坐标漂移这是最有 Windows 味的一个坑。Windows 11 默认 150% 缩放tkinter 如果不在初始化时设置进程级 DPI 感知窗口坐标和鼠标坐标走的是两套单位拖拽时球会飘——你按住球往右拖它却往右下角窜。解决方式就是在创建 tkinter 窗口之前强制设置 DPI 感知ctypes.windll.shcore.SetProcessDpiAwareness(1)设置之后geometry 的坐标系和winfo_screenwidth()返回的值会保持一致。多显示器环境下最好用虚拟屏幕坐标winfo_screenwidth()拿到的只是主显示器宽度副屏上的默认落点会不准这一点笔记本外接屏幕用户尤其要当心。5.4 踩坑 4鼠标穿透之后拖不回来了开了鼠标穿透后窗口完全不接收鼠标事件自然也没法通过拖拽取消穿透。我一开始没做热键结果球卡在屏幕角落死掉了只能杀掉进程重启。后来加了两个出口一个是右键菜单在穿透模式下仍可用因为WS_EX_TRANSPARENT只影响鼠标点击穿透对右键菜单这种系统交互不一定拦截另一个是全局热键——在穿透模式下按CtrlAltB强制关闭穿透并恢复可拖拽。Windows 上注册全局热键可以用keyboard库也可以直接用RegisterHotKey我更推荐后者少一个 pip 依赖。5.5 实测结论值不值得装用了两周最直接的感受是切终端的次数至少降了一半。以前写一个多文件重构任务每隔几分钟就切回去看一眼进度现在只要余光扫一下右上角黄色说明还在跑绿色说明停了该切回去给指令或者确认结果。悬浮球不是万能的它不能告诉你这次改动改坏了哪一行但它把是否要切窗口这个决策成本降到了最低。另外我把它和 Claude Code 的 session 管理配合起来用红色闪烁时直接单击球体会触发一个脚本把 Windows Terminal 切到前台并激活 Claude Code 的会话窗口。这个比手动从任务栏点要顺手得多算是悬浮球最有增值空间的扩展点。6. 不写代码版用 AutoHotkey 二十行实现简版悬浮灯Python 方案适合愿意维护脚本的人。如果你只是想要一个能用的状态灯不想装 Python 也不想碰 JSONAutoHotkey 可以用二十行脚本解决问题。AHK 的思路简单粗暴每隔几秒检测一次指定窗口或进程是否存在然后修改球的颜色。如果你把 Claude Code 跑在一个固定的 Windows Terminal 标签页里可以检测该标签页的窗口标题是否包含项目名也可以直接检测node.exe进程是否存在但这样误报率会高一些。下面是我实际用过的简版脚本#Persistent #SingleInstance Force ; 初始悬浮球 Gui, New, AlwaysOnTop -Caption ToolWindow Gui, Color, 2EFF2E Gui, Show, x1520 y80 w25 h25, ClaudeStatusBall SetTimer, CheckStatus, 5000 return CheckStatus: ; 检测窗口标题里是否含 claude按你终端标签实际标题改 WinGet, activeWinList, List, claude if (activeWinList 0) Gui, Color, 2EFF2E ; 有相关窗口绿色 else Gui, Color, FF4444 ; 没找着红色 return ^b:: Gui, Cancel ExitApp return这个版本不是真正识别 Claude Code 的运行状态它只是检测有没有相关窗口/进程存活所以更准确的名字是窗口存在性指示灯。好处是零依赖、秒启动、不占内存适合开会时给旁边的人看我现在 AI 正在干活别打断我。AHK 版还能进一步加一点状态感用Gosub配合SetTimer做颜色呼吸效果或者用Gui, LastFoundWinSet, Transparent调整透明度。但核心局限很明显——它读不到日志内容无法区分思考中和等审批。如果你的工作流里 Claude Code 频繁需要审批确认AHK 简版会频繁显示同一种颜色参考价值不大。7. 从悬浮球到完整工作流几个我仍在用的扩展方向文章写到这悬浮球本身的功能就讲完了。额外说几个我还在调试的扩展方向给想折腾的读者当参考。第一个方向是给悬浮球加文本气泡提示。日志里有 tool_use 字段能拿到当前调用的是 Read、Edit 还是 Bash把工具名显示在球旁边。我试过用 tkinter 的Label做动态文字状态切换时闪一下正在 Edit 文件 xxx比单纯颜色更直观。注意别让气泡挡住代码区我把它放在球的下方停留 2 秒自动消失。第二个方向是把状态通过 WebSocket 或 MQTT 推给手机/其他电脑。这样人在客厅、机器在书房跑长任务时手机看一眼就能知道跑完没有。这个方案我还没完全稳定因为要额外起一个本地 WebSocket 服务悬浮球作为客户端连接复杂度比纯本地高一个台阶。第三个方向是让悬浮球反向控制 Claude Code。Claude Code 支持非交互式运行模式可以claude -p ...直接给指令。悬浮球上做一个输入框按快捷键弹出输入内容后直接以非交互模式发给正在运行的会话相当于给你的终端 Agent 加了一个悬浮快捷指令入口。这个玩法还没有成熟但因为 Claude Code 的命令行协议是开放的实现路径已经比较清晰。如果你只需要解决频繁切窗口这一个问题第一版 Python 悬浮球完全够用——它稳定、轻量、逻辑透明代码也不长。我在实际使用中的体会是工具越简单越好修别在第一天就把功能堆满先让球亮起来、转起来再根据自己真正的使用节奏往里加交互。等跑两三周你会发现那些看着酷炫的花活大部分都用不上真正高频的其实就三件事绿色、黄色、红色外加一键切回终端。