Agents

Agents are AI helpers that work inside your workspace. Instead of a chatbot in a separate tab, they can read your notes, plans, and files, and propose changes you approve.

Undra ships with Mira, a built-in assistant, and you can create your own agents for the work you do over and over. Whichever you use, it runs on the AI provider you have connected: a Claude or ChatGPT subscription, or a local model on your own machine.

What an agent can do

• Answer from your work. Ask about the current note, a selection, or your whole library, and get an answer grounded in your real material rather than the open web.
• Summarize and draft. Turn a messy meeting note into a summary, draft a brief from scattered ideas, or pull the open tasks out of a project.
• Propose changes. Create a new note, edit a plan, or fix a typo across files, surfaced as a proposal you review before anything is written.
• Run on a schedule. A routine can do any of the above on its own, on a daily or weekly schedule, or at a regular interval (every few hours).
• Remember what matters. Tell an agent a durable fact or preference once (how you like your summaries, what your projects are called) and, with your approval, it carries that context into every later run.

Grounded in your workspace

A generic chatbot forgets you the moment the tab closes. An Undra agent works from your actual files: the note in front of you, the items you select, the things they link to. Ask “what’s left before the Phoenix launch?” and it reads the real plan instead of guessing.

Propose, review, apply

The pattern is always the same: gather context, propose, you review, apply. When an agent wants to change something, you see exactly what would change and decide whether to accept it. Nothing is written to your files behind your back.

Make your own agent

Save an agent when you want a behaviour to be reusable and understandable instead of a one-off prompt you rebuild every time: a “weekly review” agent, a “tidy this note” agent, a “draft release notes” agent. Create, duplicate, and delete them like any other item.

Where to create one

Agents live in the AI section of the explorer, in the Agents group. To make a new one, use the New Agent action at the bottom of that group, or right-click inside the Agents area and choose New Agent. That gives you a fresh, empty agent and opens its editor.

Under the hood, each agent is just a small folder in your workspace, so it is yours, portable, and readable. You never have to touch these files by hand, but it helps to know they are real:

.undra/ai/agents/<your-agent>/
  AGENT.md      the agent's definition

AGENT.md has two parts: a short block of settings at the top (its name, what it is allowed to touch, which skills and tools it can use) and, below that, the role instructions written in plain markdown. The role instructions are the heart of the agent: they are the standing brief that tells it who it is and how to do the job, every time it runs.

The fields you fill in

The editor opens on a Configure tab with just a few things to set:

• Name and Description. What the agent is called and a one-line note on what it is for.
• Role instructions. The standing prompt. Write here what you would otherwise type into the chat every time: the goal, the tone, the steps, what to do when it is unsure. This is where most of the behaviour lives.
• Skills and Tools (under the Knowledge tab). Skills are reusable chunks of guidance that get folded into the agent’s instructions on every run. Tools are the actions it is allowed to take, like searching your workspace or proposing a new note. You switch each one on or off.
• Permissions (back under Configure). What the agent is allowed to touch. This is covered in detail just below.

The model an agent runs on follows your connected AI provider and Undra’s default, so there is no separate model picker to wrestle with for a basic agent. If you want a specific model, see Settings.

From a one-off prompt to a saved agent

If you keep typing the same long instruction into the chat, that is the signal to save it as an agent. The move is small:

1. Write the prompt as role instructions. Take the wording you keep reusing and paste it into the agent’s role instructions. Make it standing rather than one-off: “Every time, do X, then Y” instead of “this time, do X.”
2. Turn on what it needs, and only that. Attach any skills it should always apply, switch on the tools it needs, and set its permissions (next section).
3. Test it before you trust it. The editor has a Test Agent panel: give it a sample request, run it, and read the output. Test runs are read-only and cannot change your files, so you can iterate safely.
4. Save, then reuse. From then on you call the agent by name instead of retyping the brief, and you can also drop it into a routine to run it on a schedule.

What an agent is allowed to touch

An agent only uses the tools you allow it. Give it read-only access, or let it propose edits. Its permissions are yours to set, and it respects them exactly.

Permissions are not a vague promise. They are explicit switches in the agent’s Configure tab, under Permissions, and Undra enforces them: a capability is off unless you turn it on, and an agent simply cannot reach for a tool its permissions deny, even if its instructions ask it to.

Flip a permission and watch the agent’s tool calls turn allowed or blocked. These limits are enforced where the agent runs, not just suggested.

The switches are:

• Can use tools. The master switch. With it off, the agent can only talk, never act. With it on, the more specific permissions below decide what those actions can be.
• Can read workspace. Lets the agent search and read your notes, plans, and files for context. This is what makes it grounded in your real material rather than guessing. Leave it off for an agent you want kept to general help with no access to your library.
• Can use network. Lets the agent fetch from the web (for example, pulling a recipe or article from a URL). Off by default, so an agent stays local unless you opt it in.
• Can stage changes. Lets the agent propose edits: a new note, an edited plan, a fix across files, surfaced for you to review. It cannot apply anything on its own.
• Can write only after approval. The gate on the line above. Proposed changes wait for your explicit yes before they touch a file.

Read-only vs propose-edits

This is the dial most people care about, and it is just a couple of switches:

• Read-only agent. Can read workspace on, Can stage changes off. It can answer from your work and summarize it, but it has no way to change anything. Good for a research or review agent.
• Propose-edits agent. Can read workspace on and Can stage changes on. It can draft real changes, but they arrive as proposals you review and approve. Good for a “tidy this note” or “draft release notes” agent.

The granularity is per-capability, per-agent: reading, network, and proposing edits are separate switches, so you can hand out exactly the access a job needs and nothing more. A summarizer can read but never write. An importer can fetch from the web but stay out of the rest of your files. Each agent carries its own limits, saved alongside it.

Run it on its own

You do not have to be there for an agent to work. Turn one into a routine and it runs on a schedule you set: every morning, every Monday, or at a regular interval. The agent does its job, leaves its output in your workspace, and you read it when you are ready.

Think of a weekly-review agent that gathers the week’s open tasks into one summary, or a digest agent that pulls anything new in a folder into a single note. It is the same agent you built and tested by hand, now running without you. Every run is recorded under the agent’s Activity tab, so you can always see what it did and when.

It remembers what matters

An agent starts each run from its role instructions, but it can also carry a small, durable memory: the handful of facts worth keeping between runs. How you like your summaries. What your projects are called. A constraint you stated once and should not have to repeat.

You stay in control of that memory. An agent can suggest something worth remembering, and it only sticks once you approve it. You can add, edit, or remove memories yourself from the agent’s Test tab. Nothing is memorized behind your back, and what is remembered is plain to read.

Share an agent, or use someone else’s

Because an agent is just a small folder of plain files, it travels. You can hand a working agent to someone else, or install one the community has published (for example, a chef that turns a recipe URL into a clean note). When you install one, Undra shows you up front exactly what it can touch, the same permissions you would set yourself, and you approve before it runs. From there it behaves like any agent in your workspace: open it, read its instructions, and change anything you like.

Trust is the point

Agents should make you faster without quietly taking ownership of your files. Everything stays local, every change is reviewable, and you decide what each agent can touch. That is what makes leaning on AI here feel safe rather than risky. See Local-First Trust for the foundation underneath it.

Where to go next

• Notes: the material agents read and write.
• Workflows: turn an agent into a repeatable, scheduled routine.
• Folder Portals: give an agent scoped access to a real folder on your disk.
• Local-First Trust: why AI here can be powerful and safe.