Assistants and Pangur

An assistant is an AI client outside Pangur that you connect to your Pangur account. Claude and ChatGPT are assistants in this sense, and so is a coding agent such as Claude Code. Pangur runs an MCP server for them (MCP, the Model Context Protocol, is the standard these clients use to call outside tools), and once connected an assistant can search your library, read your sources, look at manuscript leaves, and add references, notes, documents and other material through the server's tools.

This page explains the rules that govern a connection. The steps for setting one up are in Connect Claude, ChatGPT or a coding agent, and every tool is listed in the MCP tools reference.

The three parties in a connectionCopy Anchor Link

When you ask a connected assistant a question, three parties share the work. You ask the question or set the task, in Claude, ChatGPT or your terminal. The assistant's own model decides which Pangur tools to call, reads what they return, and writes the answer. Pangur's server runs each tool call: it searches your library, returns passages and metadata, detects the lines on a manuscript leaf, looks up a DOI in an outside catalogue such as OpenAlex, or saves whatever the assistant asked it to save.

Pangur never runs its own language or vision model during an assistant's tool call. Where a tool would use a model elsewhere in Pangur, over MCP it returns the material and some instructions instead, and the assistant's model does the reading. ask_library, for instance, returns ranked passages and leaves the assistant to write the answer, and summarise_item returns instructions for paging through the work so that the assistant can write the summary itself and save it as a document. This arrangement decides who pays for the work, which is the subject of Who pays for an assistant's work below.

The project and collection an assistant seesCopy Anchor Link

A connection belongs to your Pangur account, the one you sign in with when the assistant asks you to authorise it, rather than to any one project. Each tool call works in your default project, which is the project you opened last on any device. Project settings carry a note reminding you of this.

An assistant can work in another project by naming it. The list_projects tool returns your projects with their ids and addresses, and every other tool, apart from the five exceptions listed in the MCP tools reference, accepts an optional project argument that takes either. In practice this means you can say "work in my Huguenot letters project" and the assistant passes that project along with each call. What a project holds is explained in Projects and libraries.

Scope to one collectionCopy Anchor Link

The owner of a project can limit assistants and the command line to one collection in it. In the project's settings, Scope to collection: offers Whole library or one of the project's collections. While a project is scoped, searches and lists return only what is in that collection, any top-level items, notes and links the assistant creates are filed into it, and a request to read a single item outside the collection, or to write into another collection, is refused with a message saying the target is outside the connection's collection scope.

Because the scope is a setting of the project rather than of a particular connection, it applies to every assistant, and to the pangur command, whenever they work in that project.

What an assistant can and cannot changeCopy Anchor Link

Assistants can add to your library, but they cannot edit or delete what is already in it. They can create references, attach files and links, add notes, create collections and add items to them, start documents and exhibition drafts, record answers in your Ask conversations, mark passages, and save transcriptions. They cannot change an item's metadata, take an item out of a collection, delete a note or a file, or overwrite a document. A few tools do record choices in Pangur's own structures, such as the values on an arrangement node or which copy is a resource's reading copy. The MCP tools reference says what each tool writes.

When an assistant revises something, Pangur keeps the earlier state. append_to_document saves a new version of a document and leaves the previous versions readable. revise_tei_text adds a revision to a TEI text and keeps the original and every earlier revision. When an assistant saves a reading of a manuscript leaf that already has text, Pangur first saves the existing transcription as a version, and any line an editor has corrected keeps the editor's reading rather than the assistant's.

If an assistant tries an operation that would edit or delete, Pangur refuses it and tells the assistant that editing and deleting are not available to assistants. To make such a change, use the web app or the command line, both of which have the full set of operations.

Marks and Ask answers labelled as the assistant'sCopy Anchor Link

An assistant cannot make highlights in your sources. When it points at a passage with mark_passage, the mark appears in the reader in a layer of its own beside your highlights, labelled with the assistant's name. You can keep a mark, which turns it into one of your highlights, or dismiss it, and the assistant cannot change or remove a mark once it has made it. The layer itself is described in Highlights, notes and assistant marks.

In the same way, an answer that an assistant adds to one of your Ask conversations with record_ask_turn appears in Ask, on the web and on your phone, beside Pangur's own answers and labelled with the name of the assistant that wrote it. The name is the one the assistant's client reports when it connects, such as "claude-ai" or "claude-code".

Exhibitions stay draftsCopy Anchor Link

An assistant can start an exhibition draft and add sections and blocks to it, including text, quotation, document, IIIF, bibliography and table blocks. It cannot publish or unpublish an exhibition, apply a design, or place image, gallery, audio or video blocks. You review the draft and publish it yourself, as described in Make an exhibition.

Viewers in organisation projectsCopy Anchor Link

In an organisation's project, an assistant acts with whatever role you hold there. If you are a viewer, every tool that changes the shared project is refused, with the same message you would see in the web app: viewers can read, ask and export, but not change the project. Four tools that add something of your own stay open to viewers, as they do in the web app: create_document, append_to_document, summarise_item and temporary_page_link. Organisation projects are not offered on every account or deployment; see Work in an organisation.

Your Zotero account is not written toCopy Anchor Link

Every write goes to Pangur's own library. A zotero.org account you connected in order to import from it is a read-only source for that import, so an assistant cannot write to it.

Who pays for an assistant's workCopy Anchor Link

Because Pangur runs no model of its own during an assistant's tool call, the model cost of the work stays with the assistant's provider and with your plan there, and none of it uses your Pangur allowances. An answer the assistant writes from ask_library does not count as an Ask question on your Pangur plan, and record_ask_turn stores that answer without counting it either. Assistant tool calls add nothing to the daily model limits shown on your usage page, because no Pangur model call is made.

Pangur's server still does work of its own that is not model use: it searches the library's text, computes search vectors on its own servers, detects lines on a manuscript leaf, and queries outside catalogues. Some tools also return material that Pangur's model wrote earlier, outside the assistant's session, such as library map entries, and reading that material costs nothing.

Other limits do apply to assistants, such as file sizes, the number of files in one upload and the pace of citation scans. They are listed under Limits for assistants. For the whole picture of which actions use Pangur's model and whose allowance pays for them, see Models, assistants and who pays.

Library text as dataCopy Anchor Link

Your library contains text that other people wrote: articles, transcriptions, web pages, notes from collaborators. Pangur's server tells every connected assistant that this text is data to quote, summarise and cite, not instructions to follow. In particular, it tells the assistant not to send library text to an outside address (with scan_references, attach_link or request_ingest_urls), change an exhibition, or write to the library unless you asked for that in your own words.

This instruction reduces the risk that a document in your library steers the assistant, but it cannot guarantee how a third-party model behaves. Read what an assistant proposes to add before you rely on it, and if a project holds material you would rather the assistant did not read, keep it scoped to a collection.

Assistants compared with the command lineCopy Anchor Link

The pangur command and an assistant reach the same projects but follow different rules. The command line is a tool you operate yourself, so it can edit and delete, and its pangur ask runs Pangur's model and counts against your plan just as Ask on the web does. An assistant connection can only add, and never runs Pangur's model. Installing and using the command is the subject of The command line.