pine README

项目的 README,来自 github.com/pmndre/pine。合并为一个 markdown 文件:README.md。

pine

pine in half a minute. pine start: it runs as a service. In the terminal, for a chat: a question about the weather is answered with a web search. Or in the desktop app, for code: an agent adds a function, runs the tests, and the diff is shown beside the conversation. Then a card: pine is built on an event bus, agents can react to any external stimuli. A colleague writes in Slack; in pine that is an event, and the agent that listens wakes, reads the message and says what it is about. At night a camera sees somebody with a covered face at the door; the clip is an event, the agent watches it and asks its owner on Telegram whether to ring the alarm. A letter goes through the scanner; the scan is an event, the agent reads the letter and puts what is due on a TODO list.

npm install -g @pmndre/pine

PINE makes AI reactive

Most harnesses just do input chat: "Do this do that". And maybe a scheduler: "Do it tomorrow". In PINE agents react to any stimuli. From watching folders, commands, websites, ftp endpoints, webhooks, to any other event source. You can hook them up and let them react to and operate your physical devices in the house, or digital assets.

PINE of course also handles regular chat, coding, tasks and orchestration. Agents carry memory and so on. All the basic stuff is in there, too.

Some design choices

[!IMPORTANT] pine runs on macOS and Linux; pine init sets up what it needs. Windows users can try Docker. It remains open what exactly is necessary to make it run completely in Windows.

                  you:  terminal UI · Telegram
                               │
                               ▼
 wake it                 ┌───────────┐            it uses
 events ───────────────► │           │ ◄───────── MCP servers
   Telegram · MQTT · FTP │           │ ◄───────── skills
   webhooks · folders    │   agent   │
   web addresses         │           │
   commands · etc *      │           │
 schedules ────────────► │           │
   repeating · once      └─────┬─────┘
                               │  delegate ──► other agents
                               │  subagent ──► with distinct prompts, in parallel
                               ▼
                 answers · messages · actions

 Events, schedules, MCPs and skills can be set up by asking:
 for the current conversation, agent scope, or globally
 (main agent only) for all agents.

 * New event types that agents can subscribe to can be created easily.

Quick start

Sets everything up: the browser the web tools drive, and your user folder (~/.pine). On Linux also the sandbox that agents in safe mode work in; it shows what it would install and asks once.

pine init

Checks the setup: validates the configuration, lists each agent with its model, tools and MCP servers, and prints security notes if something is open that should not be.

pine check

Opens the terminal UI. If no daemon is running, it starts one inside and stops it when you quit.

pine

Runs the daemon as a service, without the UI, so agents keep reacting to events with no terminal open. pine then attaches to it. To have it start at login, see operations.md.

pine start

Connect your subscriptions, or local llm servers. Switch with /model in the UI:

pine login opencode-go

pine login anthropic and pine login openai-codex use a Claude or ChatGPT subscription. A model server of your own (llama.cpp, vLLM, LM Studio) is added by its address, with pine model add studio http://127.0.0.1:8080, or by asking the main agent. See operations.md and tui.md.

To work on a project, start it in that folder. The agent gets that folder for the conversation, and ▤ code (or ctrl+g) opens a pane with git changes and diffs, the files and the output of its tool calls. /undo takes your last message back, with the files it changed (coding.md):

pine .

There is also a desktop app for macOS, with the same conversations in a window, an editor for a conversation's folder and a settings panel for agents, models, MCP servers, skills and events. It starts pine itself, or uses the one that runs (desktop.md). Each release has it as a disk image, for Apple silicon and for Intel. It carries pine and the Node it runs on, so nothing else has to be installed, and it gives your shell the pine command. From a checkout:

npm run desktop

To get a newer version later, with whatever it needs:

pine update

Docker

A container needs nothing special. It is the wall around pine, and the agents work inside it without a sandbox of their own:

docker run -it -v pine:/root/.pine node:24 bash

-v pine:/root/.pine keeps pine's home (configuration, conversations) when the container is replaced. Inside, it is the same as anywhere:

npm install -g @pmndre/pine
pine init

Every agent whose mode you did not choose then works in auto mode, and pine check says so. The agents and pine's own secrets are in the same container; what keeps the two apart there is described under "pine's own files without a sandbox" in docs/references/security.md.

safe mode puts an agent into a sandbox of its own, as on a Mac. A container may only make one when it is started with the rights for it, which take away most of what Docker itself protects:

