Helix (Jon J Levesque)

⬡ Helix

Siri本应如此。

*专为Mac打造。由克劳德提供动力。持久内存、系统控制、语音和自主任务——所有这些都在本地运行。都是你的。*

  ](https://nodejs.org)  

______________________________________________________________________

Helix不是聊天应用程序。这是一个将克劳德变成个人人工智能的框架 *做事* --打开应用程序，查看日历，记住会话之间的事情，在睡觉时运行计划任务，如果你想的话，还可以大声与你交谈。

你分叉它，配置它，并拥有它。 你的经纪人。你的规则。你的Mac。

______________________________________________________________________

它的作用

Helix通过安装将Claude直接连接到Mac的“插件”（称为MCP服务器）为Claude提供了四种新的超能力：

此外，还有三件事建立在这些之上：

• 语音 --大声跟克劳德说话。它倾听、回应并回应。所有这些都在你的Mac上运行——没有云，没有订阅，没有每字成本。
• 循环 --按计划运行的自动化任务，如晨间简报、内容起草，或任何你想让克劳德在没有你要求的情况下重复做的事情。
• 身份 A. CLAUDE.md 您可以在其中定义代理的姓名、个性和行为。它在每次会话中都会读到这一点——这是你的代理人如何知道自己是谁以及该做什么。

这不是什么

不是网络应用程序。不跨平台。不是托管服务。 Helix完全在您的Mac上运行。您可以通过终端（具体来说 claude 命令）。如果你从未打开过终端，这可能会有一个学习曲线——但下面的设置指南会引导你完成每一步。

______________________________________________________________________

为什么这不会让你的帐户被禁止

还有其他框架可以让你自动运行Claude，但其中一些框架的运行方式违反了Anthropic的规则（抓取API密钥，使用非官方访问方法等）。Helix的构建方式不同。

以下是Helix长期安全运行的原因：

• 它使用官方的克劳德应用程序，句号。 Helix的运行方式相同 claude 您每天在终端中使用的命令——只是自动化的。Anthropic明确记录并支持此用例。
• 没有其他AI服务。 每个请求都会通过您自己的Claude帐户。没有OpenAI，没有Gemini，没有第三方代理。一个模型，一个帐户，你的控制。
• 插件是扩展Claude的官方方式。 Anthropic专门为此目的构建了MCP（Helix使用的插件系统）。我们完全按照设计使用它。
• 没有任何东西离开你的Mac。 内存是磁盘上的一个文件。语音在您机器上安装的软件上运行。日志保留在本地。没有任何东西会进入你无法控制的服务器。

底线是： Helix可以无限期运行，而不会危及您的帐户，因为它建立在Anthropic明确支持的工具之上，而不是围绕这些工具。

一个注意事项： 框架是安全的。什么你 *用它实现自动化* 这是你的责任。如果你构建了一个发布到推特或Reddit的循环，请先检查这些平台的规则。

______________________________________________________________________

工作原理（简明英语）

以下是基本图片：

You ←→ Claude (in Terminal)
           │
           ├── helix-mac      → your Mac, your apps, your browser
           ├── helix-memory   → remembers things between sessions
           ├── helix-agents   → runs tasks on a schedule
           └── helix-telegram → your phone (optional)

当你打字时 claude 在终端中，Claude会自动加载所有四个插件。它读你的 CLAUDE.md 文件要知道它的名称和个性，然后就可以使用了。

预定循环 是单独的克劳德会话，在计时器上醒来（如“每30分钟”或“每天早上8点”），完成一项任务，然后重新入睡。他们将他们所做的事情记录到一个文件中，你可以稍后查看。

所有会话共享相同的内存 --所以你的手机（通过Telegram）、语音会话和短信会话都知道彼此发生了什么。

→ 完整的架构文档

______________________________________________________________________

设置

在你开始之前——你需要什么

1. 运行macOS 14或更高版本的Mac （索诺玛或更新版本-办理入住手续→ 关于这台Mac
2. 已安装克劳德代码 --这就是 claude 终端中的命令。得到它在 claude.ai/claude-code 如果你还没有。跑 claude --version 检查。
3. Node.js 20或更高版本 --这是运行Helix插件的引擎。如果你不确定，快跑 node --version 在终端。如果收到“找不到命令”，请安装它：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.zshrc
nvm install 20

______________________________________________________________________

第一步——下载Helix

打开终端并运行：

git clone https://github.com/JonJLevesque/Helix.git ~/Developer/Helix
cd ~/Developer/Helix
cp .env.example .env

这将Helix下载到一个名为的文件夹中 Developer/Helix 在主目录中创建一个名为 .env 从示例中。

______________________________________________________________________

第二步——填写配置

打开 .env 任何文本编辑器中的文件（TextEdit工作正常——只要确保它保存为纯文本，而不是富文本）。您需要填写三个值。以下是如何找到每一个：

PROJECT_ROOT --您刚刚下载的Helix文件夹的完整路径。在终端中运行此命令，然后复制结果：

echo $HOME/Developer/Helix

CLAUDE_BIN --在哪里 claude 命令存在于您的机器上。运行此命令，然后复制结果：

which claude

它看起来会像 /Users/yourname/.local/bin/claude

NODE_BIN --Node.js所在的地方。运行此命令，然后复制结果：

which node

它看起来会像 /Users/yourname/.nvm/versions/node/v20.0.0/bin/node

你完成了 .env 应该看起来像这样：

PROJECT_ROOT=/Users/janedoe/Developer/Helix
CLAUDE_BIN=/Users/janedoe/.local/bin/claude
NODE_BIN=/Users/janedoe/.nvm/versions/node/v20.15.0/bin/node

______________________________________________________________________

步骤3——安装和构建

运行这个命令——它将安装所有内容并编译所有4个插件：

bash scripts/setup.sh

这需要一分钟的时间。你会看到很多输出滚动——这很正常。当它完成时，你会看到 “安装完成。”

______________________________________________________________________

步骤4--确认插件已加载

运行：

claude mcp list

您应该看到列出的所有四个： helix-mac, helix-memory, helix-agents, helix-telegram。如果缺少，安装脚本还会打印手动修复的说明。

______________________________________________________________________

第五步——说出你的代理人的名字

打开 CLAUDE.md 在文本编辑器中。在顶部附近，找到这三个占位符，并用您想要的任何内容替换它们：

______________________________________________________________________

第六步——启动它

claude

就是这样。您的代理启动，加载所有4个插件，并准备就绪。试着让它记住一些东西，检查你的日历，或者打开一个应用程序。

Something not working?

“未找到helix mac”或类似 --奔跑 claude mcp list 看看装了什么。如果缺少服务器，请检查中的路径 .mcp.json 指向一个真实的文件。跑 ls mcp-servers/helix-mac/dist/ 以确认它是建造的。

插件在启动时崩溃 --直接运行它以查看错误消息：

node mcp-servers/helix-mac/dist/index.js

电报没有响应 --验证您的bot令牌是否有效：

curl https://api.telegram.org/bot/getMe

______________________________________________________________________

语音模式

语音模式允许您与您的代理人大声交谈。它会倾听、思考和回应——所有这些都在你的Mac上本地运行。没有云服务。不收每字费用。没人听。

它是如何工作的：

Your voice → Whisper (turns speech into text) → Claude (thinks) → Kokoro (speaks the response) → your speakers

当你开始一个会话时，你的代理会用语音问候你，并听6秒。回话，它将保持语音模式。改为键入，它会自动切换为文本。模式会自动切换——你不必做任何事情。

步骤1--安装Whisper（语音转文本）

Whisper是一款将您的声音转换为文本的软件。使用Python的包管理器安装它：

pip install faster-whisper-server
faster-whisper-server --port 2022 --model base.en

要确认它正在运行，请打开一个新的终端选项卡并运行：

curl http://localhost:2022/health

您应该看到： {"status":"ok"}

使用哪种模型： - tiny.en --下载约50MB，响应速度最快，准确性稍低 - base.en --~150MB下载，平衡良好（建议启动） - small.en --约450MB下载，最准确，稍慢

第二步——安装Kokoro（文本转语音）

Kokoro是将Claude的文本响应转换为语音音频的软件：

pip install kokoro-onnx
kokoro-server --port 8880

要确认它正在运行：

curl http://localhost:8880/health

您应该看到： {"status":"healthy"}

步骤3--将麦克风设置为音频输入

安装一个小工具，可以从命令行切换音频输入：

brew install switchaudio-osx

然后将麦克风设置为输入源（更换 "USB PnP Audio Device" 如果您的麦克风名称不同，请检查系统设置→ 声音→ 输入以查看确切名称）：

SwitchAudioSource -s "USB PnP Audio Device" -t input

第四步——测试一切

bash services/voice-health-check.sh

如果所有三项服务都显示✓ 你完了。如果有什么显示✗:

bash services/voice-auto-recover.sh

此脚本尝试重新启动任何未运行的程序。之后再次运行健康检查。

Voice cutting out or not detecting silence correctly?

编辑 ~/.voicemode/voicemode.env （如果它不存在，请创建它）：

VOICEMODE_VAD_AGGRESSIVENESS=3    # How strict silence detection is: 0 = permissive, 3 = strict
VOICEMODE_LISTEN_DURATION_MIN=2.0 # Minimum seconds to listen before cutting off
VOICEMODE_SAMPLE_RATE=32000       # Audio sample rate — must match your Whisper server

VAD_AGGRESSIVENESS=3 适用于有背景噪音（风扇、交流电、电脑嗡嗡声）的房间中的USB麦克风。如果它过早地打断了你，试试看 2.

登录时运行语音服务 所以在你开始Claude之前，它们已经准备好了：为Whisper和Kokoro创建launchd plist。看 config/com.helix.template-loop.plist 对于结构来说，这是相同的模式。

______________________________________________________________________

循环（自动任务）

循环是一个按照时间表自动运行的Claude任务，就像cron作业一样，但Claude是做这项工作的人。

它是如何用简单的英语工作的：

1. macOS在计时器上唤醒循环（每30分钟、每小时、每天一次——无论你设置什么）
2. 脚本读取当前状态（已完成的操作、排队的内容、当前时间）
3. 克劳德得到一个描述情况的提示，并选择了一个行动
4. 克劳德做这件事（写草稿、提取数据、检查东西、记录结果）
5. 状态文件已更新
6. 循环回到睡眠状态

关键规则： 每次运行一个动作。 循环的设计是为了专注和可靠，而不是一次完成所有事情。

循环能做什么？ Claude可以用你的工具做任何事情：起草内容、从API中提取数据、检查日历、写入文件、发送Telegram消息、调用web服务、记录结果。此仓库中的示例显示了一个内容营销循环，该循环研究主题并起草时事通讯。

构建自己的循环，从脚手架开始 services/template-loop/ --它把所有东西都连接好了，你只需填写你想让克劳德实际做的事情。

→ 带示例的完整循环指南

______________________________________________________________________

盒子里是什么

helix/
├── CLAUDE.md              ← Start here — your agent's name, personality, rules
├── .env.example           ← Config template with every variable explained
├── mcp-servers/
│   ├── helix-mac/         ← The plugin that controls your Mac and Chrome
│   ├── helix-memory/      ← The plugin that remembers things between sessions
│   ├── helix-agents/      ← The plugin that runs and schedules background tasks
│   └── helix-telegram/    ← The plugin that connects your phone via Telegram
├── services/
│   ├── voice-health-check.sh  ← Checks that voice services are running
│   ├── voice-auto-recover.sh  ← Restarts voice services if they crashed
│   ├── noise-gate/            ← Optional audio filtering (advanced)
│   └── template-loop/         ← Starter template for building your own loop
├── agents/
│   ├── schedules/         ← Example scheduled task scripts (morning brief, etc.)
│   └── messages/          ← Where loops leave notes for you or each other
├── config/
│   ├── safety.json        ← Commands Claude is blocked from running
│   ├── example-persona.md ← Template for writing your agent's personality
│   └── com.helix.template-loop.plist  ← Template for scheduling a loop via macOS
├── examples/
│   └── content-loop/      ← A real-world content marketing loop, fully anonymized
├── docs/
│   ├── ARCHITECTURE.md    ← How all the pieces fit together
│   ├── MCP-SERVERS.md     ← Full tool reference for each plugin
│   ├── VOICE-SETUP.md     ← Detailed voice setup guide
│   └── LOOPS-GUIDE.md     ← How to build and schedule your own loops
└── scripts/
    └── setup.sh           ← First-run installer — run this once

______________________________________________________________________

需求

你需要这些来运行Helix：

• 运行macOS 14（Sonoma）或更高版本的Mac-检查→ 关于本机
• 克劳德代码 --the claude CLI应用程序
• Node.js版本20或更高版本-运行 node --version 检查

这些是可选的——只安装你想要的：

• Python 3.11+——只需要语音（Whisper+Kokoro）
• 更快的耳语服务器 --语音模式的语音转文本
• kokoro onnx --语音模式的文本转语音
• Telegram帐户——只有当你想通过手机控制你的代理人时才需要

______________________________________________________________________

许可证

弹性许可证2.0（ELv2） --免费使用和修改。未经许可，不得作为托管服务出售或提供。