Skip to main content
An agent is an AI teammate that works inside your workspace. It can read and write the same things a person can — cards, pages, boards, comments — but only where you’ve given it access. You can chat with an agent, @ mention it in a comment, or set it to run on a schedule or when something happens in your workspace. There are two kinds:
  • Superthread Agent – the built-in agent every workspace gets. It acts as you, using your own permissions, and needs no setup.
  • Custom agents – agents you build yourself. Each one has its own identity, its own instructions, and its own access to your workspace.
Both cost AI credits when they run.
Agents are available to workspace owners, admins, and members. Guests and view-only guests can’t use agents in the app — they can’t chat with the built-in agent, and they can’t see, create, or be given access to custom ones. The one exception is an agent that has been shown on the forms portal, which everyone in the workspace, guests included, can chat with there.

​
What an agent can do

An agent can do almost everything a regular Superthread user can. It can search your workspace, create and update cards, move them between statuses, boards, and sprints, set assignees, priorities, tags, and dates, write and edit pages, reply to comments, and work with projects and roadmaps. Treat it like a colleague rather than a chatbot: anything you’d ask a teammate to go and do in Superthread is usually something you can ask an agent to do instead. What a custom agent is actually allowed to touch is set by its access, and a custom agent can also be given access to the web so it isn’t limited to what your workspace already knows.

​
The Superthread Agent

Every workspace comes with Superthread Agent, ready to use with no setup. It works on your behalf, borrowing your permissions — so it sees exactly what you can see, and a colleague asking the same question gets an answer from their access, not yours. Your chats with it are private too: everyone shares the same built-in agent, but nobody can see anyone else’s chat history, and there’s no setting to change that. It has no triggers, access, or model settings of its own, and it can’t use email or calendar accounts — those connect to a custom agent. What you can change is your own instructions, and whether a chat can search the web. If you want shared behaviour, permissions of its own, or an agent that runs automatically, create a custom agent instead. If you’d rather work in Claude, ChatGPT, or another AI tool, the Superthread MCP server does much the same job — it connects those tools to your workspace and, like the built-in agent, acts as you with your own permissions.
Your workspace also has a built-in Superthread Forms agent, used by the forms portal to help people find and fill in the right form. It doesn’t respond to mentions.

​
Your instructions

You can tell the Superthread Agent how to work with you — how to address you, what to know about you, and how to format its replies. Open a chat with it and click the Settings icon in the chat header to open Your instructions, then write them like any other page. Changes save automatically.
  • They’re private to you. Only you can see your instructions, and you have a separate set in each workspace.
  • They apply to new chats. Start a new chat to try out a change.
  • They only shape your own chats with the built-in agent. They don’t affect anyone else’s chats, and they don’t apply to custom agents, which follow their own instructions.
  • They change style, not the rules. Your instructions can set the tone and format of replies, but they can’t change what the agent is allowed to do or when it has to ask for approval.
If you haven’t written any, the agent uses its default tone. Only the first 8,000 characters are used, so keep them to what matters. You can also just tell the agent in a chat — “remember I prefer bullet points”, for example. It proposes an update and shows you the exact new text in an Update your instructions card. Click Approve to save it, or Cancel to leave your instructions as they were. It only changes your instructions when you ask.

​
Arranging your sidebar

The Superthread Agent can rearrange your sidebar for you. Describe how you work and it makes the change straight away, while you watch:
  • “I only work on this board” favourites the board at the top of your Favourites and hides everything else in the sidebar except Favourites.
  • “Focus mode” hides the sidebar.
  • “Make my sidebar wider” or “narrower” changes its width.
  • “Show everything again” brings back the default sidebar, and keeps your favourites.
It can also add favourites, create favourites folders, and move favourites into them. It never removes your other favourites without asking first. Each change gets a one-line reply saying what changed. If you don’t like it, ask it to undo, and it puts things back.
This only works in your own chats with the built-in Superthread Agent. Custom agents, mentions, and triggered runs can’t change anyone’s sidebar.

​
Working on notes and note templates

Open a saved note or saved note template and use the agent composer beside it. The subject chip identifies the exact note or template the chat is about. A new chat follows the item you have open; once you send a message, that chat keeps its subject even if you navigate elsewhere or reopen the chat later. Start a new chat to work on another item. On a note, ask the Superthread Agent to revise the enhanced notes with instructions such as “Group the actions by owner.” Asking it to use a different template regenerates an enhanced version from the original notes and transcript. The result streams into the note editor, and completion confirms it has been saved. A failed enhancement keeps the previous saved version. On an owned template, ask it to edit the meeting context or ordered sections. The updated template affects later enhancements; applying it again to an existing note is a separate request. The built-in agent uses your permissions. Only a note’s owner can revise or re-enhance it, and only a template’s owner can edit that template. Custom agents with a note read grant can read the note but cannot edit it or observe its enhancement operation. Shared or built-in templates you do not own remain read-only. The same operations are available through MCP and the CLI.

