@pmndre/pine 0.0.0-stage → 0.22.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (151) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +226 -2
  3. package/bin/pine.js +27 -0
  4. package/docs/SKILL.md +234 -0
  5. package/docs/references/agents.md +454 -0
  6. package/docs/references/coding.md +311 -0
  7. package/docs/references/computer.md +212 -0
  8. package/docs/references/configuration.md +310 -0
  9. package/docs/references/events.md +267 -0
  10. package/docs/references/mcp.md +420 -0
  11. package/docs/references/operations.md +394 -0
  12. package/docs/references/overview.md +195 -0
  13. package/docs/references/security.md +896 -0
  14. package/docs/references/setup.md +385 -0
  15. package/docs/references/sources.md +772 -0
  16. package/docs/references/stack.md +121 -0
  17. package/docs/references/tui.md +575 -0
  18. package/examples/home/.env.example +7 -0
  19. package/examples/home/USER.md +4 -0
  20. package/examples/home/agents/main/agent.json +4 -0
  21. package/examples/home/agents/main/workspace/AGENTS.md +14 -0
  22. package/examples/home/agents/main/workspace/MEMORY.md +4 -0
  23. package/examples/home/agents/main/workspace/SOUL.md +4 -0
  24. package/examples/home/models.json +62 -0
  25. package/examples/home/pine.json +34 -0
  26. package/examples/home/skills/README.txt +7 -0
  27. package/examples/launchd/com.pine.daemon.plist +32 -0
  28. package/examples/systemd/pine.service +22 -0
  29. package/mcp/browser.d.ts +99 -0
  30. package/mcp/browser.js +496 -0
  31. package/mcp/commands.d.ts +20 -0
  32. package/mcp/commands.js +88 -0
  33. package/mcp/computer.d.ts +139 -0
  34. package/mcp/computer.js +698 -0
  35. package/mcp/computer.swift +989 -0
  36. package/mcp/lib.d.ts +23 -0
  37. package/mcp/lib.js +52 -0
  38. package/mcp/web.d.ts +6 -0
  39. package/mcp/web.js +140 -0
  40. package/package.json +32 -4
  41. package/src/access.d.ts +112 -0
  42. package/src/access.js +438 -0
  43. package/src/actions.d.ts +75 -0
  44. package/src/actions.js +167 -0
  45. package/src/admin.d.ts +167 -0
  46. package/src/admin.js +625 -0
  47. package/src/agent-admin.d.ts +24 -0
  48. package/src/agent-admin.js +55 -0
  49. package/src/agents.d.ts +540 -0
  50. package/src/agents.js +2776 -0
  51. package/src/background.d.ts +29 -0
  52. package/src/background.js +100 -0
  53. package/src/cli.d.ts +2 -0
  54. package/src/cli.js +777 -0
  55. package/src/computer.d.ts +30 -0
  56. package/src/computer.js +32 -0
  57. package/src/config.d.ts +396 -0
  58. package/src/config.js +549 -0
  59. package/src/dev/claude-model.d.ts +37 -0
  60. package/src/dev/claude-model.js +204 -0
  61. package/src/env-file.d.ts +4 -0
  62. package/src/env-file.js +40 -0
  63. package/src/goals.d.ts +133 -0
  64. package/src/goals.js +316 -0
  65. package/src/http.d.ts +46 -0
  66. package/src/http.js +509 -0
  67. package/src/limiter.d.ts +32 -0
  68. package/src/limiter.js +84 -0
  69. package/src/login.d.ts +23 -0
  70. package/src/login.js +130 -0
  71. package/src/manual.d.ts +61 -0
  72. package/src/manual.js +443 -0
  73. package/src/mcp-config.d.ts +49 -0
  74. package/src/mcp-config.js +182 -0
  75. package/src/models.d.ts +90 -0
  76. package/src/models.js +274 -0
  77. package/src/net.d.ts +50 -0
  78. package/src/net.js +150 -0
  79. package/src/pine.d.ts +32 -0
  80. package/src/pine.js +134 -0
  81. package/src/programs.d.ts +123 -0
  82. package/src/programs.js +412 -0
  83. package/src/router.d.ts +56 -0
  84. package/src/router.js +164 -0
  85. package/src/sandbox-fs.d.ts +34 -0
  86. package/src/sandbox-fs.js +186 -0
  87. package/src/sandbox-linux.d.ts +96 -0
  88. package/src/sandbox-linux.js +297 -0
  89. package/src/sandbox-setup.d.ts +70 -0
  90. package/src/sandbox-setup.js +216 -0
  91. package/src/security.d.ts +238 -0
  92. package/src/security.js +660 -0
  93. package/src/skills.d.ts +67 -0
  94. package/src/skills.js +163 -0
  95. package/src/snapshots.d.ts +68 -0
  96. package/src/snapshots.js +306 -0
  97. package/src/source-types.d.ts +61 -0
  98. package/src/source-types.js +1 -0
  99. package/src/sources/command.d.ts +4 -0
  100. package/src/sources/command.js +77 -0
  101. package/src/sources/folder.d.ts +6 -0
  102. package/src/sources/folder.js +116 -0
  103. package/src/sources/ftp.d.ts +4 -0
  104. package/src/sources/ftp.js +307 -0
  105. package/src/sources/http.d.ts +4 -0
  106. package/src/sources/http.js +201 -0
  107. package/src/sources/mqtt.d.ts +18 -0
  108. package/src/sources/mqtt.js +97 -0
  109. package/src/sources/telegram.d.ts +22 -0
  110. package/src/sources/telegram.js +283 -0
  111. package/src/sources/webhook.d.ts +4 -0
  112. package/src/sources/webhook.js +52 -0
  113. package/src/sources.d.ts +344 -0
  114. package/src/sources.js +966 -0
  115. package/src/store.d.ts +99 -0
  116. package/src/store.js +277 -0
  117. package/src/timers.d.ts +83 -0
  118. package/src/timers.js +318 -0
  119. package/src/tools.d.ts +11 -0
  120. package/src/tools.js +1297 -0
  121. package/src/tui/app.d.ts +305 -0
  122. package/src/tui/app.js +3195 -0
  123. package/src/tui/client.d.ts +236 -0
  124. package/src/tui/client.js +131 -0
  125. package/src/tui/code-pane.d.ts +68 -0
  126. package/src/tui/code-pane.js +535 -0
  127. package/src/tui/highlight.d.ts +8 -0
  128. package/src/tui/highlight.js +86 -0
  129. package/src/tui/picture.d.ts +206 -0
  130. package/src/tui/picture.js +801 -0
  131. package/src/tui/run.d.ts +8 -0
  132. package/src/tui/run.js +97 -0
  133. package/src/tui/theme.d.ts +32 -0
  134. package/src/tui/theme.js +128 -0
  135. package/src/tui/undo.d.ts +5 -0
  136. package/src/tui/undo.js +50 -0
  137. package/src/tui/voice.d.ts +49 -0
  138. package/src/tui/voice.js +155 -0
  139. package/src/tui/voice.swift +223 -0
  140. package/src/types.d.ts +139 -0
  141. package/src/types.js +1 -0
  142. package/src/undo.d.ts +224 -0
  143. package/src/undo.js +465 -0
  144. package/src/update.d.ts +35 -0
  145. package/src/update.js +130 -0
  146. package/src/util.d.ts +65 -0
  147. package/src/util.js +171 -0
  148. package/src/watching.d.ts +20 -0
  149. package/src/watching.js +68 -0
  150. package/src/workspace-view.d.ts +72 -0
  151. package/src/workspace-view.js +221 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Paul Henschel
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,227 @@
1
- # Temporary Holding Version
1
+ <h1 align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="docs/images/logo-dark.svg">
4
+ <img src="docs/images/logo-light.svg" alt="pine" width="360">
5
+ </picture>
6
+ </h1>
2
7
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
8
+ ```bash
9
+ npm install -g @pmndre/pine
10
+ ```
11
+
12
+ ### PINE makes AI reactive
13
+
14
+ 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.
15
+
16
+ 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.
17
+
18
+ ### Some design choices
19
+
20
+ - **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"
21
+ - **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.
22
+ - **Self-discovery:** A built-in BM25 manual tool lets agents look up any API or internal detail on demand, without carrying docs in context.
23
+ - **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.
24
+ - **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).
25
+ - **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.
26
+
27
+ > [!IMPORTANT]
28
+ > pine runs on macOS and Linux; `pine init` sets up what it needs. Windows users can try [Docker](#docker). It remains open what exactly is necessary to make it run completely in Windows.
29
+
30
+ <br/>
31
+
32
+ <table>
33
+ <tr>
34
+ <td align="center" width="50%">
35
+ <br />
36
+ <img src="docs/images/meme.png" width="100%" alt="pine searches the web, downloads a picture and shows it in the terminal"><br/>
37
+ <sub>Support for images</sub>
38
+ </td>
39
+ <td align="center" width="50%">
40
+ <br />
41
+ <img src="docs/images/video.gif" width="100%" alt="pine fetches a video from the web and plays it in the terminal"><br/>
42
+ <sub>Support for videos</sub>
43
+ </td>
44
+ </tr>
45
+ <tr>
46
+ <td align="center" width="50%">
47
+ <br />
48
+ <img src="docs/images/drop.png" width="100%" alt="A picture dropped into the terminal, shown as a thumbnail, and the agent's answer about it"><br/>
49
+ <sub>Drag and drop</sub>
50
+ </td>
51
+ <td align="center" width="50%">
52
+ <br />
53
+ <img src="docs/images/watch.png" width="100%" alt="Asked to watch a folder, the agent sets up an event source; a file changes, it wakes up and shows the git diff"><br/>
54
+ <sub>Event sources (file watchers, ...)</sub>
55
+ </td>
56
+ </tr>
57
+ <tr>
58
+ <td align="center" width="50%">
59
+ <br />
60
+ <img src="docs/images/tabs.png" width="100%" alt="Tabs for several agents and conversations, with the list of conversations: pinned ones stay, the others clean themselves up"><br/>
61
+ <sub>UI can be navigated by clicking</sub>
62
+ </td>
63
+ <td align="center" width="50%">
64
+ <br />
65
+ <img src="docs/images/flipper.png" width="100%" alt="pine drives a Flipper Zero through an MCP server"><br/>
66
+ <sub>Support for MCPs and skills</sub>
67
+ </td>
68
+ </tr>
69
+ <tr>
70
+ <td align="center" width="50%">
71
+ <br />
72
+ <img src="docs/images/code.png" width="100%" alt="The code pane beside a conversation: the git diff of a file the agent just changed"><br/>
73
+ <sub>Code assistance</sub>
74
+ </td>
75
+ <td align="center" width="50%">
76
+ <br />
77
+ <img src="docs/images/folder.png" width="100%" alt="pine started in a project folder: the agent inspects it, and the folder menu lists the folders a conversation can work in"><br/>
78
+ <sub>Current folders</sub>
79
+ </td>
80
+ </tr>
81
+ </table>
82
+
83
+ <br/>
84
+
85
+ ```
86
+ you: terminal UI · Telegram
87
+ │
88
+ ▼
89
+ wake it ┌───────────┐ it uses
90
+ events ───────────────► │ │ ◄───────── MCP servers
91
+ Telegram · MQTT · FTP │ │ ◄───────── skills
92
+ webhooks · folders │ agent │
93
+ web addresses │ │
94
+ commands · etc * │ │
95
+ schedules ────────────► │ │
96
+ repeating · once └─────┬─────┘
97
+ │ delegate ──► other agents
98
+ │ subagent ──► with distinct prompts, in parallel
99
+ ▼
100
+ answers · messages · actions
101
+
102
+ Events, schedules, MCPs and skills can be set up by asking:
103
+ for the current conversation, agent scope, or globally
104
+ (main agent only) for all agents.
105
+
106
+ * New event types that agents can subscribe to can be created easily.
107
+ ```
108
+
109
+ ## Quick start
110
+
111
+ Sets everything up: the browser the web tools drive, and your user folder (`~/.pine`). On Linux
112
+ also the sandbox that agents in `safe` mode work in; it shows what it would install and asks once.
113
+
114
+ ```bash
115
+ pine init
116
+ ```
117
+
118
+ Checks the setup: validates the configuration, lists each agent with its model, tools and MCP
119
+ servers, and prints security notes if something is open that should not be.
120
+
121
+ ```bash
122
+ pine check
123
+ ```
124
+
125
+ Opens the terminal UI. If no daemon is running, it starts one inside and stops it when you quit.
126
+
127
+ ```bash
128
+ pine
129
+ ```
130
+
131
+ Runs the daemon as a service, without the UI, so agents keep reacting to events with no terminal
132
+ open. `pine` then attaches to it. To have it start at login, see
133
+ [operations.md](docs/references/operations.md).
134
+
135
+ ```bash
136
+ pine start
137
+ ```
138
+
139
+ Connect your subscriptions, or local llm servers. Switch with `/model` in the UI:
140
+
141
+ ```bash
142
+ pine login opencode-go
143
+ ```
144
+
145
+ `pine login anthropic` and `pine login openai-codex` use a Claude or ChatGPT subscription. A
146
+ model server of your own (llama.cpp, vLLM, LM Studio) is added by its address, with
147
+ `pine model add studio http://127.0.0.1:8080`, or by asking the main agent. See
148
+ [operations.md](docs/references/operations.md) and [tui.md](docs/references/tui.md).
149
+
150
+ To work on a project, start it in that folder. The agent gets that folder for the
151
+ conversation, and `▤ code` (or `ctrl+g`) opens a pane with git changes and diffs, the files and
152
+ the output of its tool calls. `/undo` takes your last message back, with the files it changed
153
+ ([coding.md](docs/references/coding.md)):
154
+
155
+ ```bash
156
+ pine .
157
+ ```
158
+
159
+ To get a newer version later, with whatever it needs:
160
+
161
+ ```bash
162
+ pine update
163
+ ```
164
+
165
+ ## Docker
166
+
167
+ A container needs nothing special. It is the wall around pine, and the agents work inside it
168
+ without a sandbox of their own:
169
+
170
+ ```bash
171
+ docker run -it -v pine:/root/.pine node:24 bash
172
+ ```
173
+
174
+ `-v pine:/root/.pine` keeps pine's home (configuration, conversations) when the container is
175
+ replaced. Inside, it is the same as anywhere:
176
+
177
+ ```bash
178
+ npm install -g @pmndre/pine
179
+ ```
180
+
181
+ ```bash
182
+ pine init
183
+ ```
184
+
185
+ Every agent whose mode you did not choose then works in `auto` mode, and `pine check` says so.
186
+ The agents and pine's own secrets are in the same container; what keeps the two apart there is
187
+ described under "pine's own files without a sandbox" in
188
+ [docs/references/security.md](docs/references/security.md).
189
+
190
+ `safe` mode puts an agent into a sandbox of its own, as on a Mac. A container may only make
191
+ one when it is started with the rights for it, which take away most of what Docker itself
192
+ protects:
193
+
194
+ ```bash
195
+ 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
196
+ ```
197
+
198
+ | Part | What it is for |
199
+ | --- | --- |
200
+ | `--cap-add SYS_ADMIN` | lets the sandbox create its namespaces |
201
+ | `--cap-add NET_ADMIN` | lets a sandbox without network have its own loopback interface |
202
+ | `--security-opt seccomp=unconfined` | Docker's system call filter forbids the sandbox's change of root |
203
+ | `--security-opt apparmor=unconfined` | Docker's AppArmor profile forbids its mounts |
204
+
205
+ `pine init` installs what the image lacks (bubblewrap, the browser's system libraries) and says
206
+ so if a right is missing. With pine as an ordinary user in the container instead of root, add
207
+ `--security-opt systempaths=unconfined`. `--privileged` works in place of all of them.
208
+
209
+ ## Documentation
210
+
211
+ Start at [docs/SKILL.md](docs/SKILL.md); it indexes everything.
212
+
213
+ | To do this | Read |
214
+ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
215
+ | Understand how the pieces fit | [overview.md](docs/references/overview.md) |
216
+ | Use the terminal UI | [tui.md](docs/references/tui.md) |
217
+ | Work on a project: `pine .`, the code pane with git changes, files and tool output, `/undo` | [coding.md](docs/references/coding.md) |
218
+ | Install, run, use the CLI, run it as a service | [operations.md](docs/references/operations.md) |
219
+ | Write `pine.json` and `agent.json` | [configuration.md](docs/references/configuration.md) |
220
+ | Let agents set things up by tool call instead of editing files | [setup.md](docs/references/setup.md) |
221
+ | Set up agents, delegation and sub-agents | [agents.md](docs/references/agents.md) |
222
+ | Route events, schedules, model calls | [events.md](docs/references/events.md) |
223
+ | Event sources: Telegram, folders, MQTT, web addresses, commands, webhooks, FTP | [sources.md](docs/references/sources.md) |
224
+ | MCP servers, web search, command tools | [mcp.md](docs/references/mcp.md) |
225
+ | Let an agent operate the apps on your Mac | [computer.md](docs/references/computer.md) |
226
+ | Know what is protected and what is not | [security.md](docs/references/security.md) |
227
+ | Work on pine itself | [AGENTS.md](AGENTS.md), [stack.md](docs/references/stack.md) |
package/bin/pine.js ADDED
@@ -0,0 +1,27 @@
1
+ #!/usr/bin/env node
2
+ // pine's launcher. From a checkout it runs the TypeScript sources as they are; from an installed
3
+ // package it runs the compiled ones (Node does not run TypeScript from inside node_modules).
4
+ import { spawnSync } from "node:child_process";
5
+ import fs from "node:fs";
6
+ import path from "node:path";
7
+ import { fileURLToPath, pathToFileURL } from "node:url";
8
+
9
+ if (Number(process.versions.node.split(".")[0]) < 24) {
10
+ console.error(`pine needs Node 24 or newer (this is ${process.versions.node}): https://nodejs.org`);
11
+ process.exit(1);
12
+ }
13
+ // The real place of this file, also when it was started through the link npm puts on the PATH.
14
+ const root = path.resolve(path.dirname(fs.realpathSync(fileURLToPath(import.meta.url))), "..");
15
+ const source = path.join(root, "src", "cli.ts");
16
+ if (fs.existsSync(source)) {
17
+ // A fresh checkout: fetch what pine is built on, once, so that the first command just works.
18
+ if (!fs.existsSync(path.join(root, "node_modules", "@earendil-works", "pi-coding-agent"))) {
19
+ console.error("pine: installing its dependencies (once) ...");
20
+ const done = spawnSync("npm", ["install", "--no-audit", "--no-fund"], { cwd: root, stdio: ["ignore", 2, 2] });
21
+ if (done.status !== 0) {
22
+ console.error(`pine: npm install failed; run it in ${root} to see why`);
23
+ process.exit(1);
24
+ }
25
+ }
26
+ await import(pathToFileURL(source).href);
27
+ } else await import(pathToFileURL(path.join(root, "src", "cli.js")).href);
package/docs/SKILL.md ADDED
@@ -0,0 +1,234 @@
1
+ ---
2
+ name: pine
3
+ description: Run, configure and extend pine, the event-driven multi-agent daemon built on the pi coding agent SDK. Use when setting up agents and their workspaces, subscribing agents to event sources (Telegram, folders, MQTT, webhooks, FTP uploads, web addresses, commands), scheduling what happens at a time, adding MCP servers and skills, routing events to agents, reaching agents on Telegram, delegating between agents, reviewing what is protected against prompt injection, or changing pine's code.
4
+ ---
5
+
6
+ # pine
7
+
8
+ pine (PI neural engine) is one process that hosts several pi agent sessions and an event log.
9
+ Event sources and schedules turn the outside world and the clock into events; subscriptions,
10
+ schedules and routes turn events into work; agents answer, act, hand tasks to each other, and
11
+ publish events of their own.
12
+
13
+ Three things to know before anything else:
14
+
15
+ 1. **Configuration lives in a home directory**, by default `~/.pine`: `pine.json` (global),
16
+ `models.json` (pi's model file), `.env` (secrets), and one folder per agent under `agents/`.
17
+ 2. **An agent is a folder**: `agents/<id>/agent.json` and a workspace. In the workspace lie the
18
+ files the agent keeps itself and that are read into its prompt: `AGENTS.md` (its purpose),
19
+ `SOUL.md` (who it is), `MEMORY.md` (its memory). `USER.md` in the home is what all agents
20
+ know about you. The workspace is wherever `workspace` points, for example a repository.
21
+ 3. **Where content came from decides what it may do.** Your own messages get the agent's full
22
+ tool set. Anything else is data. An event from outside runs with a reduced tool set in a
23
+ separate session; an event from a source a conversation subscribed to arrives in that
24
+ conversation, framed as data, and marks it as having read outside content (unless the source
25
+ is marked as yours). Either way nothing is sent out without your approval.
26
+
27
+ ## If you are an agent running inside pine
28
+
29
+ You search this manual with your `manual` tool: a search names the parts that fit with the
30
+ line that matched, and you then read the one or two parts you need. Search before you answer a
31
+ question about pine or say that something is not possible.
32
+
33
+ pine's configuration lives in its home folder (`~/.pine` unless your owner chose another),
34
+ which is closed to you on purpose: you never write those files. Four things you set up by
35
+ calling a tool, for the conversation you are in or for yourself as an agent
36
+ ([references/setup.md](references/setup.md)): event sources and subscriptions, schedules,
37
+ MCP servers, and skills. The main agent administers pine, and the rest is its job, also by
38
+ tool call ([references/setup.md](references/setup.md), "The main agent administers pine"):
39
+ creating, changing and deleting one of the others with its folder, pine's settings, routes, and
40
+ anything that is for everyone or for somebody else. If that is you, use those tools and never
41
+ send your owner to the files; if not, send your owner to it.
42
+ For what has no tool (the control API, a secret):
43
+
44
+ 1. Search the manual for it and read the part.
45
+ 2. Tell your owner what to put where: usually a few lines of JSON in `pine.json` (for everyone)
46
+ or `agents/<your id>/agent.json` (for you), then `pine check`, then a restart of the daemon
47
+ (quitting and reopening the terminal UI restarts an embedded one).
48
+ 3. Do not try to edit those files or work around the restriction. Say plainly that this is a
49
+ step for them.
50
+
51
+ One thing you can start yourself: when your owner asks you to install or connect an MCP
52
+ server, call `add_mcp_server` with a short name and either its https URL (a remote server) or,
53
+ for a local server, the line that starts it (`command`, for example
54
+ `npx -y @example/mcp@latest`, taken from the server's own documentation). Do not send your
55
+ owner to a terminal for this: adding it is your job, and they confirm it in a dialog. Leave
56
+ the scope out: the server is then for the conversation you are in (in your main conversation:
57
+ for you as an agent). Pass `scope: "agent"` only if they said it is for you in general, and, as
58
+ the main agent, `scope: "global"` only if they said "for all agents". They get a dialog and
59
+ confirm it. `remove_mcp_server` takes one out again. Do not probe the URL first; an
60
+ "unauthorized" answer only means the server wants a sign-in, which your owner does afterwards
61
+ with `/mcp login <name>` in the terminal UI or `pine mcp login <name>` in a shell. Tell them
62
+ that. You do not have a new server's tools in the turn in which you added it: end that turn,
63
+ and pine calls you again at once in the same conversation, with the tools in your list. Never
64
+ tell your owner to start a new chat for it. A local server runs where your commands run (in your
65
+ sandbox, or without one when you work in auto mode), with your home folder. If it needs a sign-in, its
66
+ documentation says how (often the same line with `login` at the end): run that with bash, give
67
+ your owner the link it prints, and wait until they are done.
68
+
69
+ Another: when your owner asks you to watch something or to react when something happens, call
70
+ your `sources` tool: it lists what you can subscribe to and what you are subscribed to (use it
71
+ too when your owner asks what you are watching). If one fits, subscribe to it with a note that
72
+ says what you are to do; whoever is subscribed is woken with that note whenever it reports
73
+ something. A subscription is for the conversation it is asked for in: that one is woken, and the
74
+ subscription goes when the conversation is closed, reset or removed. So leave the scope out.
75
+ Only when your owner says in so many words that it is for more do you pass one: agent (your
76
+ main conversation is woken instead, and it stays) or, if you are the main agent, global (all
77
+ agents); your owner is then asked to confirm. Do not pick a wider scope yourself; if you think
78
+ they want one, ask. You can end anything your own agent is subscribed to from any of its
79
+ conversations (`unsubscribe` with scope `agent` or `all`). If none fits,
80
+ set one up with `add_source` (a folder to watch, a web address or a command that is looked at
81
+ again and again, an MQTT device, a webhook, an FTP drop, Telegram); your owner confirms it where
82
+ that is needed. A password or token is never yours to handle: leave it out, and pine asks your
83
+ owner for it in a dialog. `remove_source` deletes one for good. Through a source that can send
84
+ (Telegram, MQTT) you reach out with `send`. Do not go looking in pine's home folder for what is
85
+ configured: `sources` tells you.
86
+
87
+ When your owner wants something done at a time ("every morning at seven", "remind me at five",
88
+ "in twenty minutes"), that is a schedule, not a source: call `add_schedule` with a name, the
89
+ task in your own words, and one of `cron`, `every`, `at` or `in`. When it is time you are woken
90
+ with the task. `schedules` lists what is scheduled, `remove_schedule` ends one.
91
+
92
+ When your owner wants you to remember how something is done ("make a skill for this"), call
93
+ `add_skill` with a name, a line on when to use it, and the steps. It is listed among your
94
+ skills from your next message on; `remove_skill` deletes it. A fact rather than a procedure
95
+ belongs into your `MEMORY.md` instead. In a conversation that has read outside content, a
96
+ skill is put to your owner first, with its instructions: write what you did and learned, not
97
+ orders.
98
+
99
+ When your owner asks for something in an app on their Mac that is neither a web page nor a
100
+ command (a note in Notes, a setting, a document in TextEdit, trying out an app they built), and
101
+ you have the tools whose names start with `mcp__computer__`, use them: `apps` lists what runs,
102
+ `app_open` opens an app, `app_snapshot` reads a window as text with a reference on every
103
+ control, `app_press` and `app_set_text` use a reference, `app_type` and `app_key` use the
104
+ keyboard. If you can see pictures, `app_screenshot`, `app_click`, `app_drag` and `app_scroll`
105
+ work by position in a picture. Your owner is asked once per app. If you do not have these
106
+ tools, you cannot get them by asking: say so ([references/computer.md](references/computer.md)
107
+ says who has them).
108
+
109
+ When a call comes back "not approved", it was put to your owner, and your owner said no. Do
110
+ not try another way to the same end: say what you wanted to do and why.
111
+
112
+ Schedules, skills, sources and servers follow the same rule: leave the scope out and it is for
113
+ the conversation you are in. What you have of each, you see with a tool, never in pine's files:
114
+ `sources`, `schedules`, `mcp_servers` and `skills` list what this conversation has, whom each
115
+ is for, and what only another conversation of yours has.
116
+
117
+ When you cannot go on without your owner's decision (which of two ways, which file), ask with
118
+ your `question` tool, with two to five short answers to pick from. For work with several steps,
119
+ keep a list with your `todo` tool; your owner sees it. A command that takes long or keeps
120
+ running (a server, a build, a watcher) you start with `background: true` on the shell tool, and
121
+ `stop_program` ends it ([references/coding.md](references/coding.md), "Commands in the
122
+ background"). When your owner wants you to work on until something is reached, tell them to
123
+ type `/goal` with what they want reached: only they can set a goal
124
+ ([references/agents.md](references/agents.md), "Goal mode"). In plan mode you only look and
125
+ answer with a plan; your owner switches the mode when it is to be carried out.
126
+
127
+ If you are the main agent and your owner asks for a new agent, call `create_agent` with an id,
128
+ one line on what it is for, and its instructions written to the agent itself ("You are ..."):
129
+ its job, what it should and should not do, how it reports. Your owner confirms it, and the agent
130
+ exists at once. For a device or service that no existing type of source can watch, the main
131
+ agent can also write a new source type and register it with `add_source_type`
132
+ ([references/sources.md](references/sources.md)); try the existing types first. A model server
133
+ of your owner's own (llama.cpp, vLLM, LM Studio) is the main agent's to add as well, with
134
+ `add_model_server` and the server's address; never ask for its key, pine asks your owner
135
+ ([references/setup.md](references/setup.md), "Adding a model server").
136
+
137
+ Things you can do yourself: work in your workspace, keep notes there, use the tools you have,
138
+ hand work to the agents listed in your prompt, and write shared state under your own keys.
139
+
140
+ ## Which file to read
141
+
142
+ | You want to | Read |
143
+ |---|---|
144
+ | See what an agent is given (events, schedules, MCP servers, skills) and how events, tasks and sessions fit together | [references/overview.md](references/overview.md) |
145
+ | Chat with agents in the terminal: tabs, slash commands (`/goal`, `/compact`, `/copy`, `/export`, `/undo`), keys, the five modes (auto, safe, manual, bypass, plan), approvals, an agent's questions and its list of steps, what a model thinks, pictures, switching models | [references/tui.md](references/tui.md) |
146
+ | Work on a project: `pine .`, a folder for a conversation, the code pane with git changes, files and tool output, what an agent left running, what it runs in the background, and taking a message back with `/undo` and `/redo` | [references/coding.md](references/coding.md) |
147
+ | Install it, start it, update it, use the CLI (every `pine` command), the control API for scripts, run it at login or in a container, find out why something did not happen | [references/operations.md](references/operations.md) |
148
+ | Look up a key in `pine.json`, `agent.json`, `models.json` or `.env` | [references/configuration.md](references/configuration.md) |
149
+ | Know what agents can set up by tool call, for whom, and what you are asked: event sources, MCP servers, skills, schedules, new agents, new source types, model servers; how an agent lists what it has; the table of pine's own tools (`question`, `todo`, `stop_program` and the rest) | [references/setup.md](references/setup.md) |
150
+ | Add an agent, give it a workspace, tools and a persona; skills; how agents look pine up (the `manual` tool); delegation, sub-agents, sessions, goal mode (`/goal`: working until an objective is met), shared state | [references/agents.md](references/agents.md) |
151
+ | Let an agent react to the outside world and reach out: Telegram, a watched folder, MQTT devices, a web address or a command that is looked at again and again, webhooks, FTP uploads from cameras; subscribing, unsubscribing, sending; a source type of your own | [references/sources.md](references/sources.md) |
152
+ | Have something done at a time (schedules); write rules for events yourself: set state, publish, single model calls, debounce | [references/events.md](references/events.md) |
153
+ | Add MCP servers globally, per agent or for one conversation; web search, page reading and the bundled browser (showing its window to log in yourself, local addresses); turn shell commands into tools | [references/mcp.md](references/mcp.md) |
154
+ | Operate the apps on a Mac: read a window, press, click, type; who may, what is asked, the grants macOS needs | [references/computer.md](references/computer.md) |
155
+ | Understand the defences against outside abuse and prompt injection, and their limits: the sandbox (macOS and Linux), what happens after outside content, the modes, approvals | [references/security.md](references/security.md) |
156
+ | Know the technology underneath and the pi behaviours pine works around; open points | [references/stack.md](references/stack.md) |
157
+ | Change pine's code | [../AGENTS.md](../AGENTS.md) |
158
+
159
+ ## The shortest working setup
160
+
161
+ ```bash
162
+ npm install -g @pmndre/pine
163
+ ```
164
+
165
+ ```bash
166
+ pine init
167
+ ```
168
+
169
+ ```bash
170
+ pine
171
+ ```
172
+
173
+ One agent, `main`, with web search and a browser, and the terminal UI to talk to it. Everything
174
+ below is added on top of that when you need it.
175
+
176
+ `~/.pine/pine.json`:
177
+
178
+ ```json
179
+ {
180
+ "main": "main",
181
+ "defaults": { "model": "dev/claude-haiku" }
182
+ }
183
+ ```
184
+
185
+ (An excerpt. `pine init` also writes the web, browser and app control servers and the limits;
186
+ put the model you use where `dev/claude-haiku` stands. `dev/claude-haiku` answers through
187
+ `claude -p` and needs Claude Code installed and signed in; for another model see "Choosing a
188
+ model" in [references/operations.md](references/operations.md).)
189
+
190
+ Telegram as a second way in is set up by asking the main agent: "watch Telegram". The dialog
191
+ you confirm has a field for the bot's token; then you write to the bot and type the six-digit
192
+ code it sends you into pine. See [references/sources.md](references/sources.md).
193
+
194
+ `~/.pine/agents/gonzo/agent.json`, a second agent, a specialist the main agent can hand work to.
195
+ Create the folder; the workspace here is `~/dev/gonzo`, which must exist, and an `AGENTS.md` in
196
+ it says what the agent is for (without `workspace`, pine makes `agents/gonzo/workspace` itself).
197
+ Or ask the main agent to create one: it calls `create_agent`, and no restart is needed.
198
+
199
+ ```json
200
+ {
201
+ "description": "Contract law; knows the case files",
202
+ "workspace": "~/dev/gonzo"
203
+ }
204
+ ```
205
+
206
+ ```bash
207
+ pine check
208
+ ```
209
+
210
+ ```bash
211
+ pine start
212
+ ```
213
+
214
+ `main` sees `gonzo` in its list of agents and can call `delegate`. `pine events -f` shows everything as it happens.
215
+
216
+ ## Vocabulary
217
+
218
+ | Term | Meaning |
219
+ |---|---|
220
+ | event | One record in the log: topic, payload, source, trust, cause |
221
+ | topic | Slash-separated name, matched with `+` (one level) and `#` (the rest) |
222
+ | route | A rule in `pine.json` that reacts to topics |
223
+ | source | A named thing that reports events from outside: a folder, an MQTT broker, a web address, a command, a webhook, an FTP drop, a Telegram bot. It runs only while something is subscribed to it (or always, with `"start": "always"`) |
224
+ | schedule | Something done at a time: at set times, every so often, or once. With a task it wakes an agent to do it |
225
+ | goal | An objective you give a conversation with `/goal`: the agent is called again, round after round, until a judge says it is met |
226
+ | subscription | A conversation of an agent listens to a source: each event arrives there as a message and wakes the agent |
227
+ | task | One piece of work for one agent; has a status, a result and statistics |
228
+ | session | A conversation of one agent with history. The manual also says "conversation". Named ones are kept until removed (unused ones after `limits.conversationDays`); `new` is one-off |
229
+ | owner | You. Content is "owner" only when it entered through a channel that authenticated you |
230
+ | untrusted | Everything else: data that may contain instructions it has no right to give |
231
+ | tainted | A session that has seen outside content (a web page, an MCP result, an untrusted task) |
232
+ | approval | Your yes or no to one tool call, asked in the terminal UI and over Telegram, or answered with `pine approve` |
233
+ | mode | How much an agent does without asking: `auto` (the default), `plan` (it only looks and answers with a plan), `manual` (every action waits for your yes), `bypass` (nothing waits) |
234
+ | extension | A pi extension: pi's own plug-in format, usable in pine sessions |