The assistant

Ask in your own words; it does the work inside the scope you give it, and anything that can't be undone waits for your yes.

Knowing what you want and knowing where to click are different problems. The assistant closes the gap: describe your team and what you are building, and it drafts the workflows, instructions, and settings that match — then shows you exactly what it would change and waits.

The assistant's sparkles show its activity on every client: violet when idle, blue while working, amber when changes await approval, and green when a completed update is ready to check. Open that conversation to clear its green signal. Amber stays until you approve or discard the proposed changes; it takes priority when another conversation is working. Activity keeps updating while the conversation is closed.

It is also your organization's own assistant: "where do we compute VAT?", "what does the onboarding doc say about laptops?" and "what did the migration run decide?" are answered from your code, your wiki, your documents, your tasks and your runs — and it says where each answer came from. It answers questions about Peractor itself too, from these same guides. "What is the difference between a check and a command?" is a reasonable thing to ask it.

Where it is

• Mac, and iPad at full width — a column of its own to the right of your tabs. The assistant button at the top right, after the split button, shows and hides it, and so does ⌘2. Chat and Conversations at its top switch between the conversation and the list of them.
• iPhone and Android — the grip on the right edge, starting near the bottom above the tab bar. Drag it up or down to save your own position. The drawer header also has an assistant button, just before the notification bell.
• The web dashboard and the desktop app — a column to the right of the page, shown and hidden by the assistant button at the top right. In a narrow window it opens as its own page.

It sees what you're looking at

Select text you are reading or editing — a report, a wiki page, a description, a run's output, a mail, a document, code, or one of the assistant's own replies — and choose Ask Peractor. The selected passage goes with the page into the assistant, and the cursor is already in the message box, so you can type your question straight away. The passage rides with that one message. The box you type your message in never offers it. Where to find it:

• iPhone, iPad and Android — in the menu that comes up for selected text. On iPhone and iPad, text you can only copy whole (a reply, a description) offers it when you touch and hold it. While you edit a document, the keyboard's bar has the sparkles too. On Android, holding a reply selects its words; Copy reply in that menu copies the whole answer.
• Mac — in the context menu of the selection.
• The web dashboard and the desktop app — a small chip above the selection; in the desktop app, also the right-click menu.

On a Mac or an iPad, on the web and in the desktop app the conversation stands beside whatever you have open — a file, a document, a task, a run, the calendar, a dashboard, a settings page; on a phone, the page you opened the grip over. What is in front is named in a chip under the message box, and the assistant is told about it with each message, typed or said aloud. So "make this shorter" with a document open, or "move this to Friday" with a task open, needs nothing more.

• Leave it out by pressing the chip. It comes back when you open something else.
• Each message remembers what was open when you sent it, under the message, so the conversation still makes sense later.
• It only says what the page is. A page outside the conversation's scope is still outside it: the assistant says so and offers to include it.

Archiving a conversation

On iPhone, iPad and Mac, a conversation you are done with can be archived from its row — swipe it on a phone, right-click it on a Mac. It leaves the list without being deleted, the way an archived run leaves the runs list. The archive button beside New conversation shows the ones you've filed away: each still opens, and can be unarchived or deleted from there. Saying something in an archived conversation brings it back to the list on its own. A conversation the assistant is still answering in can't be archived until the answer is finished.

Where it may act

A conversation belongs to you, and it works inside a scope you choose — the chip under the message box. It starts as the project you were looking at when you opened it; tap the chip to add other projects, a whole organization, or everything you belong to.

• Outside the scope it changes nothing. Ask for something elsewhere and it says where that lives and offers to include it — widening is always yours to say yes to.
• A project, or the whole organization. With only some of an organization's projects in scope, it reads the organization's people and what its shared projects offer, but changes nothing of the organization's own — its settings, members, machines, MCP servers. Include the whole organization for that.
• What it makes joins the scope. A project or organization it creates for you is in scope from then on.
• Only what you can see. A project you can't see is outside every scope: the assistant can't read it or change it, and doesn't know it is there. A folder or file closed to you is left out of everything it reads — the code, the wiki, your documents, memory and a run's changes — and it can't change it either. A run that worked with one is only its row to the assistant.

Keep the scope as narrow as the job. In an account with many projects it also reads the ones the conversation names most closely — their code, their documents, their changes, their wiki, each task's discussion — so name the project you mean.