​
Custom agents

A custom agent is one you build yourself, for the work your team actually does. Unlike the built-in agent, it’s a first-class member of your workspace with its own identity:
  • It acts as an independent user, so it appears as a member of spaces and shows up as the actor on the work it does — you can see at a glance which card an agent updated or which comment it wrote.
  • It has its own list of spaces, with its own role in each, so what it can reach is set once and applies to everyone who uses it. It does not borrow the permissions of whoever asked.
  • It has its own instructions, model, and triggers.
That independence is what makes custom agents useful for repeatable work: a triage agent, a release-notes writer, a standup summariser. Everyone gets the same behaviour from it, and it can run when nobody is watching.
Acting as an independent user doesn’t mean taking up a seat. Custom agents are never billed as workspace members, however many you create — the only thing they cost is the AI credits their runs consume.

​
Creating a custom agent

Open Agents in the sidebar and click Create an agent. Superthread creates the agent straight away with a placeholder name, such as “Super Owl”, adds it to your favourites so it shows in the sidebar’s Agents section, and opens its chat with the settings beside it. Type to rename it. From there you can fill in:
  • Name and icon – how the agent appears in mentions, in the sidebar, and as the actor on its work. Edit them at the top of the agent’s chat.
  • Description – a short blurb shown in the agent’s chat view, so people know what it’s for.
  • Instructions – what the agent should actually do (see below).
  • Triggers – when it should run without being asked.
  • Access – what the agent can reach in your workspace and on the web.
  • Model and effort – which model it runs on and how hard it thinks.
You can also just ask the built-in Superthread Agent to do it. Tell it what you want an agent for and it can create one, and it can update your existing agents too — handy for tweaking instructions or adding a trigger without opening the settings yourself.

​
Agent settings

To change an agent, open its chat and click the Settings icon in the chat header. Instructions sit at the top. Everything else is grouped into cards, each with an icon and a one-line subtitle:
  • Triggers – when should this agent run?
  • Workspace and internet access (internal users) – what can this agent access?
  • Email and calendar – let this agent read a mailbox and work with your calendars.
  • Websites and apps (external users) – let people chat with this agent through a chat bubble on your website or in your app. See Publish an agent. Only shown to workspace owners and admins, and to people with Full access to the agent.
  • Model – the AI model this agent uses, and how hard it thinks.
  • Activity – changes to this agent, and who made them.
Cards stay closed until you open them, with a short summary beside the title, such as how many triggers are on or how many spaces the agent can reach. Hover the ? next to a card’s title for what it covers and how it’s set up. A card opens by itself when something needs your attention — for example, when the agent can’t access anything, or a trigger won’t fire. Instructions save as you type. Other changes wait until you click Save changes at the top of the panel.

​
Instructions

An agent’s instructions are its standing brief — the description of its job that it reads on every single run. This is where the agent’s real behaviour lives, so it’s worth spending time on. Instructions are stored as a page, which means you edit them in the normal Superthread editor with full formatting. Edit them in the Instructions section at the top of the agent’s settings, or click Open page there to open them as a page in their own right. You don’t have to write them from scratch. Ask the built-in Superthread Agent to draft or refine them — tell it what you want the agent to do and it will write the brief. Good instructions usually cover:
  • What the agent is responsible for, and what it should leave alone.
  • The steps it should follow, in order.
  • The format you want its output in.
  • The edge cases where it should stop and ask rather than guess.
You need Can edit access to an agent to change its instructions.

​
Model and effort

Each custom agent picks its own model, from both Anthropic (Claude) and OpenAI (GPT), in the Model card. Alongside the model you choose an effort level, which controls how much the model thinks through a task before answering:
  • No thinking – fastest and cheapest, best for simple, mechanical work.
  • Low through Max – progressively more deliberate multi-step reasoning.
  • The level marked (Default) is the model’s own default. Choosing it keeps the agent on whatever that model defaults to.
More thinking gives better results on complex work and costs more credits, so match the level to the job. A summariser rarely needs more than low; an agent that plans work across several boards benefits from more.
If you switch to a model that doesn’t support the effort level you’ve chosen, Superthread automatically uses the closest level that model does support. Models with no effort levels don’t show the setting at all.

