Scripts

A script is a small program that runs inside your OS with real access - reading and writing files, calling another app's tools, reaching the network - but only as much access as you grant it, checked every single time it asks. You can ask the assistant to write one, or start from the Scripts app.

What a script can do

A script exports one function that receives a context object and whatever fired it. The context gives it:

• Files - read, write, list, and check for a file, scoped to whatever paths you grant.
• Events - emit an event onto the OS event bus, or look back at recent ones.
• Intents - ask another app to do something (open a note, start a call).
• Notifications - show one.
• Storage - a small private slot just for this script.
• Network - fetch a URL, through the same approval flow the rest of the OS uses for a new host.
• Tools - call another app's agent tools, by name, from a list the script declared up front.
• Agents - start a full agent run.

None of this is available unless you granted it. A script that asks for "read my notes" can read your notes and nothing else - not your mail, not your calendar, not the rest of the filesystem.

Where it runs

A script runs in its own sandbox with no window and no direct line to the network - it cannot open a connection on its own, cannot read the page, and cannot touch anything outside the narrow channel that checks every request against what you approved. If a script tries to reach the network directly instead of through the network capability above, it fails immediately and loudly, the same way it would if it tried to write somewhere it has no permission for.

A script also can never write into the folder that holds installed apps, other scripts, or extensions - not even its own - no matter what you've granted it. That boundary exists specifically so one piece of installed code can never quietly rewrite another.

Binding a script to something

A script does nothing on its own until you give it a trigger:

• A command - it gets a name in the strip, and optionally a keyboard shortcut.
• An event - it runs whenever something matching a pattern happens elsewhere in the OS (a note saved, a message arriving).
• A schedule - it runs on a repeating interval, or once a day at a time you choose. Under the hood this becomes an Automations rule, so you'll see it show up there too.
• Manual - it only runs when you (or the assistant) tells it to.

A script can have more than one trigger, and can also hook into six moments right before they happen - a note about to be saved, a note about to be created, a folder about to be created, a message about to be sent, a calendar event about to be added, a setting about to change - and either let it through, veto it with a reason, or rewrite what's about to be saved.

Limits

A run gets 30 seconds by default; running one by hand can go up to 5 minutes if it genuinely needs it. A hook gets 2 seconds, since it sits in the middle of an action you're actively taking and shouldn't make you wait. A script that runs past its budget is stopped outright - it does not get a chance to clean up first. Every run, however it ends, is recorded: what fired it, how long it took, and what it produced or why it failed.

Approving a script

Before a script can run, you approve exactly what code it is and exactly what it may touch. If the code changes afterward - you edited it, or something else on the machine tried to swap it out - it stops running until you approve the new version. This is the same approval a script keeps getting checked against on every single call it makes, not just once at install.

Calling one of your own agent tools works the same way any destructive action does elsewhere in the OS: if what it's about to do needs a second look, you get asked, in the same place you'd get asked for anything else that needs approval.

Installing from the community, and sharing your own

Like apps and skins, a script can come from the community catalog - installed with a verified download and the exact permissions it declares, which you still get to see and approve. If you've written something worth sharing, the Scripts app can propose it back to the same catalog for others to install.

The context object, in full

The function a script exports is called with two things every time it runs: a context object, and whatever fired it. The context is:

• Files - read, read as text, write, write text, list, check details, check existence, make a folder, remove - every call is checked against your grants at the moment it's made, not once at install.
• Events - put one on the OS event bus, or look back at recent ones matching a pattern.
• Intents - ask another app to do something, the same way a card's click does.
• Notify - a plain OS notification with a title and a body.
• Storage - get, set, or remove a value in a small private slot (256 KB) that belongs only to this script.
• Network - fetch a URL, through the same approval flow anything else uses to reach a new host for the first time. There is no other way out to the network - reaching for it directly fails immediately, on purpose.
• Tools - call another app's agent tool by name, only from the list this script declared up front; a name outside that list is refused before it is even looked up.
• Agents - start a full agent run without waiting on its answer.
• Log - anything logged here shows up in this run's entry in the run log.
• What fired it - a command, an event (with its payload), a schedule, or a manual run (with whatever input it was given).

A script can also export a set of before-hooks, one function per action it watches (see "Changing how things work" above), and a set of extra named entry points a command with more than one job can point at.

The manifest, field by field

A script is one folder: a small manifest plus its own source. The manifest names an id, a display name, a version, an optional description, which permissions it's asking for (the exact same list an app declares - reading or writing a folder, events, network, storage, agents), which of your agent tools it may call by name, and one or more triggers - a command (with an optional keyboard shortcut), a pattern to match on the event bus, a schedule (a daily time, or a repeating interval), or manual-only. If it watches any of the six before-hook moments, it lists which ones by name.

Three scripts, worked through

A command that files today's screenshots. Triggered from the strip or its shortcut: it lists a screenshots folder, keeps only what changed today, and moves each one into a dated subfolder it creates if it doesn't exist yet - permissions: reading and writing that one folder, nothing else.

An event script that tags mail. Triggered on a pattern matching new mail arriving: it reads the message that just came in from the event's payload, and if the sender matches someone the person named, dispatches an intent that adds a label - permissions: events, and reaching the mail app through an intent, no filesystem access at all.

A hook that enforces a mail subject. Registered on the "send a mail message" moment: it looks at the subject about to be sent, and if it's empty, cancels the send with a reason instead of letting an empty-subject message go out - the person sees that reason immediately, as a notice, and the message stays a draft.

What's next

• Turn a one-off request into a repeating job - the same Automations rules a scheduled script becomes.
• Making apps with the assistant - the closest sibling to scripts, for something that needs its own window instead of running in the background.
• Community tools - publish what you built, or find what others have.