npm install -g @pmndrs/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

• Event-driven architecture: Agents subscribe to events and react. An event source is just a *.ts service with a schema. Tell the agent what you want and they subscribe: "Watch ~/documents/scans, for every new file: extract summaries and payment details, if present"
• No configs: Tell the main agent what you want. It configures PINE, creates agents, MCPs, event sources, skills and schedules through administrative tool calls, never touches user config, never messes it up or breaks it.
• Self-discovery: A built-in BM25 manual tool lets agents look up any API or internal detail on demand, without carrying docs in context.
• A CLI that feels like a desktop app: Tabs, buttons, scroll regions, inline images and video, and drag-and-drop with thumbnails. Works in Kitty-protocol terminals like Ghostty, with fallbacks for older ones.
• Built in: Computer use (macOS), web browsing, coding tools, diffs and git, undo, plan mode and goals (/goal keeps an agent working until it is done).
• Orchestration: Agents can delegate, create sub-agents in parallel. A pinned tab simply persists an agent and its task. Name it, give it instructions, chat with it or subscribe it to events.

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.

Support for images	Support for videos
Drag and drop	Event sources (file watchers, ...)
UI can be navigated by clicking	Support for MCPs and skills
Code assistance	Current folders

                  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 .

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 @pmndrs/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
Work on a project: pine ., the code pane with git changes, files and tool output, /undo	coding.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: Telegram, folders, MQTT, web addresses, commands, webhooks, FTP	sources.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