​
What the agent can access

This is the “what can this agent reach?” side of an agent, configured in the Workspace and internet access (internal users) card. It covers the spaces the agent works in, your notes, the web and, if your workspace uses it, the forms portal. Only people with Full access to the agent can change its spaces and web access. Spaces are chosen one at a time. An agent can only reach the spaces listed here — click Add space to pick them. For each space, choose what the agent can do there:
  • Viewer – can read, but never create or change anything.
  • Editor – can create and change things in that space.
A space you add starts as Viewer, so change it to Editor where the agent needs to write. Remove a space with the × beside it. Private and view-only spaces are marked with their usual icons. If an agent has no spaces and no notes, it can’t reach anything at all; Superthread warns you, and the card opens so you can see it.
Agents set up before per-space access may still show All open spaces (or All spaces) in the card’s summary. They keep that access until someone with Full access saves the agent’s settings — saving limits the agent to the spaces listed, so add every space it needs before you save.
This is separate from the built-in Superthread Agent, which has no access of its own — it always acts with the permissions of whoever is talking to it.

​
Your notes

Add my notes, under My notes in the access card, gives a custom agent access to your own notes — the ones under My notes, including private ones. It’s what makes an agent that files actions from your meetings possible, and it’s the only way an agent can be set to run when a note is enhanced. Three things make this different from adding a space:
  • You’re granting your own notes, nobody else’s. The grant covers your notes only. It never reaches another person’s, whatever access they have to the agent.
  • A custom agent can read your notes, never change them. Only you can revise or re-enhance a note, through the built-in Superthread Agent acting as you.
  • The grant stays yours. You can withdraw it at any time with Remove my notes in the agent’s Share menu, even if you can’t otherwise edit the agent. People with full access can also remove it.
Superthread asks you to confirm before the grant is added, because of what it means once the agent is shared — see what sharing means for your private things.

​
Show on forms portal

If your workspace uses the forms portal, the access card also has a Sharing section with Show on forms portal. Turn it on and anyone in the workspace, guests included, can chat with this agent on the forms portal. Only people with Full access to the agent can change it. This is different from publishing an agent, which puts it on your own website or app for people outside your workspace.

​
Web access

By default an agent only knows what’s in your workspace. Web access lets it look outside — useful for an agent that researches competitors, checks a vendor’s docs, or summarises a page someone linked in a comment. Turn on Search and read the web, under Web in the access card, and the agent gains two abilities together:
  • It searches the web itself when a question needs something your workspace doesn’t hold.
  • It reads pages linked in the conversation — a URL you paste, or one it found while searching.
Answers built from the web are cited: each passage shows the source it came from, so you can check a claim rather than take it on trust.
Web searches cost AI credits on top of the normal cost of a run, charged per search. Reading a linked page adds no separate charge beyond the page’s own length.

​
Limiting which sites

Sites decides where the agent may go:
  • Any site — no restriction.
  • Only these sites — an allowlist: those sites and nothing else.
  • Every site except these — a blocklist: anything but those sites.
Enter one domain per entry, with no path — example.com, not example.com/docs. Subdomains are included automatically, so example.com also covers docs.example.com. You can paste a full URL and Superthread will keep the domain and drop the rest. The list covers searching and link-reading alike; an agent can’t reach through one what it’s blocked from on the other.
The two modes are opposites, and switching between them keeps the domains you’ve already typed. A list that meant “only these” becomes “everything except these”, so re-read it after you switch.
If you choose Only these sites and list nothing, the agent can’t reach the web at all — Superthread warns you when that happens. Links to your own Superthread cards and pages are a special case: rather than fetching them from the public web, where they’d be just a sign-in page, the agent opens them through its normal workspace access. So a linked card is subject to what the agent can access, exactly like any other card it reads.

​
Web search in a chat

The built-in Superthread Agent has no Web access setting. Instead, you choose for each chat: in a new chat with it, click the Web search globe in the message box before you send your first message. Once you’ve sent it, the choice is fixed for that chat — start a new chat to change it. Web searches are charged in the same way as for custom agents.

​
Email and calendar

Web access lets an agent read the open web. The Email and calendar card lets it work in mail and calendar accounts you connect to it — reading mail, drafting replies, finding a free slot, moving a meeting. You can connect Gmail and Google Calendar accounts, and Outlook mail and Outlook Calendar from a Microsoft account. Each account is set up per agent: connecting an account to one agent doesn’t give it to any other. The built-in Superthread Agent can’t use email or calendar accounts, so to work in your inbox or calendar, connect them to a custom agent.