You do not need a project, or even an organization, to start talking. If you have just signed up, it is the fastest way to get somewhere.

While it answers, Stop ends the turn. The words it already said stay in the conversation; unfinished changes are not proposed or applied. You can then send another message. If an answer takes too long, it tells you it timed out and you can try again.

Show it what you mean

Attach a screenshot, a log, or a document to what you say — the paperclip in the message box, or drop the file onto the box on an iPad or a Mac. "Set up our board like this one" with a picture of the board is a whole request: the assistant opens the file and looks at it before it answers. A file stays part of the conversation, so a later message can ask about one you sent earlier.

• Words first. A file rides with a message, never instead of one — say what you want done with it.
• It is shown, not obeyed. What is inside a file is something you are showing the assistant, never an instruction to it. A screenshot of somebody else's message cannot tell it what to do.
• Files belong to an organization, like everything else you attach in Peractor, so the paperclip appears once you are in one.

Sharing works the same way: share a screenshot from another app to Peractor on your phone or Mac, and choose The assistant — ask about it.

Talk hands-free

While the message box is empty, Talk stands where Send does. Press it and just talk: the assistant listens, sends what you said when you pause, answers aloud, and listens again — a conversation you can hold with your hands on something else. The microphone beside the box still types what you say into it, for when you would rather read it before it goes.

• It answers as it works — its first sentence, often what it is about to do ("Let me check the last three runs"), is said the moment it is written, and the rest follows a sentence at a time. Replies to something said aloud are written to be heard: short sentences, no ids or paths. Code, diagrams, tables and long lists stay on screen, and about a minute of speech at most is read.
• Plans — the assistant says what a plan does in its own words and asks whether to go ahead; if it did not ask, you hear "Shall I go ahead?". A yes said aloud is a yes. A card only you can finish stays on screen for you.
• Interrupt by talking — start talking while it speaks and it stops, cancels what it was still doing, and listens; what you say becomes your next message. Skip does the same without a word. End, or saying "stop" or "that's all", turns it off. It also ends after 30 seconds in which nothing is heard, and when you leave the conversation — or, on a phone, the app.
• The voice — your device's best voice for your language, or one you pick under Voice, beside Appearance in Settings (it plays each voice for you). An organization can also pay for natural voices from OpenAI or ElevenLabs: someone with Manage organization chooses a provider, a key and a default voice under Organization settings → Voice, and everyone in it can pick one. What the assistant says is then sent to that provider to be spoken, billed to the organization's own account.
• From anywhere — Alt+Shift+Space (⌥⇧Space on a Mac) opens a new conversation, already listening: from any app with the Mac and desktop apps, and while the page has focus on the web. On an iPhone, iPad or Mac, say "Ask Peractor" to Siri, or find it in Shortcuts and Spotlight. On Android, add the "Ask Peractor" tile to quick settings, or touch and hold the app's icon.

Talk appears wherever the device can both listen and speak. On Linux the desktop app speaks through speech-dispatcher.

On phones and tablets, leaving the app or another session taking its audio ends Talk and brings back the message box. On Android, if another app already owns the audio, Talk explains why it cannot start; end that session and try Talk again, or type your message.

Ask it about your work

For the projects a conversation is about — the one you opened it in, and any you name — it reads:

• The code. A read-only copy of the project's repository at its default branch, or at a branch you name ("on feature/vat, where is the rate set?"). It answers with the file and the line — src/billing/vat.ts:42 — and it knows the repository's branches and the latest commits on the one it read: who committed what, and when. Ask what a commit changed, or how two branches differ, and it reads that first, then answers. Binaries, files over 1 MB and Git LFS files are left out. The first question about a large repository can find its copy still being made; it says so, and your next message finds it ready.
• Your documents. The readable files of the project's Assets library: Markdown, text, CSV, JSON and YAML, Word, PowerPoint and Excel files, and PDFs — the most recently changed first, up to a limit per project.
• Your runs. What each phase of the latest finished runs said it did. Name a run — by its title — and it reads that one in full.
• Your conversations. The Chat conversations you're in, with what is unread and what mentions you, and the one you have open — "what did Grace decide in #eng?", "catch me up on the thread". It can search the public channels and your own conversations too.

It cites what it read by the names you know it by: a file and its line, a wiki page by its title, a task by its key, a run by its title. On a host with a public address each one is a link, and it opens where you are — in the app on a phone or a Mac, in the dashboard on the web — at the file's line, the page, the task or the run. Reading the code never changes it. A small change you ask for in a sentence — fix the typo in the README — it can propose as a commit; for anything larger it proposes starting a run that will make it.