docker run -it --cap-add SYS_ADMIN --cap-add NET_ADMIN --security-opt seccomp=unconfined --security-opt apparmor=unconfined -v pine:/root/.pine node:24 bash
Part What it is for
--cap-add SYS_ADMIN lets the sandbox create its namespaces
--cap-add NET_ADMIN lets a sandbox without network have its own loopback interface
--security-opt seccomp=unconfined Docker's system call filter forbids the sandbox's change of root
--security-opt apparmor=unconfined Docker's AppArmor profile forbids its mounts

pine init installs what the image lacks (bubblewrap, the browser's system libraries) and says so if a right is missing. With pine as an ordinary user in the container instead of root, add --security-opt systempaths=unconfined. --privileged works in place of all of them.

Documentation

Start at docs/SKILL.md; it indexes everything.

To do this Read
Understand how the pieces fit overview.md
Use the terminal UI tui.md
Use the desktop app (macOS): conversations, an editor, and a settings panel in one window desktop.md
Work on a project: pine ., the code pane with git changes, files and tool output, /undo coding.md
Let an agent make a web page you click in, as its user interface, and be woken by what you press interfaces.md
Install, run, use the CLI, run it as a service operations.md
Write pine.json and agent.json configuration.md
Let agents set things up by tool call instead of editing files setup.md
Set up agents, delegation and sub-agents; how tools are declared and what stays cached agents.md
Route events, schedules, model calls events.md
Event sources: setting one up, subscribing, sending, secrets, trust sources.md
Every source type: Telegram, folders, MQTT, web addresses, feeds, mail, Slack, cameras source-types.md
MCP servers, web search, command tools mcp.md
Let an agent operate the apps on your Mac computer.md
Know what is protected and what is not security.md
Work on pine itself AGENTS.md, stack.md

pine (pmndre/pine)

正在搜索数据库…

340 ·GitHub
这是什么?PINE 是一个 AI 智能体的运行框架,它对事件做出反应,而不只是对聊天消息做出反应。智能体可以订阅各种来源,例如被监视的文件夹、网站、FTP 端点、Webhook 或设备,并在事件发生时采取行动。它同样能处理普通聊天、编程和任务。
这是一个我可以导入的库,还是一个我可以运行的工具?它是一个可以直接运行的工具,包括终端界面、一个后台守护进程(即使没有打开窗口,也能让智能体持续响应事件),以及一个 macOS 桌面应用,可以在窗口中显示相同的对话。
我该如何让它运行起来?获取代码并运行 pine init,它会为网页工具设置浏览器,并创建你的 ~/.pine 文件夹(在 Linux 上还会提供安全模式的沙箱)。然后运行 pine check 来验证配置,再运行 pine 打开终端界面。守护进程需要通过单独的命令作为服务运行,详见 operations.md。
它能在 Windows 上运行吗?不能原生运行:它支持 macOS 和 Linux,Windows 用户可以尝试使用 Docker 容器。README 本身也说明,要在 Windows 上完整运行还需要哪些条件,目前尚不明确。
它只适合开发者吗?并不只适合开发者。除了编程、聊天和任务,README 还特别强调可以把智能体连接到文件夹、Webhook 和家中的实体设备,因此只要你能熟练使用终端,也很适合喜欢自动化家居的人。
我不在的时候,它还能继续响应事件吗?只有在它所在的机器保持开机时才可以。README 说明守护进程可以在没有界面的情况下作为服务运行,因此即使没有打开终端,智能体也能继续响应事件;但它没有提到如何为团队进行托管。
我能用本地模型代替云端模型吗?可以:通过地址添加你自己的模型服务器,例如 llama.cpp、vLLM 或 LM Studio,然后在界面中使用 /model 切换模型。README 没有说明是否所有功能都能完全离线使用。
我必须手动编写配置文件吗?不必。你只需告诉主智能体你的需求,它就会通过管理性的工具调用来创建智能体、MCP 服务器、事件来源、技能和计划任务,你无需自己编辑文件。
如何让智能体对新文件做出反应?告诉主智能体要监视什么,例如 scans 文件夹,它就会进行订阅:每个新文件都会被提取摘要和付款信息。事件来源就是一个带有 schema 的 TypeScript 服务。
开箱即用的功能有哪些?在 macOS 上可以使用电脑操作功能、网页浏览、带差异对比和 git 的编程工具、撤销、计划模式,以及目标功能:/goal 会让智能体持续工作,直到目标完成。智能体还可以把任务委派给并行的子智能体。
作者
pmndre
大小
24.8 MB
星标
340
时长
8天
提交 · 90 天