Scripts (Beta)

Last reviewed: 2026-11-17

A script is a small program for what a model does badly and a program does the same way every time: counting, sorting, comparing, adding up. You write it in JavaScript. It runs in a closed box inside Plainva: it cannot open a file, reach the network or wait for later. It only calls the tools you ticked for it: they read your vault the way the AI’s tools do, or leave a suggestion that you decide about. A script that you start here changes nothing by itself; one that the AI starts in a conversation can write directly where you let it (see “In a conversation” below).

Running a script

Your scripts stand under Skills in the AI tab — on the phone on the AI screen under skills — in the group Scripts. Run opens the script: fill in what it asks for and press Run. While it runs you see each tool it calls, and Stop ends it. Afterwards the dialog shows the Calls, the Result — which you can copy — and the Log, and what the run used of its limits.

A run you start here stays on this device: nothing of it goes to a model, so it also reads notes you keep from the cloud. Dry run calls the tools that read, and only writes down a call that would show something in the app or leave a suggestion.

In a conversation

In an ordinary conversation the AI can find your active scripts and run one when it fits; the step then reads Running the script “word-count”. The script reads only what that conversation may read: a note you keep from the cloud stays kept, and every note the script reads counts among what the run read. What it returns goes to the model as data, never as instructions. A routine, a skill’s test run and the doors Explain image and Make a note of it run no script, a conversation started with a skill is offered none, and neither is an AI app connected through the MCP server.

Suggesting changes

A script can also be given tools that suggest. The tools Suggesting changes to a note and Suggesting a property value leave a suggestion in the margin of a note; Drafting a note, Drafting a database entry, Drafting a task and Drafting a journal entry leave a draft. Both carry the script’s name. A script you start here with Run writes nothing directly: nothing in your vault changes before you accept a suggestion or create a draft — exactly as with a suggestion of the AI. After a run the dialog lists them under Suggestions and drafts; a run started with Dry run leaves nothing.

What a script read decides where it may write: a suggestion or a draft that rests on a note you keep from the cloud is taken only by a place under the same rule. In a conversation the AI is offered a script that suggests only where the conversation can suggest itself, and what the script leaves there carries the name of the conversation’s model. Where the conversation applies changes directly — with the chip Apply directly, or for a target in a folder that allows Change without asking —, what such a script writes goes in directly too: a change to a note and to its properties, a new note, a database entry, a task or a journal entry, with the same net as the assistant’s own direct changes (see “Apply directly” in AI Assistant). One run can change many notes this way: the AI may start a script in every step of its answer, and each start may make as many calls as the script’s limit allows. Each change keeps its version before, and the answer lists them all with Undo all. Without that leave the script leaves suggestions and drafts, as above.

Writing a script

New script asks for:

Create and approve writes the script into your vault as .agent/scripts/<name>/ — a manifest.json and a main.js — and approves it on this device. Edit in a script’s menu opens the same form; Save and approve replaces the files.

The code is the body of a function. input holds the inputs by name, tools.<name>(…) calls a tool and is awaited, return hands back the result, and console.log(…) writes a line into the log:

const found = await tools.search_vault({ query: "#" + input.tag, limit: 25 });
const notes = [];
for (const hit of found.results) {
  const note = await tools.read_note({ path: hit.path });
  if (note.text.includes("#" + input.tag)) notes.push(hit.path);
}
return { tag: input.tag, count: notes.length, notes };

The language is current JavaScript — ES2024, with most of ES2025 — without Intl. There is no fetch, no timer, no import and no file access, and what a script returns must be data that can be written as JSON. A tool that refuses — a note that does not exist, a note the conversation may not read — throws an error the script can catch.

What a tool returns

What a tool returns in the form opens this page. Every tool takes one object and returns one; cursor takes the next of the call before and continues its list.

ToolYou passYou get
search_vault — Searching the vaultquery; optional folder, limit (up to 25), cursorresults: a list of { title, path, snippet }; next
read_note — Reading a notepath; optional section, maxChars (200 to 20,000), cursorpath, text, next
get_outline — Reading the outlinepathpath; properties: name and value; sections: a list of { level, text, section }
query_base — Reading a databasebase, the path of the .base file; optional view, limit (up to 50), cursorbase, view, views; rows: a list of { title, path, properties }; next
get_tasks — Reading tasksoptional range (today, upcoming, overdue, inbox, all, done), limit (up to 50), cursortasks: a list of { state, title, due, priority, path, note, source }; next
get_backlinks — Reading backlinkspath; optional limit (up to 50), cursorpath; notes: a list of { title, path, links, places }; next
graph_neighborhood — Following linkspath; optional depth (1 or 2), limit (up to 50)path; notes: a list of { title, path, fromHere, toHere, via }
get_recent — Looking at recent notesoptional kind (opened or edited), limit (up to 20)kind; notes: a list of { title, path, at }
get_changes — Looking at what changedsince as YYYY-MM-DD; optional until, folder, limit (up to 20)since, until; notes: a list of { path, title, kind, made, last, added, removed, gained }
get_note_history — Following how a note developedpath; optional since and until as YYYY-MM-DD, at most 31 days apartpath, since, until, made; days: a list of { day, added, removed, gained }
get_calendar — Reading appointmentsfrom and to as YYYY-MM-DD, at most 31 days apart; optional details, limit (up to 100)events: a list of { day, start, end, allDay, title, cancelled, place, with, others, online, event }; more
run_command — Using the appid, a command of the app such as open-note, show-in-graph or open-calendar; optional args with path, section or datedone, command
propose_edit — Suggesting changes to a notepath; edits, a list of { find, replace }, or append; optional section, noteproposed, path, passages
set_property — Suggesting a property valuepath, key, value; optional noteproposed, path, property
create_note — Drafting a notetitle, content; optional folderdrafted, kind, title
create_entry — Drafting a database entrybase, title; optional properties, contentdrafted, kind, title, base
create_task — Drafting a tasktextdrafted, kind, title
add_journal_entry — Drafting a journal entrytext; optional taskdrafted, kind

Limits

A script carries its limits in its manifest. The form sets three of them:

LimitDefaultRange
Seconds of computing51 to 30
Tool calls200 to 50
Memory in MB328 to 128

Only the time a script computes counts, not the time a tool takes. A script that goes over a limit — time, memory, steps, the number of calls, the size of the arguments of one call or the size of its own result — is ended, the dialog says which limit it was, and an ended script returns nothing. A tool’s answer that is larger than the limit for one call is no end: the script gets an error for that call and runs on. By default the arguments of one call, what one call hands back and the result may each be 64 KB at most; a manifest may allow up to 256 KB.

Nothing runs before you approve it

A script that is new or changed — through sync, or written by another program — does not run until you approve it on this device. It waits at the top of Skills under Waiting for your approval. Review and approve shows What it may do, its Limits, its Input and the whole Code, and says whether the code can be read as JavaScript; code that cannot is not approved.

With Approve, this device signs exactly these files. The key for that is made on this device and kept in its keychain. Any change to a file lifts the approval, and on each of your other devices the script waits for an approval of its own — an approval cannot be carried from one device to another. Withdraw approval in a script’s menu takes it back, and Show code shows the review again.

Limits of the beta

A script suggests and drafts, and writes directly only in a conversation where you let the assistant apply changes directly; it never renames, moves or deletes a note, and it writes no e-mail and no appointment. A skill cannot start a script, and a skill’s own scripts/ folder is not run. Mail, the internet and the tools of external servers are not available to scripts.