​
Connecting an account

Open the Email and calendar card. Under Email, choose Connect Gmail or Connect Outlook; under Calendar, choose Connect Google Calendar or Connect Outlook Calendar. Sign in and grant access. The account then appears in the list with its provider’s logo, its address and its current state, and the card shows as Connected. Outlook accounts also show whether they’re a work or school account or a personal one. You can connect more than one account to the same agent, mixing providers if you like. A mail account that’s already been connected can be added to another agent with Give agent access, without signing in again.
Connecting your account to an agent other people can use lets them act through it. Superthread asks you to confirm before you connect to a shared agent — read what sharing means for your private things first.
Some work or school organisations only let people connect apps their Microsoft administrator has approved. If Microsoft says you need admin approval when you connect Outlook, ask your organisation’s Microsoft administrator to approve Superthread, then try again.

​
What the agent may do

Reading is always included: the agent can read and search connected mail, and read events and availability on connected calendars. Everything that changes something is off until you turn it on. For an Outlook account, turning on a permission can need one more sign-in to Microsoft. When it does, a Grant permission button appears beside it. Require confirmation is on by default and is the safety net under all of it: the agent stops before it acts, shows you the actual email or event change it wants to make, and does nothing until you approve. Turn it off only for an agent whose work you’re happy to have happen unattended. Only the person who connected an account can change what it allows. Anyone else managing the agent sees the settings but can’t edit them.

​
Choosing calendars

An account usually holds several calendars. After connecting, pick which ones the agent can see, and mark one as the default — the calendar it books into when you ask for an event without saying where. The default has to be one of the calendars you’ve selected, and can’t be removed while it holds that role.
With a personal Outlook account, the agent can’t see other people’s availability — only the calendars you choose.

​
Running on mail and events

As well as answering you in chat, these agents can run on their own:
  • An Email trigger runs the agent when a connected account receives or sends mail, or when a chosen Gmail label or Outlook category is applied.
  • A Calendar trigger runs it when events change, on whichever of the selected calendars you choose. Filters narrow this down — all-day events can be included, excluded or required, and you can restrict it to events you’ve accepted or declined.
Set both up under triggers, alongside the schedule and event triggers an agent already has.

​
Testing and disconnecting

Test in chat opens a conversation with the agent so you can check the connection does what you expect before you rely on it. If access is withdrawn — you revoke it in your Google or Microsoft account, or a password change invalidates it — the account shows as no longer connected and the agent stops using it. Reconnect restores it. Disconnect removes the account from that agent; it doesn’t touch your Google or Microsoft account, delete any mail or events, or affect any other agent using it.
This is not the same as the calendar you connect for meeting notes. That one is yours, read-only, and only used to show your upcoming meetings. The calendars here belong to the agent and can be written to.

​
Who can use the agent

Sharing is the other axis: not what the agent can reach, but who is allowed to use it. Click Share in the agent’s chat header to set this. General access is the workspace-wide default for Everyone in the workspace, applied to everyone who hasn’t been given something more specific:
  • No access – the agent is private to the people you name.
  • Can use – anyone in the workspace can view and run it.
  • Can edit – anyone in the workspace can also change its settings.
People with access grants individuals more than the default:
  • Can use – view the agent and run it.
  • Can edit – also change its settings and instructions.
  • Full access – also manage sharing, other people’s access, and the agent’s access to spaces and the web.
A person’s effective access is whichever is higher, their own grant or the workspace default — so a personal grant can only ever raise access, never take it away. Full access is only ever granted to named people, and an agent must always keep at least one person with full access. Sharing only covers people in your workspace. To let people outside it chat with the agent on your website or in your app, publish it. To let guests chat with it on the forms portal, use Show on forms portal.

​
Who can see the chats

By default, people see their own conversations with an agent. You can widen that with Can view everyone’s chats, either for a specific person or for everyone in the workspace. Full access always includes it.
This applies to custom agents only. Chats with the built-in Superthread Agent are always private to the person who had them.

​
What sharing means for your private things

