pine README

The project's README from github.com/pmndre/pine. As one markdown file: 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)

Searching Database…

340 ·GitHub
What is this?PINE is a harness for AI agents that reacts to events, not only to chat messages. Agents subscribe to sources like watched folders, websites, FTP endpoints, webhooks or devices and act when something happens, and it still handles normal chat, coding and tasks.
Is it a library I import, or a tool I run?It is a ready-to-run tool: a terminal UI, a background daemon that keeps agents reacting with no window open, and a macOS desktop app that shows the same conversations in a window.
How do I get it running?Get the code and run pine init, which sets up the browser for the web tools and your ~/.pine folder (on Linux it also offers the sandbox for safe mode). Then pine check validates the config and pine opens the terminal UI. A separate command runs the daemon as a service; see operations.md.
Does it run on Windows?Not natively: it runs on macOS and Linux, and Windows users can try the Docker container. The README itself says it is still open what exactly is needed to run fully on Windows.
Is it only for developers?Not only: besides coding, chat and tasks, the README stresses hooking agents up to folders, webhooks and physical devices in the house, so it also suits people who like to automate their home, as long as they are comfortable in a terminal.
Could it keep reacting to events while I am away?Only while its machine stays on. The README describes the daemon running as a service without the UI, so agents keep reacting to events with no terminal open, but it says nothing about hosting it for a team.
Can I use a local model instead of a cloud one?Yes: add your own model server such as llama.cpp, vLLM or LM Studio by its address, then switch models with /model in the UI. The README does not say whether everything works fully offline.
Do I have to write config files by hand?No. You tell the main agent what you want, and it creates agents, MCP servers, event sources, skills and schedules through administrative tool calls instead of you editing files.
How do I make an agent react to new files?Tell the main agent what to watch, for example a scans folder, and it subscribes: each new file gets its summary and payment details extracted. An event source is just a TypeScript service with a schema.
What does it do out of the box?Computer use on macOS, web browsing, coding tools with diffs and git, undo, plan mode, and goals: /goal keeps an agent working until the goal is done. Agents can also delegate to parallel sub-agents.
Creator
pmndre
Size
24.8 MB
Stars
340
Age
8d
Commits · 90 Days