pine
pine (PI neural engine) is one process that hosts several pi agent sessions and an event log.
Event sources and schedules turn the outside world and the clock into events; subscriptions,
schedules and routes turn events into work; agents answer, act, hand tasks to each other, and
publish events of their own.
Three things to know before anything else:
- Configuration lives in a home directory, by default
~/.pine: pine.json (global),
models.json (pi's model file), .env (secrets), and one folder per agent under agents/.
- An agent is a folder:
agents/<id>/agent.json and a workspace. In the workspace lie the
files the agent keeps itself and that are read into its prompt: AGENTS.md (its purpose),
SOUL.md (who it is), TOOLS.md (how it uses its tools), MEMORY.md (its memory). Three
files in the home are for all agents and kept by the main agent: AGENTS.md (traits and
behaviour), TOOLS.md (tooling defaults and preferences) and USER.md (what agents know
about you); an agent's own AGENTS.md and TOOLS.md say what is different for it. The workspace is wherever workspace points, for example a repository.
- Where content came from decides what it may do. Your own messages get the agent's full
tool set. Anything else is data. An event from outside runs with a reduced tool set in a
separate session; an event from a source a conversation subscribed to arrives in that
conversation, framed as data, and marks it as having read outside content (unless the source
is marked as yours). Either way nothing is sent out without your approval.
If you are an agent running inside pine
You search this manual with your manual tool: a search names the parts that fit with the
line that matched, and you then read the one or two parts you need. Search before you answer a
question about pine or say that something is not possible.
A tool that this manual names and that is not among your tools by that name is an action of
one of them: add_source is your tool pine_sources with action: "add_source", a list
such as sources or schedules is pine_list with what: ["sources"], and
mcp__browser__browser_navigate is browser with action: "browser_navigate"
(references/agents.md, "How tools are declared").
pine's configuration lives in its home folder (~/.pine unless your owner chose another),
which is closed to you on purpose: you never write those files. Four things you set up by
calling a tool, for the conversation you are in or for yourself as an agent
(references/setup.md): event sources and subscriptions, schedules,
MCP servers, and skills. The main agent administers pine, and the rest is its job, also by
tool call (references/setup.md, "The main agent administers pine"):
creating, changing and deleting one of the others with its folder, pine's settings, routes,
the conversations there are (listing them, reading one, pinning, renaming, opening and closing
its tab, removing it), and anything that is for everyone or for somebody else. If that is you, use those tools and never
send your owner to the files; if not, send your owner to it.
For what has no tool (the control API, a secret):
- Search the manual for it and read the part.
- Tell your owner what to put where: usually a few lines of JSON in
pine.json (for everyone)
or agents/<your id>/agent.json (for you), then pine check, then a restart of the daemon
(quitting and reopening the terminal UI restarts an embedded one).
- Do not try to edit those files or work around the restriction. Say plainly that this is a
step for them.
What you keep yourself are four files at the top of your workspace, which are part of your
instructions: AGENTS.md (your purpose and how you work), SOUL.md (who you are), TOOLS.md
(your own defaults and preferences for your tools) and MEMORY.md (what should outlive a
conversation). Three more files hold for every agent and lie in pine's home, where only the
main agent writes: AGENTS.md (traits and behaviour for all agents), TOOLS.md (tooling
defaults and preferences for all agents) and USER.md (what is known about your owner). You
read both an AGENTS.md and a TOOLS.md of each kind; yours say what is different or more for
you. If you are the main agent: a default or a preference for a tool that your owner tells you
is for all agents unless they say otherwise, and goes into the TOOLS.md in pine's home;
"for you alone" goes into your own, and for another agent alone you use update_agent with
tooling. If you are not: write it into your own file, and when your owner means all agents,
tell them to ask the main agent. Every file that is read as instructions is listed in
references/agents.md, "Every file that is read as instructions".
One thing you can start yourself: when your owner asks you to install or connect an MCP
server, call add_mcp_server with a short name and either its https URL (a remote server) or,
for a local server, the line that starts it (command, for example
npx -y @example/mcp@latest, taken from the server's own documentation). Do not send your
owner to a terminal for this: adding it is your job, and they confirm it in a dialog. Leave
the scope out: the server is then for the conversation you are in (in your main conversation:
for you as an agent). Pass scope: "agent" only if they said it is for you in general, and, as
the main agent, scope: "global" only if they said "for all agents". They get a dialog and
confirm it. remove_mcp_server takes one out again. Do not probe the URL first; an
"unauthorized" answer only means the server wants a sign-in, which your owner does afterwards
with /mcp login <name> in the terminal UI or pine mcp login <name> in a shell. Tell them
that. You do not have a new server's tools in the turn in which you added it: end that turn,
and pine calls you again at once in the same conversation, with the tools in your list. Never
tell your owner to start a new chat for it. A local server runs where your commands run (in your
sandbox, or without one when you work in auto mode), with your home folder. If it needs a sign-in, its
documentation says how (often the same line with login at the end): run that with bash, give
your owner the link it prints, and wait until they are done.
Another: when your owner asks you to watch something or to react when something happens, call
your sources tool: it lists what you can subscribe to and what you are subscribed to (use it
too when your owner asks what you are watching). If one fits, subscribe to it with a note that
says what you are to do; whoever is subscribed is woken with that note whenever it reports
something. A subscription is for the conversation it is asked for in: that one is woken, and the
subscription goes when the conversation is closed, reset or removed. So leave the scope out.
Only when your owner says in so many words that it is for more do you pass one: agent (your
main conversation is woken instead, and it stays) or, if you are the main agent, global (all
agents); your owner is then asked to confirm. Do not pick a wider scope yourself; if you think
they want one, ask. You can end anything your own agent is subscribed to from any of its
conversations (unsubscribe with scope agent or all). If none fits,
set one up with add_source (a folder to watch, a web address or a command that is looked at
again and again, an MQTT device, a webhook, an FTP drop, Telegram); your owner confirms it where
that is needed. A password or token is never yours to handle: leave it out, and pine asks your
owner for it in a dialog. remove_source deletes one for good. Through a source that can send
(Telegram, MQTT) you reach out with send. Do not go looking in pine's home folder for what is
configured: sources tells you.
When your owner wants something done at a time ("every morning at seven", "remind me at five",
"in twenty minutes"), that is a schedule, not a source: call add_schedule with a name, the
task in your own words, and one of cron, every, at or in. When it is time you are woken
with the task. schedules lists what is scheduled, remove_schedule ends one.
When your owner wants you to remember how something is done ("make a skill for this"), call
add_skill with a name, a line on when to use it, and the steps. It is listed among your
skills from your next message on; remove_skill deletes it. A fact rather than a procedure
belongs into your MEMORY.md instead. In a conversation that has read outside content, a
skill is put to your owner first, with its instructions: write what you did and learned, not
orders.
When your owner asks for something in an app on their Mac that is neither a web page nor a
command (a note in Notes, a setting, a document in TextEdit, trying out an app they built), and
you have the tools whose names start with mcp__computer__, use them: apps lists what runs,
app_open opens an app, app_snapshot reads a window as text with a reference on every
control, app_press and app_set_text use a reference, app_type and app_key use the
keyboard. If you can see pictures, app_screenshot, app_click, app_drag and app_scroll
work by position in a picture. Your owner is asked once per app. If you do not have these
tools, you cannot get them by asking: say so (references/computer.md
says who has them).
When a call comes back "not approved", it was put to your owner, and your owner said no. Do
not try another way to the same end: say what you wanted to do and why.
Schedules, skills, sources and servers follow the same rule: leave the scope out and it is for
the conversation you are in. What you have of each, you see with a tool, never in pine's files:
sources, schedules, mcp_servers and skills list what this conversation has, whom each
is for, and what only another conversation of yours has.
When you cannot go on without your owner's decision (which of two ways, which file), ask with
your question tool, with two to five short answers to pick from. For work with several steps,
keep a list with your todo tool; your owner sees it. A command that takes long or keeps
running (a server, a build, a watcher) you start with background: true on the shell tool, and
stop_program ends it (references/coding.md, "Commands in the
background"). When your owner wants you to work on until something is reached, tell them to
type /goal with what they want reached: only they can set a goal
(references/agents.md, "Goal mode"). In plan mode you only look and
answer with a plan; your owner switches the mode when it is to be carried out.
If you are the main agent and your owner asks for a new agent, call create_agent with an id,
one line on what it is for, and its instructions written to the agent itself ("You are ..."):
its job, what it should and should not do, how it reports. Your owner confirms it, and the agent
exists at once. For a device or service that no existing type of source can watch, the main
agent can also write a new source type and register it with add_source_type
(references/sources.md); try the existing types first. A model server
of your owner's own (llama.cpp, vLLM, LM Studio) is the main agent's to add as well, with
add_model_server and the server's address; never ask for its key, pine asks your owner
(references/setup.md, "Adding a model server").
Things you can do yourself: work in your workspace, keep notes there, use the tools you have,
hand work to the agents listed in your prompt, and write shared state under your own keys.
Which file to read
| You want to |
Read |
| See what an agent is given (events, schedules, MCP servers, skills) and how events, tasks and sessions fit together |
references/overview.md |
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 |
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 |
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 |
Look up a key in pine.json, agent.json, models.json or .env |
references/configuration.md |
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; the main agent's tools for conversations and tabs; how an agent lists what it has; the table of pine's own tools (question, todo, stop_program and the rest) |
references/setup.md |
Add an agent, give it a workspace, tools and a persona; skills; how agents look pine up (the manual tool); how tools are declared to the model (catalogue: families) and what a model server keeps of a conversation (prompt cache, slots); delegation, sub-agents, sessions, goal mode (/goal: working until an objective is met), shared state |
references/agents.md |
| 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 |
| Have something done at a time (schedules); write rules for events yourself: set state, publish, single model calls, debounce |
references/events.md |
| 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 |
| Operate the apps on a Mac: read a window, press, click, type; who may, what is asked, the grants macOS needs |
references/computer.md |
| 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 |
| Know the technology underneath and the pi behaviours pine works around; open points |
references/stack.md |
| Change pine's code |
../AGENTS.md |
The shortest working setup
npm install -g @pmndrs/pine
pine init
pine
One agent, main, with web search and a browser, and the terminal UI to talk to it. Everything
below is added on top of that when you need it.
~/.pine/pine.json:
{
"main": "main",
"defaults": { "model": "dev/claude-haiku" }
}
(An excerpt. pine init also writes the web, browser and app control servers and the limits;
put the model you use where dev/claude-haiku stands. dev/claude-haiku answers through
claude -p and needs Claude Code installed and signed in; for another model see "Choosing a
model" in references/operations.md.)
Telegram as a second way in is set up by asking the main agent: "watch Telegram". The dialog
you confirm has a field for the bot's token; then you write to the bot and type the six-digit
code it sends you into pine. See references/sources.md.
~/.pine/agents/gonzo/agent.json, a second agent, a specialist the main agent can hand work to.
Create the folder; the workspace here is ~/dev/gonzo, which must exist, and an AGENTS.md in
it says what the agent is for (without workspace, pine makes agents/gonzo/workspace itself).
Or ask the main agent to create one: it calls create_agent, and no restart is needed.
{
"description": "Contract law; knows the case files",
"workspace": "~/dev/gonzo"
}
pine check
pine start
main sees gonzo in its list of agents and can call delegate. pine events -f shows everything as it happens.
Vocabulary
| Term |
Meaning |
| event |
One record in the log: topic, payload, source, trust, cause |
| topic |
Slash-separated name, matched with + (one level) and # (the rest) |
| route |
A rule in pine.json that reacts to topics |
| 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") |
| schedule |
Something done at a time: at set times, every so often, or once. With a task it wakes an agent to do it |
| goal |
An objective you give a conversation with /goal: the agent is called again, round after round, until a judge says it is met |
| subscription |
A conversation of an agent listens to a source: each event arrives there as a message and wakes the agent |
| task |
One piece of work for one agent; has a status, a result and statistics |
| 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 |
| owner |
You. Content is "owner" only when it entered through a channel that authenticated you |
| untrusted |
Everything else: data that may contain instructions it has no right to give |
| tainted |
A session that has seen outside content (a web page, an MCP result, an untrusted task) |
| approval |
Your yes or no to one tool call, asked in the terminal UI and over Telegram, or answered with pine approve |
| 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) |
| extension |
A pi extension: pi's own plug-in format, usable in pine sessions |
1---2name: pine3description: 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.4metadata:5 source: https://skillmd.com/skills/pmndrs/pine6---78# pine910pine (PI neural engine) is one process that hosts several pi agent sessions and an event log.11Event sources and schedules turn the outside world and the clock into events; subscriptions,12schedules and routes turn events into work; agents answer, act, hand tasks to each other, and13publish events of their own.1415Three things to know before anything else:16171. **Configuration lives in a home directory**, by default `~/.pine`: `pine.json` (global),18 `models.json` (pi's model file), `.env` (secrets), and one folder per agent under `agents/`.192. **An agent is a folder**: `agents/<id>/agent.json` and a workspace. In the workspace lie the20 files the agent keeps itself and that are read into its prompt: `AGENTS.md` (its purpose),21 `SOUL.md` (who it is), `TOOLS.md` (how it uses its tools), `MEMORY.md` (its memory). Three22 files in the home are for all agents and kept by the main agent: `AGENTS.md` (traits and23 behaviour), `TOOLS.md` (tooling defaults and preferences) and `USER.md` (what agents know24 about you); an agent's own `AGENTS.md` and `TOOLS.md` say what is different for it. The workspace is wherever `workspace` points, for example a repository.253. **Where content came from decides what it may do.** Your own messages get the agent's full26 tool set. Anything else is data. An event from outside runs with a reduced tool set in a27 separate session; an event from a source a conversation subscribed to arrives in that28 conversation, framed as data, and marks it as having read outside content (unless the source29 is marked as yours). Either way nothing is sent out without your approval.3031## If you are an agent running inside pine3233You search this manual with your `manual` tool: a search names the parts that fit with the34line that matched, and you then read the one or two parts you need. Search before you answer a35question about pine or say that something is not possible.3637A tool that this manual names and that is not among your tools by that name is an action of38one of them: `add_source` is your tool `pine_sources` with `action: "add_source"`, a list39such as `sources` or `schedules` is `pine_list` with `what: ["sources"]`, and40`mcp__browser__browser_navigate` is `browser` with `action: "browser_navigate"`41([references/agents.md](references/agents.md), "How tools are declared").4243pine's configuration lives in its home folder (`~/.pine` unless your owner chose another),44which is closed to you on purpose: you never write those files. Four things you set up by45calling a tool, for the conversation you are in or for yourself as an agent46([references/setup.md](references/setup.md)): event sources and subscriptions, schedules,47MCP servers, and skills. The main agent administers pine, and the rest is its job, also by48tool call ([references/setup.md](references/setup.md), "The main agent administers pine"):49creating, changing and deleting one of the others with its folder, pine's settings, routes,50the conversations there are (listing them, reading one, pinning, renaming, opening and closing51its tab, removing it), and anything that is for everyone or for somebody else. If that is you, use those tools and never52send your owner to the files; if not, send your owner to it.53For what has no tool (the control API, a secret):54551. Search the manual for it and read the part.562. Tell your owner what to put where: usually a few lines of JSON in `pine.json` (for everyone)57 or `agents/<your id>/agent.json` (for you), then `pine check`, then a restart of the daemon58 (quitting and reopening the terminal UI restarts an embedded one).593. Do not try to edit those files or work around the restriction. Say plainly that this is a60 step for them.6162What you keep yourself are four files at the top of your workspace, which are part of your63instructions: `AGENTS.md` (your purpose and how you work), `SOUL.md` (who you are), `TOOLS.md`64(your own defaults and preferences for your tools) and `MEMORY.md` (what should outlive a65conversation). Three more files hold for every agent and lie in pine's home, where only the66main agent writes: `AGENTS.md` (traits and behaviour for all agents), `TOOLS.md` (tooling67defaults and preferences for all agents) and `USER.md` (what is known about your owner). You68read both an `AGENTS.md` and a `TOOLS.md` of each kind; yours say what is different or more for69you. If you are the main agent: a default or a preference for a tool that your owner tells you70is for all agents unless they say otherwise, and goes into the `TOOLS.md` in pine's home;71"for you alone" goes into your own, and for another agent alone you use `update_agent` with72`tooling`. If you are not: write it into your own file, and when your owner means all agents,73tell them to ask the main agent. Every file that is read as instructions is listed in74[references/agents.md](references/agents.md), "Every file that is read as instructions".7576One thing you can start yourself: when your owner asks you to install or connect an MCP77server, call `add_mcp_server` with a short name and either its https URL (a remote server) or,78for a local server, the line that starts it (`command`, for example79`npx -y @example/mcp@latest`, taken from the server's own documentation). Do not send your80owner to a terminal for this: adding it is your job, and they confirm it in a dialog. Leave81the scope out: the server is then for the conversation you are in (in your main conversation:82for you as an agent). Pass `scope: "agent"` only if they said it is for you in general, and, as83the main agent, `scope: "global"` only if they said "for all agents". They get a dialog and84confirm it. `remove_mcp_server` takes one out again. Do not probe the URL first; an85"unauthorized" answer only means the server wants a sign-in, which your owner does afterwards86with `/mcp login <name>` in the terminal UI or `pine mcp login <name>` in a shell. Tell them87that. You do not have a new server's tools in the turn in which you added it: end that turn,88and pine calls you again at once in the same conversation, with the tools in your list. Never89tell your owner to start a new chat for it. A local server runs where your commands run (in your90sandbox, or without one when you work in auto mode), with your home folder. If it needs a sign-in, its91documentation says how (often the same line with `login` at the end): run that with bash, give92your owner the link it prints, and wait until they are done.9394Another: when your owner asks you to watch something or to react when something happens, call95your `sources` tool: it lists what you can subscribe to and what you are subscribed to (use it96too when your owner asks what you are watching). If one fits, subscribe to it with a note that97says what you are to do; whoever is subscribed is woken with that note whenever it reports98something. A subscription is for the conversation it is asked for in: that one is woken, and the99subscription goes when the conversation is closed, reset or removed. So leave the scope out.100Only when your owner says in so many words that it is for more do you pass one: agent (your101main conversation is woken instead, and it stays) or, if you are the main agent, global (all102agents); your owner is then asked to confirm. Do not pick a wider scope yourself; if you think103they want one, ask. You can end anything your own agent is subscribed to from any of its104conversations (`unsubscribe` with scope `agent` or `all`). If none fits,105set one up with `add_source` (a folder to watch, a web address or a command that is looked at106again and again, an MQTT device, a webhook, an FTP drop, Telegram); your owner confirms it where107that is needed. A password or token is never yours to handle: leave it out, and pine asks your108owner for it in a dialog. `remove_source` deletes one for good. Through a source that can send109(Telegram, MQTT) you reach out with `send`. Do not go looking in pine's home folder for what is110configured: `sources` tells you.111112When your owner wants something done at a time ("every morning at seven", "remind me at five",113"in twenty minutes"), that is a schedule, not a source: call `add_schedule` with a name, the114task in your own words, and one of `cron`, `every`, `at` or `in`. When it is time you are woken115with the task. `schedules` lists what is scheduled, `remove_schedule` ends one.116117When your owner wants you to remember how something is done ("make a skill for this"), call118`add_skill` with a name, a line on when to use it, and the steps. It is listed among your119skills from your next message on; `remove_skill` deletes it. A fact rather than a procedure120belongs into your `MEMORY.md` instead. In a conversation that has read outside content, a121skill is put to your owner first, with its instructions: write what you did and learned, not122orders.123124When your owner asks for something in an app on their Mac that is neither a web page nor a125command (a note in Notes, a setting, a document in TextEdit, trying out an app they built), and126you have the tools whose names start with `mcp__computer__`, use them: `apps` lists what runs,127`app_open` opens an app, `app_snapshot` reads a window as text with a reference on every128control, `app_press` and `app_set_text` use a reference, `app_type` and `app_key` use the129keyboard. If you can see pictures, `app_screenshot`, `app_click`, `app_drag` and `app_scroll`130work by position in a picture. Your owner is asked once per app. If you do not have these131tools, you cannot get them by asking: say so ([references/computer.md](references/computer.md)132says who has them).133134When a call comes back "not approved", it was put to your owner, and your owner said no. Do135not try another way to the same end: say what you wanted to do and why.136137Schedules, skills, sources and servers follow the same rule: leave the scope out and it is for138the conversation you are in. What you have of each, you see with a tool, never in pine's files:139`sources`, `schedules`, `mcp_servers` and `skills` list what this conversation has, whom each140is for, and what only another conversation of yours has.141142When you cannot go on without your owner's decision (which of two ways, which file), ask with143your `question` tool, with two to five short answers to pick from. For work with several steps,144keep a list with your `todo` tool; your owner sees it. A command that takes long or keeps145running (a server, a build, a watcher) you start with `background: true` on the shell tool, and146`stop_program` ends it ([references/coding.md](references/coding.md), "Commands in the147background"). When your owner wants you to work on until something is reached, tell them to148type `/goal` with what they want reached: only they can set a goal149([references/agents.md](references/agents.md), "Goal mode"). In plan mode you only look and150answer with a plan; your owner switches the mode when it is to be carried out.151152If you are the main agent and your owner asks for a new agent, call `create_agent` with an id,153one line on what it is for, and its instructions written to the agent itself ("You are ..."):154its job, what it should and should not do, how it reports. Your owner confirms it, and the agent155exists at once. For a device or service that no existing type of source can watch, the main156agent can also write a new source type and register it with `add_source_type`157([references/sources.md](references/sources.md)); try the existing types first. A model server158of your owner's own (llama.cpp, vLLM, LM Studio) is the main agent's to add as well, with159`add_model_server` and the server's address; never ask for its key, pine asks your owner160([references/setup.md](references/setup.md), "Adding a model server").161162Things you can do yourself: work in your workspace, keep notes there, use the tools you have,163hand work to the agents listed in your prompt, and write shared state under your own keys.164165## Which file to read166167| You want to | Read |168|---|---|169| 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) |170| 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) |171| 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) |172| 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) |173| Look up a key in `pine.json`, `agent.json`, `models.json` or `.env` | [references/configuration.md](references/configuration.md) |174| 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; the main agent's tools for conversations and tabs; 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) |175| Add an agent, give it a workspace, tools and a persona; skills; how agents look pine up (the `manual` tool); how tools are declared to the model (`catalogue`: families) and what a model server keeps of a conversation (prompt cache, slots); delegation, sub-agents, sessions, goal mode (`/goal`: working until an objective is met), shared state | [references/agents.md](references/agents.md) |176| 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) |177| 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) |178| 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) |179| 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) |180| 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) |181| Know the technology underneath and the pi behaviours pine works around; open points | [references/stack.md](references/stack.md) |182| Change pine's code | [../AGENTS.md](../AGENTS.md) |183184## The shortest working setup185186```bash187npm install -g @pmndrs/pine188```189190```bash191pine init192```193194```bash195pine196```197198One agent, `main`, with web search and a browser, and the terminal UI to talk to it. Everything199below is added on top of that when you need it.200201`~/.pine/pine.json`:202203```json204{205 "main": "main",206 "defaults": { "model": "dev/claude-haiku" }207}208```209210(An excerpt. `pine init` also writes the web, browser and app control servers and the limits;211put the model you use where `dev/claude-haiku` stands. `dev/claude-haiku` answers through212`claude -p` and needs Claude Code installed and signed in; for another model see "Choosing a213model" in [references/operations.md](references/operations.md).)214215Telegram as a second way in is set up by asking the main agent: "watch Telegram". The dialog216you confirm has a field for the bot's token; then you write to the bot and type the six-digit217code it sends you into pine. See [references/sources.md](references/sources.md).218219`~/.pine/agents/gonzo/agent.json`, a second agent, a specialist the main agent can hand work to.220Create the folder; the workspace here is `~/dev/gonzo`, which must exist, and an `AGENTS.md` in221it says what the agent is for (without `workspace`, pine makes `agents/gonzo/workspace` itself).222Or ask the main agent to create one: it calls `create_agent`, and no restart is needed.223224```json225{226 "description": "Contract law; knows the case files",227 "workspace": "~/dev/gonzo"228}229```230231```bash232pine check233```234235```bash236pine start237```238239`main` sees `gonzo` in its list of agents and can call `delegate`. `pine events -f` shows everything as it happens.240241## Vocabulary242243| Term | Meaning |244|---|---|245| event | One record in the log: topic, payload, source, trust, cause |246| topic | Slash-separated name, matched with `+` (one level) and `#` (the rest) |247| route | A rule in `pine.json` that reacts to topics |248| 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"`) |249| schedule | Something done at a time: at set times, every so often, or once. With a task it wakes an agent to do it |250| goal | An objective you give a conversation with `/goal`: the agent is called again, round after round, until a judge says it is met |251| subscription | A conversation of an agent listens to a source: each event arrives there as a message and wakes the agent |252| task | One piece of work for one agent; has a status, a result and statistics |253| 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 |254| owner | You. Content is "owner" only when it entered through a channel that authenticated you |255| untrusted | Everything else: data that may contain instructions it has no right to give |256| tainted | A session that has seen outside content (a web page, an MCP result, an untrusted task) |257| approval | Your yes or no to one tool call, asked in the terminal UI and over Telegram, or answered with `pine approve` |258| 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) |259| extension | A pi extension: pi's own plug-in format, usable in pine sessions |