omni-context-cli 0.0.69 → 0.0.71

package/README.md

@@ -1,3 +1,166 @@
-# Omni Context CLI
+# OmniContext CLI
 
-Omx is a small, helpful, zero-telemetry coding assistant.
+**Precision context. Minimal cost.**
+
+OmniContext CLI is a terminal-native coding assistant that treats context as a first-class resource. Lean system prompts keep overhead low. Specialist delegation routes grunt work to cheaper models while keeping your main context clean. Zero telemetry means your code never leaves your machine. And it extends into VS Code, Office, the browser, Figma, Obsidian, and Zed.
+
+```bash
+npm install -g omni-context-cli && omx
+```
+
+## How It Works
+
+Traditional assistants call basic tools one at a time, resending your entire context with every round. OmniContext CLI delegates multi-step operations to agentic sub-agents running on a cheaper model -- your expensive model stays focused on reasoning, not file I/O.
+
+**Task: "Find the definition of `handleAuth`"**
+
+Traditional approach:
+
+| Round | Call | Result |
+|-------|------|--------|
+| R1 | `glob("src/**/*.ts")` | 43 files returned |
+| R2 | `grep("handleAuth", ...)` | 7 matches in 4 files |
+| R3 | `read("src/middleware/auth.ts")` | 186 lines -- wrong file |
+| R4 | `read("src/routes/login.ts")` | 124 lines -- still looking |
+| R5 | `read("src/services/auth.ts", 40-90)` | Found it -- 50 more lines |
+
+> 5 rounds, ~12K context added, all on main model
+
+Specialist mode:
+
+| Round | Call | Result |
+|-------|------|--------|
+| R1 | `pluck("handleAuth definition")` | Sub-agent (cheap model): glob -> grep -> read -> locate -> extract |
+
+> 1 round, ~1K context added, grunt work on cheap model
+
+## Agentic Tools
+
+Each tool runs as an autonomous sub-agent on a cheaper model. It handles file I/O, error recovery, and retries internally -- keeping intermediate output out of your main context and your token bill down.
+
+| Tool | Purpose |
+|------|---------|
+| **explore** | Survey project architecture -- directory layout, key files, and how the codebase is organized |
+| **spark** | Run shell commands with automatic error detection and retry |
+| **sculpt** | Edit files with surgical precision, find the right location, make the change, validate the result |
+| **weave** | Write entire files from scratch with auto-validation |
+| **sweep** | Find files matching complex criteria by name, content, or structure |
+| **pluck** | Extract specific code segments -- functions, classes, or blocks you need |
+| **ripple** | Trace symbol references across your codebase |
+| **slice** | Answer targeted code questions by reading only the relevant parts |
+| **quest** | Research topics via web search |
+| **glance** | Preview multiple files at once with brief summaries |
+
+## Workflow Presets
+
+Switch how OmniContext CLI behaves with a single command. Each preset changes the tools available, the system prompt, and the response style.
+
+| Preset | Description |
+|--------|-------------|
+| **Specialist** (default) | Your main model reasons, a cheaper agent model executes. Fewer rounds, cleaner context, lower cost. |
+| **Explorer** | Research-first mode. Launches multiple web searches before answering. Great for current events, docs, and fact-checking. |
+| **Artist** | Visual-first responses. Prioritizes image generation when the model supports it. Ideal for design exploration and mockups. |
+| **Assistant** | Personal assistant for app integrations. Controls browser tabs, Office documents, and Figma designs through natural language. |
+| **Normal** | Basic tools with manual orchestration. Direct read, write, edit, and bash access. Full control, no abstraction. |
+
+## Native Multi-Protocol
+
+Most tools funnel everything through a single API format and hope for the best. OmniContext CLI has a dedicated request builder and stream handler for each protocol. Prompt caching, extended thinking, and provider-specific features work exactly as the vendor intended -- no lossy translation layer in between.
+
+| Protocol | Description |
+|----------|-------------|
+| **Anthropic** | Native Messages API with prompt caching, extended thinking, and streaming. Token-level cache control via custom TTL. |
+| **OpenAI** | Native Chat Completions API. Compatible with any endpoint that speaks the OpenAI format. |
+| **Gemini** | Native generateContent API with Gemini-specific streaming. Tools and function calling use Gemini's own schema. |
+| **Responses API** | OpenAI's newer Responses API with built-in tool orchestration. Separate path from Chat Completions. |
+
+## Cost Optimization
+
+Every API call resends your full conversation history. Fewer rounds means fewer cache reads. Cleaner context means fewer tokens written. Specialist mode cuts both -- and offloads the grunt work to a cheaper model.
+
+- **Fewer API rounds** -- Traditional tools need 5 rounds to find a function definition. Specialist mode does it in 1. That's 4 fewer full-context resends -- saving cache read costs on every skipped round.
+- **Smaller context growth** -- Basic tools dump ~10KB of intermediate output into your conversation. Agentic tools return only the final result. Context editing automatically trims old tool payloads and thinking blocks, keeping growth in check even over long sessions.
+- **Cheap model for execution** -- Sub-agents run on a low-cost model while your main model handles only planning and decisions. The expensive model never does file I/O.
+- **1-hour cache for deep work** -- The default 5-minute prompt cache expires if you pause to think. Switch to 1-hour for debugging, refactoring, or research -- it eliminates repeated cache rebuilds across a session.
+
+**Simulated cost comparison: "Find the definition of handleAuth"**
+
+| | Traditional | Specialist | Saved |
+|---|---|---|---|
+| API rounds | 5 | 1 | -4 rounds |
+| Cache read per round | ~20K tokens x 5 | ~20K tokens x 1 | -80K tokens |
+| New context added | ~10KB | ~3KB | -70% |
+| Cache write (new tokens) | ~2.5K tokens | ~1K tokens | -60% |
+| Execution model | Expensive model only | Expensive + cheap | ~30% cheaper |
+
+*Based on a 20K-token conversation finding a function across a TypeScript project. Actual savings depend on project size and model pricing.*
+
+## Model Providers
+
+One command to add all your models. OmniContext CLI ships with built-in provider presets -- pick one, paste your API key, and every model from that service is ready to use.
+
+```bash
+# List available providers
+$ omx --list-providers
+
+# Add all models from a provider in one go
+$ omx --add-provider zenmux --api-key zmx-...
+
+# Remove a provider just as easily
+$ omx --remove-provider zenmux
+```
+
+Built-in providers: **Zenmux**, **DeepSeek**, **OpenRouter**, **Zhipu (GLM)**, **MiniMax**
+
+## Cross-Session Memory
+
+OmniContext CLI remembers your coding style, project patterns, and past decisions across sessions. Key points are extracted from every conversation and injected into future sessions. Helpful points gain score, harmful ones drop fast, unused ones decay naturally. Each project has its own memory file -- edit it directly if you want full control.
+
+## Integrations
+
+Terminal is home base, but OmniContext CLI reaches into every tool you use. One AI, consistent context, zero context switching.
+
+- **VS Code Extension** -- full IDE integration with file context, diagnostics, and diff views
+- **Desktop App** -- standalone GUI that acts as the local hub connecting Office, browser, and Figma extensions
+- **Chrome Extension** -- sidebar on any webpage for summarization, data extraction, and browser automation
+- **Office Add-in** -- AI panel inside Word, Excel, and PowerPoint
+- **Figma Plugin** -- inspect layouts, create shapes, modify nodes, and export assets through chat
+- **Zed Editor** -- external agent via Agent Client Protocol with full tool access
+- **Web Client** -- browser UI with LaTeX, Mermaid diagrams, file attachments, and drag-and-drop
+- **Mobile Access** -- run `omx --serve` and connect from your phone
+
+## Extensibility
+
+Custom agents, skills, slash commands, and MCP servers. Everything is a markdown file or JSON config.
+
+- **Custom SubAgents** -- write a markdown file with a prompt template and tool permissions. It becomes a new agentic tool instantly. Add `OMX-AGENTS.md` for global agent instructions.
+- **Custom Skills** -- teach OmniContext CLI domain-specific knowledge and workflows. Skills inject instructions into the current conversation.
+- **Slash Commands** -- create shortcuts for common prompts with Handlebars templating.
+- **MCP Servers** -- connect external tools and data sources via Model Context Protocol. Stdio and HTTP transports supported.
+
+## The Details
+
+- **Lean system prompts** -- minimal, focused instructions and concise tool descriptions. Your tokens go toward actual work, not bloated framework overhead.
+- **Zero telemetry** -- no usage tracking, no analytics, no data collection.
+- **Context editing** -- automatically trims old tool call payloads and thinking blocks from your conversation history.
+- **Extended thinking** -- enable deeper reasoning for complex tasks with configurable budget limits.
+- **CLAUDE.md compatible** -- already have a CLAUDE.md in your repo? OmniContext CLI reads it automatically.
+- **Auto-compaction** -- when context hits 80% capacity, the conversation is compacted, key memories are extracted, and a fresh session picks up where you left off.
+- **Native prompt caching** -- automatic cache control for Anthropic and Gemini with custom TTL settings.
+- **Project instructions** -- drop an `OMX.md` in your repo root and everyone on the team gets the same conventions and context.
+
+## Build & Release
+
+```bash
+npm run release
+```
+
+One command builds the CLI, all clients, packages release zips, and builds the desktop app for the current platform. Artifacts go to `release/`.
+
+## Documentation
+
+**https://bluenoah1991.github.io/omni-context-cli-landing/docs/**
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,166 @@
+# OmniContext CLI
+
+**精准上下文，最小成本。**
+
+OmniContext CLI 是一个终端原生的编程助手，把上下文当作一等资源来管理。精简的系统提示词控制开销。专家委派机制把脏活路由给便宜的模型，同时保持主上下文的干净。零遥测意味着你的代码不会离开你的机器。它还能延伸到 VS Code、Office、浏览器、Figma、Obsidian 和 Zed。
+
+```bash
+npm install -g omni-context-cli && omx
+```
+
+## 工作原理
+
+传统助手逐个调用基础工具，每一轮都重新发送完整上下文。OmniContext CLI 把多步操作委派给运行在便宜模型上的 Agentic 子代理——贵价模型专注推理，不做文件 I/O。
+
+**任务："找到 `handleAuth` 的定义"**
+
+传统模式：
+
+| 轮次 | 调用 | 结果 |
+|------|------|------|
+| R1 | `glob("src/**/*.ts")` | 返回 43 个文件 |
+| R2 | `grep("handleAuth", ...)` | 4 个文件中有 7 处匹配 |
+| R3 | `read("src/middleware/auth.ts")` | 186 行——找错文件了 |
+| R4 | `read("src/routes/login.ts")` | 124 行——还在找 |
+| R5 | `read("src/services/auth.ts", 40-90)` | 找到了——又多 50 行 |
+
+> 5 轮，新增 ~12K 上下文，全部在主模型上执行
+
+专家模式：
+
+| 轮次 | 调用 | 结果 |
+|------|------|------|
+| R1 | `pluck("handleAuth definition")` | 子代理（便宜模型）：glob -> grep -> read -> locate -> extract |
+
+> 1 轮，新增 ~1K 上下文，脏活在便宜模型上完成
+
+## Agentic 工具
+
+每个工具作为自主子代理运行在便宜模型上，内部处理文件 I/O、错误恢复和重试——中间输出不会进入你的主上下文，token 账单也不会膨胀。
+
+| 工具 | 用途 |
+|------|------|
+| **explore** | 勘察项目架构——目录布局、关键文件和代码组织方式 |
+| **spark** | 执行 shell 命令，自动检测错误并重试 |
+| **sculpt** | 精准编辑文件，定位正确位置，修改并验证结果 |
+| **weave** | 从头写入完整文件，自动验证 |
+| **sweep** | 按名称、内容或结构查找匹配的文件 |
+| **pluck** | 提取特定代码片段——函数、类或你需要的代码块 |
+| **ripple** | 追踪符号在代码库中的所有引用 |
+| **slice** | 只读取相关部分来回答针对性的代码问题 |
+| **quest** | 通过网络搜索调研主题 |
+| **glance** | 一次预览多个文件，附带简要摘要 |
+
+## 工作流预设
+
+一条命令切换 OmniContext CLI 的行为模式。每个预设改变可用工具、系统提示词和响应风格。
+
+| 预设 | 说明 |
+|------|------|
+| **Specialist**（默认） | 主模型负责推理，便宜的代理模型负责执行。更少轮次，更干净的上下文，更低的成本。 |
+| **Explorer** | 调研优先模式。先发起多次网络搜索再回答。适合时事、文档查阅和事实核查。 |
+| **Artist** | 视觉优先响应。在模型支持时优先生成图像。适合设计探索和原型。 |
+| **Assistant** | 应用集成的个人助理。通过自然语言控制浏览器标签页、Office 文档和 Figma 设计。 |
+| **Normal** | 基础工具加手动编排。直接使用 read、write、edit 和 bash。完全控制，没有抽象。 |
+
+## 原生多协议
+
+大多数工具把所有请求转换成单一 API 格式。OmniContext CLI 为每种协议提供专用的请求构建器和流处理器。提示词缓存、扩展思考和供应商专属特性按原厂设计工作——没有有损的转换层。
+
+| 协议 | 说明 |
+|------|------|
+| **Anthropic** | 原生 Messages API，支持提示词缓存、扩展思考和流式传输。通过自定义 TTL 实现 token 级缓存控制。 |
+| **OpenAI** | 原生 Chat Completions API。兼容任何 OpenAI 格式的接口。 |
+| **Gemini** | 原生 generateContent API，Gemini 专用流式传输。工具和函数调用使用 Gemini 自己的 schema。 |
+| **Responses API** | OpenAI 新一代 Responses API，内置工具编排。独立于 Chat Completions 的路径。 |
+
+## 成本优化
+
+每次 API 调用都会重新发送完整的对话历史。更少的轮次意味着更少的缓存读取。更干净的上下文意味着更少的 token 写入。专家模式两者兼省——并且把脏活卸载给便宜的模型。
+
+- **更少的 API 轮次** ——传统工具需要 5 轮才能找到一个函数定义，专家模式只要 1 轮。省掉 4 次完整上下文重传，每省一轮都节省缓存读取成本。
+- **更小的上下文增长** ——基础工具往对话里塞 ~10KB 中间输出，Agentic 工具只返回最终结果。上下文编辑自动裁剪旧的工具负载和思考块，长会话也能控制增长。
+- **便宜模型做执行** ——子代理运行在低成本模型上，主模型只负责规划和决策。贵价模型永远不做文件 I/O。
+- **1 小时缓存应对深度工作** ——默认 5 分钟提示词缓存在你暂停思考时就会过期。切换到 1 小时缓存适合调试、重构或调研——消除会话中反复重建缓存的开销。
+
+**模拟成本对比："找到 handleAuth 的定义"**
+
+| | 传统模式 | 专家模式 | 节省 |
+|---|---|---|---|
+| API 轮次 | 5 | 1 | -4 轮 |
+| 每轮缓存读取 | ~20K tokens x 5 | ~20K tokens x 1 | -80K tokens |
+| 新增上下文 | ~10KB | ~3KB | -70% |
+| 缓存写入（新 token） | ~2.5K tokens | ~1K tokens | -60% |
+| 执行模型 | 仅贵价模型 | 贵价 + 便宜 | 便宜 ~30% |
+
+*基于在 TypeScript 项目中查找函数的 20K token 对话。实际节省取决于项目规模和模型定价。*
+
+## 模型供应商
+
+一条命令添加所有模型。OmniContext CLI 内置供应商预设——选一个，粘贴 API key，该服务的所有模型就可以使用了。
+
+```bash
+# 列出可用供应商
+$ omx --list-providers
+
+# 一次性添加供应商的所有模型
+$ omx --add-provider zenmux --api-key zmx-...
+
+# 移除同样简单
+$ omx --remove-provider zenmux
+```
+
+内置供应商：**Zenmux**、**DeepSeek**、**OpenRouter**、**Zhipu (GLM)**、**MiniMax**
+
+## 跨会话记忆
+
+OmniContext CLI 跨会话记住你的编码风格、项目模式和历史决策。关键要点从每次对话中提取并注入未来的会话。有用的要点加分（+1），有害的快速扣分（-3），不再使用的自然衰减。每个项目有自己的记忆文件——想要完全控制可以直接编辑。
+
+## 集成
+
+终端是大本营，但 OmniContext CLI 延伸到你使用的每个工具。一个 AI，一致的上下文，零切换成本。
+
+- **VS Code 扩展** ——完整的 IDE 集成，感知打开文件、诊断信息和 diff 视图
+- **桌面应用** ——独立 GUI，作为本地中枢连接 Office、浏览器和 Figma 扩展
+- **Chrome 扩展** ——任意网页上的侧边栏，支持摘要、数据提取和浏览器自动化
+- **Office 插件** ——Word、Excel 和 PowerPoint 内的 AI 面板
+- **Figma 插件** ——通过聊天面板检查布局、创建图形、修改节点和导出资源
+- **Zed 编辑器** ——通过 Agent Client Protocol 作为外部代理接入，拥有完整工具访问
+- **Web 客户端** ——浏览器 UI，支持 LaTeX、Mermaid 图表、文件附件和拖拽
+- **移动端访问** ——运行 `omx --serve` 后从手机连接
+
+## 可扩展性
+
+自定义 Agent、技能、斜杠命令和 MCP 服务器。一切都是 Markdown 文件或 JSON 配置。
+
+- **自定义子代理** ——写一个带提示词模板和工具权限的 Markdown 文件，它立刻成为新的 Agentic 工具。添加 `OMX-AGENTS.md` 作为全局代理指令。
+- **自定义技能** ——教 OmniContext CLI 领域知识和工作流。技能会注入当前对话。
+- **斜杠命令** ——为常用提示词创建快捷方式，支持 Handlebars 模板。
+- **MCP 服务器** ——通过 Model Context Protocol 接入外部工具和数据源。支持 stdio 和 HTTP 传输。
+
+## 细节
+
+- **精简的系统提示词** ——最小化、聚焦的指令和简洁的工具描述。你的 token 用在实际工作上，而不是臃肿的框架开销。
+- **零遥测** ——没有使用追踪，没有数据分析，没有数据收集。
+- **上下文编辑** ——自动裁剪对话历史中旧的工具调用负载和思考块。
+- **扩展思考** ——为复杂任务启用深度推理，支持可配置的预算限制。
+- **兼容 CLAUDE.md** ——仓库里已经有 CLAUDE.md？OmniContext CLI 会自动读取。
+- **自动压缩** ——上下文达到 80% 容量时，对话被压缩，关键记忆被提取，新会话无缝接续。
+- **原生提示词缓存** ——Anthropic 和 Gemini 的自动缓存控制，支持自定义 TTL 设置。
+- **项目指令** ——在仓库根目录放一个 `OMX.md`，团队里每个人都能得到相同的约定和上下文。
+
+## 构建与发布
+
+```bash
+npm run release
+```
+
+一条命令构建 CLI 和所有客户端，打包发布 zip，并为当前平台构建桌面应用。产物输出到 `release/`。
+
+## 文档
+
+**https://bluenoah1991.github.io/omni-context-cli-landing/docs/zh-Hans/**
+
+## 许可证
+
+MIT