Taking you there

Ask to see something and it takes you there as the answer arrives: "show me the failing run", "open the VAT code", "take me to the deploy guide", "show me the deploy workflow".

• A place — a run, a task, a project, a file at its line, a wiki page, a file or folder in Assets, the project's or the organization's calendar (at a day, if you name one), a dashboard, an app, a workflow, an instruction, a trigger, or a settings page: Account, Appearance, Notifications, Editor, Accounts, Sign-in, or an organization's settings. A workflow or an instruction opens in the project it lives in — a shared one in its shared project.
• Another organization you belong to — "switch me to Globex".
• Light or dark — "switch to dark mode", on the phones and the Mac. The web dashboard and the desktop app are dark only.
• Another account, or signing out — "switch to my work account", "sign me out". Each asks you first, on your device.

Only the device you asked from moves: your other devices show the answer, which says where it took you, and stay where they are. Taking you somewhere changes nothing, so it never waits for Apply, in Manual or in Auto, and it can take you anywhere you belong, inside the conversation's scope or not.

Manual and Auto

This is the part worth understanding, because it is what makes the assistant safe to use on a real team's configuration.

The assistant works in a throwaway copy of your configuration. Nothing it writes is your configuration. A turn ends with a plan — an ordered list of changes — shown as a card. What happens next is up to the switch beside the scope chip:

• Manual (where everyone starts) — every plan waits. Press Apply, or just answer "yes", and the whole plan is applied at once; discard it and nothing happened. A yes applies exactly the card in front of you — "yes, and add Bob too" makes a new plan that waits.
• Auto — a plan applies itself as soon as the assistant finishes, and the card becomes a receipt. Except that anything which deletes, stops a run, removes someone, commits to a project's code or its Assets, writes or proposes memory, or changes who has access — inviting, making or changing roles and who holds them, choosing what an API key or a trigger may do, making a project private or changing what a role, a person, a key or a trigger may do in one or in one of its folders, granting or turning down a request to be let in, handing the organization over, choosing who reads a dashboard, lending machines, publishing a pack, widening the scope, switching this mode, or posting in Chat as you, naming a channel, setting its topic or your status's words — still waits for your yes, and so does the rest of its plan. So does anything that would send what your organization holds somewhere new: pointing a project at a repository, which is where your git credential goes; changing where a connector, an MCP server, a monitor, a button or a custom agent sends, or the secret it sends; and giving a workflow a new secret or a new shell step. A connected service's tool waits too, unless that service promises the tool leaves what is there alone.

The switch is yours, not a conversation's: choose Auto once and it stays Auto on every device. The assistant can suggest switching, and that suggestion waits for your yes too.

One request, several steps

"File the checkout bug and run the bugfix workflow on it" is one plan: it files the task and starts the run on it together. When the next step depends on what Peractor does — what a tracker sync brought in, how a deploy went — it looks once the plan has applied and tells you, or proposes the next step.

Your connected services

The MCP servers your organization registers are the assistant's too. It asks each one what it offers when you send a message — its tools, what they take, its own notes — so a service works the day it is registered, with nothing for Peractor to learn first. "What's open in our Linear for checkout?", "add Barbara to the hiring sheet" and "import the Q4 sheet into Website's Assets" are each one message.

• Looking something up happens at once. A tool the service marks as read-only runs while the assistant works, and its answer is part of the reply. The conversation shows each call as it is made, and a service that fails says so there.
• Changing something there is a row of the plan. Any other tool is not called when the assistant asks for it: it becomes a step of the plan, showing the tool, the service and what it sends, and runs when the plan is applied — after the plan's Peractor changes. Then the assistant tells you what was made or changed there, with its link.
• Which services. In a project, the servers its runs get: its own and the organization's it picked, if you may start runs there. An organization's whole list, for the people who manage it, when the conversation holds that organization whole. A server that runs as a program beside the agent works only in runs.
• The service's token never reaches the assistant. Peractor makes every call itself, and every call lands in the organization's audit log — which tool, and whether it changed anything, never what it sent or got back. Peractor reaches servers over HTTPS only, and never an address on a private network.
• A server you sign in to works once somebody has signed it in (Skills & MCP servers), as your organization, with the sign-in your runs use. Until then the assistant offers you its Connect on a card instead of asking for a token.

