mac-code 是一个面向 Apple Silicon Mac 的本地 AI 编程智能体，以 CLI 形式运行，定位为 Claude Code 的替代方案。其核心思路是让本地大语言模型充当路由器：模型将每个提示分类为 search（搜索）、shell（Shell）或 chat（聊天），再分别路由到对应处理流程。搜索走 DuckDuckGo，Shell 生成命令并通过 subprocess 执行，聊天则直接流式输出。
主要能力
- LLM 路由：agent.py 负责意图分类，将任务分派到搜索、Shell 或聊天。
- 本地模型运行：支持 llama.cpp 与 MLX 两种后端，均在 127.0.0.1:8000 暴露 OpenAI 兼容 API。
- 工具集：DuckDuckGo 搜索、Shell 执行、文件读写。
- 模型选项：资料给出 35B MoE（IQ2_M 量化，约 10.6 GB，适配 16 GB 内存，约 30 tok/s）、9B（Q4_K_M，约 5.3 GB，64K 上下文）、以及通过自定义 MoE Expert Sniper 在 16 GB 上运行 35B 全 Q4（约 1.54 tok/s，仅用约 1.42 GB 内存）。
- MLX 后端特性：持久化 KV 缓存保存/加载、上下文压缩、Cloudflare R2 同步。
- 研究模式 Flash Streaming：面向超出内存的模型，包含 moe_expert_sniper.py（35B Q4，22 GB 模型，1.42 GB 内存）与 flash_stream_v2.py（32B dense，18.4 GB 模型，4.5 GB 内存），使用 F_NOCACHE 直接 I/O、pread 与 16KB 对齐。
安装与启动
前置依赖：brew install llama.cpp；pip3 install rich ddgs huggingface-hub mlx-lm --break-system-packages。随后克隆仓库 git clone https://github.com/walter-grace/mac-code 并进入目录。模型通过 huggingface_hub 下载到 ~/models。后端启动提供三种选项：llama.cpp + 35B MoE（推荐）、llama.cpp + 9B（64K 上下文）、MLX 后端（python3 mlx/mlx_engine.py）。之后运行 python3 agent.py 启动智能体。
使用方式
智能体 REPL 内输入 / 可查看命令，包括 /agent（带工具的默认模式）、/raw（直接流式、无工具）、/model 9b、/model 35b、/search <query>、/bench、/stats、/cost、/good、/bad、/improve、/clear、/quit。示例提示如“查找最近 7 天修改的所有 Python 文件”会路由到 shell 并生成 find 命令；“谁赢了 NBA 总决赛”会路由到 search；“解释注意力机制如何工作”会路由到 chat。
MLX 后端提供 REST API：/v1/context/save、/v1/context/load、/v1/context/download（需 R2 环境变量），以及标准 OpenAI 兼容的 /v1/chat/completions（支持流式）。KV 缓存压缩示例使用 mlx.turboquant.compress_kv_cache 与 mlx.kv_cache 的保存/加载函数，资料称可 4 倍压缩且相似度 99.3%（26.6 MB → 6.7 MB）。
适用场景与限制
适用于希望在 Apple Silicon Mac 上以本地模型完成编程辅助、命令生成、文件操作与网页搜索的用户，尤其是关注零月费与数据本地化的场景。资料给出按内存选择模型的指南：8 GB 选 9B Q4_K_M，16 GB 选 35B IQ2_M 或 Expert Sniper，48 GB 可选 35B Q4_K_M 原生，192 GB 可选 397B 前沿模型。限制方面：本地推理速度受硬件影响（如 Expert Sniper 仅约 1.54 tok/s）；ddgs 无需 API 密钥但可能限流；MLX 使用统一内存，可能遇到内存错误；F_NOCACHE 在 macOS Sonoma 及以上需验证是否生效。资料未提供收费、价格或商业授权信息。