Working with the agent

The VersoFold agent is a research and writing assistant that works through app tools. It can read relevant source, explain a paper, check references, prepare research records, help design figures and make authorized edits. Opening a conversation does not itself contact a model; sending a request starts a run.

Open Settings → AI & agent → Connections. Choose a supported provider, a compatible endpoint or an available subscription connection, then follow its setup. Model choices and capabilities depend on the configured connection. Refresh/discover models when the account's catalog changes.

Custom endpoints are Discuss-only by default unless compatible tools have been verified. Connection tests should be distinguished from a real manuscript task. VersoFold does not silently switch to another account after authentication, quota or provider failure.

Browser-mode connection secrets remain in the server session. Desktop can remember supported credentials when explicitly selected: in the Keychain on a Mac, in the desktop keyring (GNOME Keyring or KWallet) on Linux. Without a keyring, Linux asks for the key again in each session rather than writing it to disk in the clear. Credentials do not belong in manuscript files or prompts.

Select the relevant file or passage and add it to the composer. Source/Visual selections, PDF text, small text files, PDFs and compatible images can become explicit attachments. Review the context manifest to see supplied material and subsequent tool reads.

Buttons elsewhere in the app also write requests for you: Draft with agent in the Response view, Ask the agent to judge it when checking sources, Tidy with the agent when importing reviews. They open the agent with the request ready; with no model connected, it waits in the message box until you connect one and send it.

Specify the outcome and constraints. Examples:

• “Explain this equation using the notation in the methods section. Do not edit.”

• “Shorten this paragraph while preserving every number, qualification and citation.”

• “Inspect the CSV, plot mean and standard deviation across seeds, and render the figure. Ask if the grouping is unclear.”

• “Check whether the attached source supports this claim and quote the relevant passage.”

The Prompts library provides searchable starting points for reading, reviewing, reproducibility, citation checking and writing. Edit a prompt to fit the actual task before sending.

The composer shows two controls next to the model: Mode and Approval.

Edit is the default for workspace conversations. The agent can change any text file in the paper — TeX and BibTeX, scripts, data, notes, style files — create new files, move or rename them and delete them, and run commands in the paper's folder. Its scope is the whole workspace unless a request was narrowed to specific files (an inline edit of a selection, say); reaching past that asks you instead of failing. Hidden files, VersoFold's own metadata (.versofold*, comment and task stores) and credential-named files are never available to it.

Discuss is for talking the work through first. The agent reads and answers, and the edit tools stay available: the first time it reaches for one, the conversation pauses with “The agent wants to edit main.tex — allow edits in this conversation?”. Allow edits switches the conversation to Edit and the run continues; Keep discussing leaves it in Discuss, and the agent describes the change instead. Read-only companions (the reading desk and research reader) are the one place edits are really unavailable.

Plan is read-only too: the agent works out a step-by-step plan for the change without making it. Switch to Edit to carry the plan out.

Every change goes through VersoFold's journal: exact replacements check the file hash (a replacement whose passage still matches exactly once is applied even if you edited elsewhere in the file meanwhile), whole-file writes need the hash they replace, deletions go to a private trash, and commands are snapshotted before and after. Each one has an Undo in the transcript. An edit to an existing file also arrives as a tracked change in the agent's name, in its own colour: accept or reject it in the editor or in the Review tab, one by one or all of the agent's at once (the workspace setting Edits made by agents at the bottom of Review turns this off). If you are typing in a file the agent edits, it waits a moment for the autosave and otherwise your editor merges the change into your unsaved text.

Approval decides when a permitted action pauses for you:

Allow for this conversation answers for that tool until the conversation ends; Conversation actions → Ask again before allowed tools clears those answers. Approval never widens the workspace, the file scope, the library or web grants, or another conversation.

Live versus staged: a successful live edit has already changed the working manuscript; as a tracked change it stays marked until you accept or reject it, and accepting does not apply it a second time. A staged proposal (stage_source_proposal) remains separate until you accept it, for when you want to review a larger change before it lands; once accepted, its edits are tracked changes too.

The agent sees the pending tracked changes (read_tracked_changes: who changed what, where) and, in Edit mode and when you ask for it, accepts or rejects them (decide_tracked_changes), for requests such as “accept my coauthor's changes in the method section” or “reject your edits to the abstract”. A checkpoint is taken first. See tracked changes.