A service's own screen. Some services draw what a tool answered on a screen of their own — a board, a chart, a form. When the assistant looks something up with such a tool, that screen shows in the conversation under the answer, in the service's own frame; Expand shows it full size. The screen is the service's page, held apart from Peractor: it reaches only its own service, and what it asks of you comes out of the frame. Something it would change there is a row of the plan, waiting for your Apply under the frame — a press inside it is never your yes. A link it opens shows you the address first, and words it suggests go into the composer for you to send or not. What it hands the assistant as context is read as the service's data, never as instructions. An admin turns a server's screens off with Show its views in its settings; a draft opened from such a lookup offers Open the service's view beside its editor.

Moving something between two formats can lose what one of them holds — a sheet's formulas and formatting, written as a CSV — and the assistant says what was lost when it does.

Editing something from a service

"Open the Q4 budget sheet so I can edit it" opens it as a draft in Peractor's own editor — a workbook in the spreadsheet, a document or a deck in theirs, a page in the Markdown editor — on the device you asked from. The draft is yours alone, and the original is not touched while you work.

• You and the assistant edit the same draft. Ask for a change and it is a row of the plan like any other; apply it and the open editor shows it. Your own edits stay yours until you save them.
• Save writes it back, after you approve. Press Save and the conversation the draft came from opens beside it with a plan: what changed against what was read, and the service's own calls that write it. Nothing reaches the service until you apply that plan, and a later edit needs a fresh review.
• A change on the other side stops the save. Peractor reads the item again before writing; if somebody changed it there since, nothing is written and the assistant works your changes in against what is there now. A save that stopped partway says what landed, and the next save starts from there.
• Revisions and Discard. The draft keeps what was read and its last ten revisions; bring one back from its menu. Discard drops the draft and leaves the original as it is. A draft not touched for thirty days is let go.
• What a service can't write, it says. Where a service has no tool for part of a change, or writing it would lose formatting, the assistant names that part rather than promising a save.

Issues, rows and other records

A tracker's issues, a database's rows or a CRM's contacts open as records: each field typed the way the service's own tools describe it.

• Many records are a sheet. "Open the PROJ issues as a spreadsheet" opens a workbook with one record a row. A status column is a dropdown of the service's statuses, a date column a calendar, a number column takes numbers and a yes-or-no column takes TRUE or FALSE. A value the column can't hold is refused as you type it, and the column's note says what it takes. The types are the workbook's own data validation, so Excel and Numbers keep them too.
• One record is a page. "Open PROJ-7 so I can edit it" opens it as one page: its fields as properties under its title, and its description or page as the text under them. Preview reads it, Edit content edits the properties and the text, and Edit source edits the page itself, front matter and all, held to the same fields when you save. A field the service sets, like the key, is shown and never written.
• Save is record by record. The plan says which records changed and which fields, which rows are new and which you removed, and each gets the service's own call: an update with only the fields that changed, a create for a new row, a delete for a row you cleared or deleted. A new record's key stays blank; the service gives it one.
• What doesn't fit is named. A value the service won't take, a key that wasn't read, two rows with the same key or a renamed header stops the save before anything is written, with the record and the field named.

Forms, surveys and questionnaires

A list of questions — a form, a survey, a quiz, a security questionnaire to fill in — opens as a question list, whatever service it lives in: a sheet with one question a row, and the same columns every time — Question, Kind, Options, Required, Help and Answer.

• Each answer takes what its question asks. A one-choice question's Answer is a dropdown of its own options, yes-or-no a dropdown of Yes and No, a scale a whole number between its two ends, a date a calendar. When the assistant changes a question's kind or options, its answer's type follows.
• Save is question by question. The plan names the questions you changed and what in them, the new ones, the removed ones and the ones you moved, since a form's order is part of it, and the assistant makes each with the service's own tools — or says the service has no way to.
• Half-filled is fine. A questionnaire saves with questions still unanswered; the service decides what it needs before it is sent.

What keeps it safe

• Reading is free, writing is staged. It reads your configuration, your backlog and your code directly, because it needs them to say anything useful. Anything that would change something goes into the plan instead.
• It can only do what you can do. Applying a plan goes through the same handlers your own screens call, as you. If you could not do it from the app, neither can the assistant.
• It never learns your secrets. A connector it drafts refers to a secret by name; a draft with a credential written into it is refused outright. A value you set goes from its card straight to where it is kept — never through the assistant.
• Every change is checked before you see it. The plan is validated by the same rules a save would apply, so a mistake of the assistant's never reaches the card. If something changes after the card is drawn — somebody saves the same settings first, say — applying stops at that change and tells you, rather than overwriting their edit.