An agent can hold things that belong to one person: a private space, a grant to someone’s notes, a connected mail or calendar account. Sharing the agent shares the use of those things, and this is the part worth being deliberate about. Anyone who can use the agent can use what it holds. They can’t open your notes or your inbox directly, and they won’t see them listed anywhere — but they can ask the agent, and the agent will answer from them. An agent with your notes will summarise them for a colleague who asks. An agent with Send email turned on will send mail from your address when someone else tells it to. Superthread warns you on the Share menu when an agent holds private content, but the judgement is yours. Connecting is personal; using is shared. Only you can connect your mail or calendar account or grant your own notes, and only you can change what a connected account allows — anyone else managing the agent sees those settings but can’t edit them. What they can do is run the agent. You can always withdraw. Disconnect an account, or remove your notes grant, and the agent loses that access immediately. Your notes grant is yours to remove whatever your access to the agent itself. Disconnecting an account affects that agent only — not your Google or Microsoft account, and not another agent you’ve connected the same address to. Requiring confirmation limits the damage. With Require confirmation on, nothing leaves the agent unseen: it shows the email or the calendar change and waits for approval. Leaving it on is the difference between a shared agent that drafts on your behalf and one that acts on your behalf.
If an agent needs your private things but the work doesn’t need to be shared, leave General access at No access and name the few people who should have it. Keeping the agent narrow is easier than keeping track of what a workspace-wide agent might be asked.

​
Running an agent

There are four ways an agent runs.

​
Chat

Open the agent from the Agents section in the sidebar, or from Agents, and start typing. Your conversations are saved under the Chat tab at the top of the sidebar, where you can group them by agent or by time and pick a thread back up later.

​
Mentions

Type @ and the agent’s name in a comment, and the agent will run and reply in the thread — the same way you’d mention a colleague. This is the quickest way to pull an agent into work that’s already happening: ask it to summarise a long discussion, draft acceptance criteria, or pick up a card. Mentions can be turned off per agent, with the When agent is mentioned toggle in the Triggers card, if you’d rather it only ran on demand or on its triggers.

​
On a schedule

Click Add trigger in the Triggers card and choose a Recurring trigger to run the agent at a set time. Pick the days of the week, the time, and the timezone, and write the prompt the agent receives when it fires. A daily digest, a Monday morning sprint check, an end-of-week summary.

​
On a workspace event

Event triggers run the agent when something happens. Add them with Add trigger in the Triggers card. You can trigger on:
  • Comments – on a card, a project, or a page. You can narrow this to any card in a specific board, sprint, or roadmap.
  • Cards moving – a card added to or removed from a board or sprint, or an epic added to a roadmap.
  • Card properties changing – status, assignees, priority, tags, sprint, project, due date, start date, estimate, board, or list. You can watch one specific property and only fire when it changes to particular values.
  • Content being added – a page or board added to a space.
  • Form submissions – when someone submits a specific form, or any form.
Each trigger carries its own prompt, so one agent can behave differently depending on what woke it up. Triggers can be enabled and disabled individually from their toggles in the Triggers card.

​
Disabling and archiving

Both live in the ••• menu in the agent’s chat header. Disabling an agent stops it running at all — it can’t be chatted with, mentioned, or triggered — while leaving everything about it intact. Only the agent’s owner can re-enable it. Archiving hides the agent and its runs, and disables its triggers. Archived agents aren’t gone: filter the agents list by Archived to find them, and restore an agent to bring it and its runs back.

​
Seeing what an agent has done

Every run is recorded, and each one shows where it came from — Chat, Mentioned, or Triggered. Because a custom agent acts as itself, its work is attributed to it throughout the workspace, so you can trace any change an agent made back to the run that made it. Changes to the agent itself — its settings, access and triggers — are listed in the Activity card in its settings, with who made them.

​
Best practices

  • Give the agent the narrowest access it needs. Add only the spaces it works in, start them as Viewer, and change a space to Editor only when the agent genuinely needs to write there.
  • Be specific in the instructions. Vague briefs produce vague work. Say what “done” looks like and what format you want.
  • Start with mentions, then automate. Use the agent by hand until its output is consistently right, then add a trigger.
  • Match effort to the task. Don’t pay for deep reasoning on work that doesn’t need it.
  • Keep web access as narrow as the job allows. Turn it on only for agents that need outside information, and prefer an explicit list of sites over the open web — it costs less and keeps the agent reading sources you trust.
  • Give triggers focused prompts. A trigger prompt that says exactly what to do with the thing that just changed beats a general-purpose one.
  • AI credits – what agent runs cost, and how to see where the spend is going
  • Publish an agent – put a custom agent on your website or in your app for people outside your workspace
  • MCP – connect Claude, ChatGPT, and other AI tools to your workspace
  • Mentions – how @ mentions work elsewhere in Superthread
  • Forms – the forms portal and its built-in agent
  • Sidebar – customise your sidebar, or ask the Superthread Agent to do it
  • Spaces – how space membership and visibility work
  • Calendar integration – the read-only calendar connection used for meeting notes
  • Plans and billing – workspace plans and billing