Besides reading, searching and editing, the agent can:

• Run commands in the paper's folder with run_command — the paper's own analysis or plotting scripts, latexmk on a supplement, data checks. Commands use your installed tools, run in a sandbox (the macOS sandbox on a Mac, bubblewrap on Linux: writes only inside the workspace, never its hidden VersoFold or git folders; no credential stores; no network unless the command asks for it and you or the verifier allow it) and report the files they changed. Longer research scripts can also run in the separate research sandbox.

• Read a file elsewhere on your computer that you name, such as a shared style file or a dataset.

• Use the rest of VersoFold through find_capabilities and use_capability: git, history and named versions, paper variants, tasks and comments, tables, page layout, rebuttal, submission rehearsal, the web edition, templates, the spelling dictionary, reference-library management, remote data, Overleaf and exports. These are the same capabilities external agents use, with the same approval and file-scope rules.

When the agent cannot do something, its message says what to do next: allow edits, allow another file, wait for your autosave, read the file again, or describe the change for you to make.

The transcript shows responses, source links, tool activity and recorded outcomes. Only reported reasoning summaries are displayed. A claim that something compiled should have an actual build result. Open the PDF when layout matters.

Use Stop to cancel ongoing work. Cancellation does not undo a completed write. Use an edit's checked Undo control while its recorded state still matches, or review the source/history when newer edits exist.

Runs interrupted by restart remain visible as interrupted; they are not silently replayed. A failed or incomplete tool response should be checked against actual state before repeating a write.

When an agent needs your approval, asks a question, or finishes, VersoFold tells you. That covers the built-in agent, a connected Claude Code, Codex or ACP chat, and an external MCP client. While VersoFold is behind other windows you get a system notification; clicking it opens the conversation, or External agents for an MCP request. In front, a bell with a count sits in the header until every request is answered, and the Dock icon shows the same count. Switch them off under Settings → General → Notifications, where Send a test notification shows one and says whether the system displayed it. If nothing appears, allow VersoFold in your system's notification settings (on a Mac, System Settings → Notifications; macOS asks once, the first time) and check that Focus or Do Not Disturb is off. In a browser, choose Allow notifications there once.

Create, rename, reopen, export or delete conversations using their controls. Deleting a conversation removes its transcript/execution history, not manuscript edits. Workspace conversations are retained in the project's hidden agent area; personal library conversations and account settings are separate.

Conversation Undo/Redo moves the active conversation boundary without changing files. Edit & retry branches before a user message and returns its text for revision. A branch preserves the original conversation. Long conversations can compact into a continuation checkpoint while retaining the complete local transcript and execution evidence. Compact also provides an explicit action.

Usage indicators show available token/context measurements. Cost is an estimate when pricing is configured, not a subscription balance. Missing usage/cost information should remain unavailable rather than being treated as zero.

Save personal or project writing preferences, reusable profiles and prompt shortcuts. Current requests take precedence over preferences. Notes the agent keeps about the paper are approved, edited and forgotten in Workspace memory; reusable procedures are written and versioned in Settings → Procedures and run from the composer's + menu with Use a procedure. See workspace memory & procedures.

Public web research is on unless you turn it off in Agent settings. Commands and research scripts follow the approval table above. Remote execution and registered MCP extensions are enabled per message from the composer's + menu and have their own prerequisites. A figure recipe is declarative data; it does not authorize arbitrary script execution. Remote commands require the configured connection, folder and executable restrictions.

Agent settings also manage persistent, budgeted read-only background questions and stopping/pausing controls. Background tasks remain bound to their declared workspace. Read-only work may run concurrently while each workspace keeps a single edit writer.

The agent knows this handbook exists, but its contents are not automatically added to every conversation. It is instructed to search/read it only when you explicitly ask for documentation or how to use VersoFold, or when it is stuck on a specific VersoFold capability needed for your task.

Ask “Use the handbook to explain how to freeze a dataset” to request a lookup. The agent can search sections and read bounded Markdown excerpts. The handbook does not replace reading your actual manuscript and does not authorize actions. See handbook access for agents.