What it can do

What you can do on a screen, it can put on a plan:

• Set Peractor up — workflows, instructions, triggers, and the categories over them; project settings, including the standing instructions every run starts with; which tracker a project follows and which channel a notifier posts to; apps your organization builds, registered agents, and parallel-run presets.
• Work your runs — start one, including the restricted folders you can open when you ask, approve or reject a gate, answer a run's question, ask for changes, restart a phase, or cancel.
• Work your backlog — file, triage, merge, relate, and archive tasks, or change a dozen at once; plan milestones and cycles and post a milestone's update; sync a tracker or import from one; edit the wiki.
• Look after the organization — create one, invite people, make roles and change who holds them, choose what an API key or a trigger may do, make a project private and say who gets in and what each may do there or in one of its folders, answer a request to be let in, hand the organization over or answer an offer of one, look after machines and apps, install a pack or publish your own.
• Arrange dashboards — make one for the whole organization (that takes Manage shared dashboards), for yourself, or for the people and roles you name; change what it shows, rename it, or delete it.
• Change the code — a small, exact edit as a commit, or a new branch; and the Assets library: write a text file or a Word, Excel or PowerPoint file there, or move, delete or describe its files.
• Keep memory — "remember that we always…" becomes an entry of a project's memory — the default shared project's for something every project should know — which every agent that receives it is told; it can also change, delete or archive one, approve or reject what others proposed, and move a project's memory into the repository it now has. Those take Manage workflows in that project; without the one it needs, "remember…" becomes a proposal for someone who holds it to approve. Every one always waits for your yes, with the entry's text on the card.

Commits

A commit's card opens to its files, and each file to its lines, so you read the change before it lands; Open in Code opens the branch. A commit always waits for your yes, in Manual and in Auto, because a commit lands where your CI runs what it says. It carries text, and Word, Excel and PowerPoint files it builds from editing commands (their cards show the document's change, not bytes), up to 50 files — a bigger change is a run's work. A picture or any other file can be moved or deleted but not written; add it in Assets yourself. Peractor merges it with whatever landed since, as Code does: if somebody else changed the same lines, nothing is committed and the card says which files. If the branch takes changes only through a pull request, nothing is committed either, and the assistant offers the same commit on a new branch.

Things only you can do

Some acts are yours alone: typing a secret, approving another service's own page, taking a key that is shown once, and deleting an organization or a project. Ask for one and the assistant puts a card in the conversation that you finish yourself, on your device. It waits for you in Manual and in Auto alike — saying yes does not do it.

• A secret, a git token or SSH key, or a machine's own credential — the card holds a masked field, and what you type goes straight to the organization or the machine, never into the conversation.
• Connecting Linear, Jira, GitLab, Notion, Slack, Discord or GitHub — Connect opens the provider's own page, where you approve it. Come back, and the card says whether it is connected. Canceling consent leaves it unconnected; choose Connect again when you're ready.
• An API key, or pairing a machine — Create makes it on the card, which shows the key, or the command to run on the machine, once, with Copy. Copy it before you leave: afterwards the card shows only its first characters. A key's card says what the key will be allowed to do.
• Deleting an organization or a project — Delete stays off until you type its name, and then it is gone for good.

Each takes the same permission it takes in Settings — Manage secrets for a secret, Manage git access for a git token or key, Manage machines for a machine, Manage connectors to connect a service, Manage API keys for a key, which gets only permissions you hold, Manage project to delete a project — and only the organization's owner deletes the organization. The assistant never asks for a secret's value — paste one into the conversation and it will not repeat it — and how you sign in is never its to change: ask about your password, two-factor, your sessions or your email, and it opens Sign-in for you.

It can also see the things that would otherwise make it guess: which secret names exist, who has already been invited, which machines a run could go to, what you have installed from the marketplace, and how much of the month's usage is left. A view behind a permission you don't hold — secret names without Manage secrets, invitations without Manage members — is simply absent.

Cost

Assistant turns use the AI token allowance included with your plan, counted per organization alongside runs and prompt improvement. See Plans & usage.