Muxy 如何拦截 Claude Code 与 Codex 的 HookUnix Socket 代理协议全解析【免费下载链接】muxyLightweight and Memory efficient terminal for Mac built with SwiftUI and libghostty项目地址: https://gitcode.com/gh_mirrors/muxy1/muxyMuxy是一款基于 SwiftUI libghostty 构建的轻量级 Mac 终端但它还有一个更有趣的能力不改一行 AI 工具的代码就能把Claude Code和Codex的任务进展事件拦截下来实时在终端里变成通知。本文带你完整拆解 Muxy 的 Hook 拦截链路和本地 Unix Socket 代理协议从写入配置到失败重试每一步都讲清楚不需要任何网络编程基础也能看懂。全局概览拦截到底是怎么实现的Claude Code 和 Codex 都没有提供通知 Muxy 我干完了的官方 API但它们都支持Hook 机制——允许你在特定时机任务完成、等待授权等自动执行一段外部脚本。Muxy 的做法非常直接 安装时Muxy 把一个小脚本muxy-*-hook.sh写进两个工具的 Hook 配置列表 事件触发时脚本启动 Muxy 附带的muxy-hook桥接进程 桥接进程读取事件 JSON封装成一行协议消息发送给 Muxy 的 Unix Socket并等待服务端确认️ Muxy 主进程根据事件定位到对应的终端分屏推送进行中 / 需要关注 / 已完成的状态通知。下面逐段拆解整条链路。一、注入阶段Muxy 如何把 Hook 写进 Claude Code 与 CodexClaude Code7 个事件各挂一行脚本Muxy 不会整体覆盖 Claude 的配置而是合并——在~/.claude/settings.json的hooks字段下逐项加入自己的条目且每条命令末尾都带一个标记注释muxy-notification-hook方便后续校验和卸载时精确识别哪些是我加的。注册的事件清单定义在 ClaudeCodeProvider.swift事件键Muxy 事件名含义Stopstop任务完成StopFailurestop-failure任务失败SessionEndsession-end会话结束Notificationnotification通用通知按类型细分PermissionRequestpermission-request等待权限确认UserPromptSubmituser-prompt-submit用户提交提示词PreToolUsepre-tool-use即将调用工具每条 hook 形如muxy-claude-hook.sh stop # muxy-notification-hook超时统一设为10 秒见 ClaudeCodeProvider.swift保证即使 Muxy 没在运行也不会把 Claude 卡住。Codex4 个事件 冲突检测Codex 的 Hook 文件是~/.codex/hooks.jsonMuxy 只注册 4 个核心事件UserPromptSubmit、PreToolUse、PermissionRequest、Stop见 CodexProvider.swift。Codex 还支持在config.toml里直接写内联 hook会与 Muxy 的方式冲突所以写入前 Muxy 会先做冲突检测——发现内联 hook 就报出明确的错误绝不静默覆盖用户配置。健康自检与自动修复写配置只是第一步。Muxy 的 HookInstaller.swift 实现了完整的verify → needsRepair → repair → 再验证状态机 每次启动执行reconcile配置完好返回healthy被改坏则自动修复并记录到健康状态存储 写入前所有脚本和muxy-hook二进制会先被staged复制到~/Library/Application Support/Muxy/hooks/目录确保 Muxy 升级或重装后外部工具引用的 hook 路径依然有效暂存逻辑见 MuxyNotificationHooks.swift❌ 功能关闭时removeManagedState只精确移除带 Muxy 标记的条目不动用户自己的 hook。二、转发阶段脚本只是传话筒真正干活的是桥接进程hook 脚本本身只有 4 行它只是把执行权交给同目录下的muxy-hook并传上提供者与事件名bin$(dirname $0)/muxy-hook [ -x $bin ] || exit 0 exec $bin agent-event --provider claude_hook --provider-title Claude Code --event ${1:-}源码见 muxy-claude-hook.shCodex 版 muxy-codex-hook.sh 只是--provider不同。注意那句[ -x $bin ] || exit 0二进制不存在时静默退出连错误都不打印最大限度降低对宿主工具的干扰。桥接进程 MuxyHookBridge/main.swift 做三件事 从stdin读取 Hook 工具传入的 JSON 载荷有字节上限和时间预算 AgentHookEventMapper 把各工具的原始事件统一映射为三态working进行中/waiting等待关注/finished完成例如PermissionRequest → waiting、Stop → finished无意义的重复事件如session-end直接过滤掉 组装成AgentHookEventMessage交给 socket 客户端关键字段有字段来源作用provider命令行参数区分 claude / codex 等来源paneIDMUXY_PANE_ID环境变量Muxy 启动终端时注入可精确定位分屏pids祖先进程链没有paneID时服务端靠进程树反查终端phase/title/body映射器输出决定通知的文案与状态完整组装流程见 AgentHookRuntime.swift。三、协议全解析一行 JSON 一次确认的 Unix Socket 代理这是 Muxy 设计中最核心的部分。整个协议定义在 AgentHookProtocol.swift️版本号v3消息类型kindagent_event收发双方都校验版本与类型不匹配直接丢弃保证新旧版本共存时不会互相误解帧格式 一行 JSON \n序列化时排序键名编解码完全确定性见AgentHookWireCodecAgentHookProtocol.swift✅ 服务端收到消息后必须回一行确认{kind:ack,ok:true}客户端收到合法 ack 才算投递成功。服务端地址默认是~/Library/Application Support/Muxy/muxy.sock开发构建用muxy-dev.sock也支持用MUXY_SOCKET_PATH环境变量覆盖见 AgentHookPaths.swift 与 AgentHookRuntime.swift。客户端连接、写入、等待确认全程限时AgentHookSocketClient.swift 用快速失败策略实现整条传输参数默认值含义maximumAttempts3 次最多尝试连接 3 次totalBudget0.4 秒整个发送过程的总时间预算超了立刻放弃retryDelay0.02 秒两次重试之间的间隔几个值得称道的工程细节 socket 上设置SO_NOSIGPIPE服务端中途断开也不会让进程被信号击毙见 configure⏱️ 全程非阻塞 I/O poll等待就绪到截止时间才放弃绝不无谓长眠 重试耗尽也不弹窗而是把失败追加写入hooks.log见 AgentHookFailureLogger默认以退出码 0 结束——Hook 失败永远不影响 AI 工具本身的运行。服务端校验、去重、精准投递Muxy 主进程侧由 NotificationSocketServer.swift 绑定AF_UNIX SOCK_STREAMsocket 并常驻监听startListening。每条 Hook 事件进来后经过三道关卡格式校验版本号、kind、非空provider、合法 UUID 的paneID缺一即丢弃parseAgentHookEventMessage去重维护最近 256 条事件 ID 的滑动窗口RecentAgentHookEventIDs同一id只投递一次Hook 工具重复上报不会造成重复通知投递先回ack再把事件派发到主线程按paneID或祖先进程匹配到终端分屏更新状态存储并弹出通知dispatchAgentHookEvent。在 handleLine 里能看到先应答、后处理的清晰顺序ack 优先返回客户端无需等 Muxy 处理完 UI。四、为什么这么设计三点工程权衡文件系统 socket 而非 TCP纯本机通信不占端口、不受防火墙影响socket 文件权限设为 0700其他用户无法注入伪造事件一行 JSON 而非二进制协议方便排错日志里每一条事件都能直接还原成可读内容预算 重试 兜底日志事件投递的最坏结果是hooks.log 里多一条记录agent 的使用体验永远是最高优先级。五、源码导航快速定位核心模块想动手深入建议按这条路径阅读Hook 脚本muxy-claude-hook.sh、muxy-codex-hook.sh提供者注入逻辑ClaudeCodeProvider.swift、CodexProvider.swift安装与健康自检HookInstaller.swift桥接进程MuxyHookBridge/main.swift协议定义AgentHookProtocol.swiftSocket 客户端AgentHookSocketClient.swiftSocket 服务端NotificationSocketServer.swift一句话总结Muxy 没有黑进任何 agent它只是在官方 Hook 机制里注册了一个信使信使在 0.4 秒内把事件送达 Muxy送不到就安静离开——这就是一个本地 Unix Socket 代理协议优雅的分界线。【免费下载链接】muxyLightweight and Memory efficient terminal for Mac built with SwiftUI and libghostty项目地址: https://gitcode.com/gh_mirrors/muxy1/muxy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/7 10:15:02 · 阅读 1.2k Muxy 如何拦截 Claude Code 与 Codex 的 Hook？Unix Socket 代理协议全解析
Muxy 如何拦截 Claude Code 与 Codex 的 HookUnix Socket 代理协议全解析【免费下载链接】muxyLightweight and Memory efficient terminal for Mac built with SwiftUI and libghostty项目地址: https://gitcode.com/gh_mirrors/muxy1/muxyMuxy是一款基于 SwiftUI libghostty 构建的轻量级 Mac 终端但它还有一个更有趣的能力不改一行 AI 工具的代码就能把Claude Code和Codex的任务进展事件拦截下来实时在终端里变成通知。本文带你完整拆解 Muxy 的 Hook 拦截链路和本地 Unix Socket 代理协议从写入配置到失败重试每一步都讲清楚不需要任何网络编程基础也能看懂。全局概览拦截到底是怎么实现的Claude Code 和 Codex 都没有提供通知 Muxy 我干完了的官方 API但它们都支持Hook 机制——允许你在特定时机任务完成、等待授权等自动执行一段外部脚本。Muxy 的做法非常直接 安装时Muxy 把一个小脚本muxy-*-hook.sh写进两个工具的 Hook 配置列表 事件触发时脚本启动 Muxy 附带的muxy-hook桥接进程 桥接进程读取事件 JSON封装成一行协议消息发送给 Muxy 的 Unix Socket并等待服务端确认️ Muxy 主进程根据事件定位到对应的终端分屏推送进行中 / 需要关注 / 已完成的状态通知。下面逐段拆解整条链路。一、注入阶段Muxy 如何把 Hook 写进 Claude Code 与 CodexClaude Code7 个事件各挂一行脚本Muxy 不会整体覆盖 Claude 的配置而是合并——在~/.claude/settings.json的hooks字段下逐项加入自己的条目且每条命令末尾都带一个标记注释muxy-notification-hook方便后续校验和卸载时精确识别哪些是我加的。注册的事件清单定义在 ClaudeCodeProvider.swift事件键Muxy 事件名含义Stopstop任务完成StopFailurestop-failure任务失败SessionEndsession-end会话结束Notificationnotification通用通知按类型细分PermissionRequestpermission-request等待权限确认UserPromptSubmituser-prompt-submit用户提交提示词PreToolUsepre-tool-use即将调用工具每条 hook 形如muxy-claude-hook.sh stop # muxy-notification-hook超时统一设为10 秒见 ClaudeCodeProvider.swift保证即使 Muxy 没在运行也不会把 Claude 卡住。Codex4 个事件 冲突检测Codex 的 Hook 文件是~/.codex/hooks.jsonMuxy 只注册 4 个核心事件UserPromptSubmit、PreToolUse、PermissionRequest、Stop见 CodexProvider.swift。Codex 还支持在config.toml里直接写内联 hook会与 Muxy 的方式冲突所以写入前 Muxy 会先做冲突检测——发现内联 hook 就报出明确的错误绝不静默覆盖用户配置。健康自检与自动修复写配置只是第一步。Muxy 的 HookInstaller.swift 实现了完整的verify → needsRepair → repair → 再验证状态机 每次启动执行reconcile配置完好返回healthy被改坏则自动修复并记录到健康状态存储 写入前所有脚本和muxy-hook二进制会先被staged复制到~/Library/Application Support/Muxy/hooks/目录确保 Muxy 升级或重装后外部工具引用的 hook 路径依然有效暂存逻辑见 MuxyNotificationHooks.swift❌ 功能关闭时removeManagedState只精确移除带 Muxy 标记的条目不动用户自己的 hook。二、转发阶段脚本只是传话筒真正干活的是桥接进程hook 脚本本身只有 4 行它只是把执行权交给同目录下的muxy-hook并传上提供者与事件名bin$(dirname $0)/muxy-hook [ -x $bin ] || exit 0 exec $bin agent-event --provider claude_hook --provider-title Claude Code --event ${1:-}源码见 muxy-claude-hook.shCodex 版 muxy-codex-hook.sh 只是--provider不同。注意那句[ -x $bin ] || exit 0二进制不存在时静默退出连错误都不打印最大限度降低对宿主工具的干扰。桥接进程 MuxyHookBridge/main.swift 做三件事 从stdin读取 Hook 工具传入的 JSON 载荷有字节上限和时间预算 AgentHookEventMapper 把各工具的原始事件统一映射为三态working进行中/waiting等待关注/finished完成例如PermissionRequest → waiting、Stop → finished无意义的重复事件如session-end直接过滤掉 组装成AgentHookEventMessage交给 socket 客户端关键字段有字段来源作用provider命令行参数区分 claude / codex 等来源paneIDMUXY_PANE_ID环境变量Muxy 启动终端时注入可精确定位分屏pids祖先进程链没有paneID时服务端靠进程树反查终端phase/title/body映射器输出决定通知的文案与状态完整组装流程见 AgentHookRuntime.swift。三、协议全解析一行 JSON 一次确认的 Unix Socket 代理这是 Muxy 设计中最核心的部分。整个协议定义在 AgentHookProtocol.swift️版本号v3消息类型kindagent_event收发双方都校验版本与类型不匹配直接丢弃保证新旧版本共存时不会互相误解帧格式 一行 JSON \n序列化时排序键名编解码完全确定性见AgentHookWireCodecAgentHookProtocol.swift✅ 服务端收到消息后必须回一行确认{kind:ack,ok:true}客户端收到合法 ack 才算投递成功。服务端地址默认是~/Library/Application Support/Muxy/muxy.sock开发构建用muxy-dev.sock也支持用MUXY_SOCKET_PATH环境变量覆盖见 AgentHookPaths.swift 与 AgentHookRuntime.swift。客户端连接、写入、等待确认全程限时AgentHookSocketClient.swift 用快速失败策略实现整条传输参数默认值含义maximumAttempts3 次最多尝试连接 3 次totalBudget0.4 秒整个发送过程的总时间预算超了立刻放弃retryDelay0.02 秒两次重试之间的间隔几个值得称道的工程细节 socket 上设置SO_NOSIGPIPE服务端中途断开也不会让进程被信号击毙见 configure⏱️ 全程非阻塞 I/O poll等待就绪到截止时间才放弃绝不无谓长眠 重试耗尽也不弹窗而是把失败追加写入hooks.log见 AgentHookFailureLogger默认以退出码 0 结束——Hook 失败永远不影响 AI 工具本身的运行。服务端校验、去重、精准投递Muxy 主进程侧由 NotificationSocketServer.swift 绑定AF_UNIX SOCK_STREAMsocket 并常驻监听startListening。每条 Hook 事件进来后经过三道关卡格式校验版本号、kind、非空provider、合法 UUID 的paneID缺一即丢弃parseAgentHookEventMessage去重维护最近 256 条事件 ID 的滑动窗口RecentAgentHookEventIDs同一id只投递一次Hook 工具重复上报不会造成重复通知投递先回ack再把事件派发到主线程按paneID或祖先进程匹配到终端分屏更新状态存储并弹出通知dispatchAgentHookEvent。在 handleLine 里能看到先应答、后处理的清晰顺序ack 优先返回客户端无需等 Muxy 处理完 UI。四、为什么这么设计三点工程权衡文件系统 socket 而非 TCP纯本机通信不占端口、不受防火墙影响socket 文件权限设为 0700其他用户无法注入伪造事件一行 JSON 而非二进制协议方便排错日志里每一条事件都能直接还原成可读内容预算 重试 兜底日志事件投递的最坏结果是hooks.log 里多一条记录agent 的使用体验永远是最高优先级。五、源码导航快速定位核心模块想动手深入建议按这条路径阅读Hook 脚本muxy-claude-hook.sh、muxy-codex-hook.sh提供者注入逻辑ClaudeCodeProvider.swift、CodexProvider.swift安装与健康自检HookInstaller.swift桥接进程MuxyHookBridge/main.swift协议定义AgentHookProtocol.swiftSocket 客户端AgentHookSocketClient.swiftSocket 服务端NotificationSocketServer.swift一句话总结Muxy 没有黑进任何 agent它只是在官方 Hook 机制里注册了一个信使信使在 0.4 秒内把事件送达 Muxy送不到就安静离开——这就是一个本地 Unix Socket 代理协议优雅的分界线。【免费下载链接】muxyLightweight and Memory efficient terminal for Mac built with SwiftUI and libghostty项目地址: https://gitcode.com/gh_mirrors/muxy1/muxy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考