如何用Headroom包裹Claude Codewrap命令参数与Serena代码导航全解【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroomHeadroom 是一个本地优先的 AI 上下文压缩层它能在工具输出、日志、文件和 RAG 分块到达 LLM 之前进行压缩——编码代理可少花约 20% 的 tokenJSON 类内容可少 60-95% 的 token而回答质量不变。对于 Claude Code 用户来说最省心的接入方式就是一条命令headroom wrap claude。本文带你完整拆解 wrap 命令的工作机制、全部常用参数以及它默认安装的 Serena 代码导航引擎是如何省 token 的。wrap 命令做了什么一次启动四件事headroom wrap claude并不是简单地套一层代理它在一次启动里替你完成了四件事启动本地代理在127.0.0.1:8787启动 Headroom 代理端口可改所有 Anthropic API 流量先经过它压缩再转发给官方端点注册 headroom MCP把headroom_retrieve等检索工具注入 Claude Code让模型在需要原文时可以按需取回CCR 可逆压缩注册 Serena MCP安装 Serena 作为代码记忆引擎提供符号级代码导航工具见下文详解改写环境变量并启动 Claude Code自动设置ANTHROPIC_BASE_URL指向代理然后拉起你本地的claude进程。退出会话后代理会做引用计数清理其他还在运行的 wrap 实例不受影响。实现都在 wrap 命令源码 中想深挖细节可以读它。一键包裹Claude Code的完整步骤第一步安装uv tool install --python 3.13 headroom-ai[all] # 推荐独立虚拟环境 # 或 pip install headroom-ai[all]如果需要从源码构建仓库地址是 https://gitcode.com/GitHub_Trending/head/headroom 仅此一处clone 后pip install -e .[all]即可。第二步包裹并启动cd 你的项目目录 headroom wrap claude第三步验证headroom doctor # 健康检查确认流量确实走了代理 headroom perf # 查看压缩统计 headroom dashboard # 实时节省看板代理需运行中不想要时一条headroom unwrap claude即可还原所有配置。wrap claude 核心参数速查表下面是 wrap claude 子命令定义 中最值得知道的参数按高频→进阶排列参数作用适用场景--port 8787指定代理端口被占用时自动探测下一个空闲端口多开会话--memory启用跨会话持久记忆启动前先同步 memory.db长项目--learn开启实时流量学习把有效模式写入 MEMORY.md想让代理越用越聪明--code-memory none不安装 Serena唯一关闭代码记忆的方式轻量使用--no-mcp跳过 headroom MCP 注册压缩标记将不可检索只压缩、不取回--no-proxy复用已运行的代理不重复启动已手动起了headroom proxy--code-graph开启代理的实时代码图文件监听大型代码库--tool-search true保持 Claude Code 的按需工具加载延迟加载开启上下文偏大的项目默认行为--1m通过ANTHROPIC_MODELopus[1m]保住 1M 上下文窗口订阅用户的超长会话--backend/--region指定代理后端如 Vertex/Bedrock与云区域云上认证模式--serena-instructions向CLAUDE.md注入优先用 Serena 符号工具的指引opt-in想强推符号导航--verbose详细输出每一步注册结果排障两个容易踩坑的点--之后的一切参数都会透传给 claude 本身例如headroom wrap claude -- --resume id恢复会话、headroom wrap claude -- -p进入 print 模式--tool-search之所以重要是因为当ANTHROPIC_BASE_URL是自定义地址时Claude Code 会退化为把所有工具 schema 一次性加载本地上下文会凭空多出几万 tokenwrap 默认帮你保住了延迟加载。Serena 代码导航wrap 默认安装的代码记忆引擎Serena 是wrap claude的默认代码记忆 MCPSerena 规格构建代码它通过uvx --from serena-agent serena start-mcp-server启动基于语言服务器把项目代码变成符号图注册在用户级作用域Claude Code 下写入~/.claude.json所以装一次其他项目也能用直到你headroom unwrap。它给 Claude Code 提供四个核心符号工具这正是省 token 的关键——只返回你要的代码而不是整个文件get_symbols_overview(file)打开文件前先列出它的顶层符号find_symbol(name)直接取某个符号的定义/函数体替代整文件读取find_referencing_symbols(name)找调用点/使用处替代全库 grepfind_declaration(name)跳到符号定义处。三个自动化的贴心细节预索引如果项目已存在.serena/project.ymlwrap 会同步执行serena project index预热符号缓存上限 300 秒可用HEADROOM_SERENA_INDEX_TIMEOUT调整首次使用的项目则由 Serena MCP 在启动时按需自动建索引不阻塞启动关闭仪表盘弹窗Headroom 会强制--open-web-dashboard False避免每次 wrap 都弹出一个浏览器标签页指引注入是 opt-in只有加--serena-instructions时才会向CLAUDE.md追加优先用符号工具、必要时才读整文件的工作流指引带标记注释幂等不重复。如果你不需要 Serena用--code-memory none即可完全跳过已有的旧版 tokensave 条目会被自动清理并迁移到 Serena。三个最实用的组合场景# 1. 长项目 持久记忆 流量学习 headroom wrap claude --memory --learn # 2. 超长上下文会话1M 窗口 恢复上次会话 headroom wrap claude --1m -- --resume session-id # 3. 云上模式Vertex 原生认证代理只负责压缩 CLAUDE_CODE_USE_VERTEX1 headroom wrap claude --region us-central1跑完一个任务后用headroom perf或headroom dashboard看看实际节省了多少 token——在官方基准里代码搜索、SRE 排障类工作负载的压缩率普遍在 73%-92%而答案质量不变。这大概就是包裹二字最直观的回报你不用改一行代码Claude Code 的每次请求都自动瘦身后出发。【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考