The Agent

The Agent is an assistant that works on the book itself. The other AI Tools each do one job to one chapter; the agent takes an instruction in your own words, looks around the manuscript to work out what you meant, and does it. It can answer questions too — "which chapters never mention the narrator's sister?" is a fair request, and nothing changes when you ask one.

It is good at bounded, checkable work — a rename carried through the whole book, an audit of something you suspect is inconsistent, a first pass at an index — and it is capable of being confidently wrong. Everything it changes is kept together so you can look it over and undo it, so the way to use it is to ask, then read what came back.

Opening it

The Agent button sits in the strip down the right-hand side of the editor, below Project Settings. It opens a panel beside your chapter, and the button pulses while a request is running, so you can carry on writing in another chapter and come back to it. AI → Open Agent does the same thing, and the other entries on that menu open it with a request already sent — see AI Tools.

Type into the box at the bottom and press Send — or just Enter, with Shift+Enter for a new line.

Attaching a file

You can show the agent a picture or a document. Use the paperclip beside Send, paste straight into the box, or drag a file onto the panel — all three do the same thing, and a message can carry up to five files of 25 MB each.

There are two quite different reasons to do it, and both work:

• A picture you want in the book. "Here's the cover — put it at the front of chapter three." The agent inserts it as a figure, and you review that insertion like any other change it makes.
• A picture you want it to work from. "Match this layout in the project settings", or "the chapter openers in this book — can you get close?" Nothing is added to the book; the agent looks at the image and changes settings.

Inkwell accepts images, PDFs and text documents (.md, .txt, .html, .tex, .docx, .odt, .rtf). A PDF is shown to the agent as its first page and its text, so it works either as a design to copy or as something to read. A document is read as text — the agent can quote it and write from it, but there is nothing to insert.

A file is only stored in your book if the agent actually uses it. Attaching a picture and then deciding against it leaves nothing behind. Because storing one is a change to the book, it needs Read-write — in Read-only or Comment the agent can look at your picture and tell you what it would do with it, but not put it in.

You don't have to attach a picture at all if it is already on the web: give the agent the address instead — "put the map at https://example.com/map.png at the top of chapter two" — and it fetches and stores it for you. It can also draw one itself, which is worth asking for when what you want is a diagram rather than a photograph. Either way it arrives as a figure and is reviewed like any other change.

Read-only, Comment, Read-write

The dropdown next to Send decides how much the agent may touch:

• Read-only — it can look at the manuscript but cannot change anything. The safe way to ask questions.
• Comment — it may take a full part in the conversation without touching your text: start a thread, reply to yours, mark one with an emoji, and rewrite or withdraw what it left. Useful for a critique you want alongside the writing rather than in it.
• Read-write — it may edit, comment, and create chapters.

The setting applies to the next thing you ask, so you can drop to Read-only for a question and raise it again for the work.

A request from the AI menu can raise it for you — the Copyeditor cannot work in Read-only — and Inkwell says so when it does. That lasts until the next request from the menu; the setting you chose yourself is what that one starts from.

Watching it work

While it runs, the panel shows Working… and a row of small icons — one per thing the agent did: a chapter it read, a search it ran, a page it rendered to look at. Click any of them for the detail behind it. A rendered page shows up as a thumbnail of the page itself, so you can see what it saw. Stop ends the run; work already done stays in the book, under that reply's chip.

Sometimes it produces something for you to read rather than an edit — a summary, an audit, a list. Those appear as a full-width entry in the log with an Open button.

Citations

The agent reaches the same sources as the Insert Citation button: the citation manager you have linked under Citations and Bibliography, a DOI or a web address, and every source the book already cites. So "find a source for this claim and cite it", "check that every citation in chapter 4 still resolves", or "this work is cited twice under two different records — merge them" are all fair requests.

It prefers a source the book already uses over a fresh lookup, which is what keeps one work from appearing twice in the bibliography. Citations it inserts are reviewed like any other change it makes.

The same is true of an assistant connected from outside — see Connecting an AI assistant below.

Reviewing what it changed

The agent's edits go straight into the book. Nothing waits for your approval, and you never have to review anything — but you can, one reply at a time.

Every reply that changed the book ends with a chip: a line in the log saying what that reply did, and how many of its changes you have not looked at yet. Click a chip to open it. While a chip is open, the passages it changed are marked in the text as tracked edits, in your AI's colour, and the chip lists the chapters it touched — click a chapter's name to jump to its first change. Only one chip is open at a time, and the agent's other edits stay out of your way in the text until you open theirs.

With a chip open, review its changes the way you would a collaborator's: put the cursor in one and use Accept or Reject on the review toolbar — see Collaboration. When you have dealt with the ones you care about, Accept the rest or Reject the rest on the chip settles whatever of it is left. Changes to the book's settings or chapter order have nowhere in the text to point at, so the chip lists them with their own Accept and Reject.

The newest chip opens on its own, so the last thing the agent did is what you see marked. Click an open chip again to close it.

Accepting here is private: it means you have read the change and it is your writing now, and it settles nothing for anybody else. Your collaborators see the agent's changes as your edits rather than your AI's, marked for them only if the project marks your writing. If it does — you are on Track or Suggest in the Users panel — an accepted change goes on showing as your own tracked change, and is settled the way the rest of your writing is. See Edits the AI made.

One continuing conversation

The panel holds one conversation with the agent for each book, and it just keeps going: everything you and the agent have said about the book is still there when you come back tomorrow.

Topics, and what the agent can see

The conversation is divided into topics. The current one fills the panel; everything before it is folded under Earlier, which says whether the agent can see it:

• The agent sees a summary — Earlier is open. The agent is given a short summary of the earlier topics: what you asked, what it answered, and which chips it made. If it needs an earlier exchange word for word, it looks it up, so "undo what you did to the epigraph last week" is a fair thing to ask.
• Hidden from the agent — Earlier is closed. The agent knows only the current topic. Ask it about something from before and it will say it has no record of it; open Earlier and ask again.

Click Earlier to open or close it. The change applies from your next message, and the panel remembers it for that book. While it is closed, any chip still waiting for you to review stays in view below it. Open it and use Show earlier messages to read further back.

A new topic starts when:

• you click New topic at the top of the panel, to put the discussion so far behind you;
• you send a request from the AI menu, which says everything it needs to on its own;
• you open the panel more than an hour after your last message. Earlier then starts out closed, since coming back to a book later is rarely carrying on where you left off — open it if you are.

Within a topic, the agent does not reread every message each time, which would make each one cost more than the last. After a pause of a few minutes it works from a short summary of the topic so far instead, and looks up anything it needs word for word.

Inkdrops

The agent spends inkdrops, and spends them faster than anything else on the AI menu — it is doing more work, over more of the book. The composer shows how many you have left, with a ? beside the count that explains what they are.

When you run out, the run stops and the panel offers the ways to carry on: Upgrade Plan, Buy Inkdrops on a paid plan, and — on the Standard plan and above — Use Your Own AI Key or Connect an AI Assistant. A free plan includes no inkdrops, so the agent needs a paid plan, or your own API key saved under My Account on Standard or above.

Flag sends the conversation to us when a run goes wrong, which is the most useful thing you can do with a bad answer.

The agent can also tell us itself. When it runs into something Inkwell can't do, or a tool of ours lets it down, it sends a short description of the problem — not the conversation — and the panel shows Reported a problem to Inkwell among its steps. It still tells you what it couldn't do; the report is so we can fix it for next time. An assistant you connect does the same.

Connecting an AI assistant

If you would rather work in an assistant of your own than in this panel, you can connect one to the book directly, with the same three modes and the same way of reviewing what it did. Its edits appear in the book's agent panel as chips, like the agent's own, marked with a plug instead of a sparkle; a run of changes it makes within a few minutes of each other shares one chip.

The connection uses MCP, the Model Context Protocol. Inkwell runs the server; your assistant is the client. That means two plans are involved: Inkwell's, and the assistant's own. Not every assistant lets every plan add a server of your own, so check the line for yours before you start.

Assistant	Plan you need with that assistant
Claude	Any plan, Free included
Claude Code	Any Claude plan, or an Anthropic API key
ChatGPT	Business, Enterprise or Edu
Grok	Any plan, Free included
Gemini app	Google AI Pro or Ultra, on a personal account, in the US
Gemini CLI	Any Google account

On Inkwell's side, connecting an assistant needs the Standard plan or higher; on a plan without it, the dialog offers to change plan instead. An assistant you connected on a qualifying plan stops working if you move to one without it, and picks up again when you move back — there is no need to reconnect.

Open AI → Connect AI Assistant to set it up. A fresh agent panel offers the same thing before you have asked it anything.

For each book, a checkbox controls whether connected assistants can reach it at all, and — once that's on — a Mode dropdown appears below it, offering Read-only, Comment, or Read-write, the same three modes as the panel. Different books can be set to different modes; an assistant that can freely edit one book might only be allowed to leave comments on another. Changes take effect immediately for every assistant you have already connected — no need to reconnect.

Losing a project turns its access off with it. Whether you removed it yourself or an administrator removed you from it, your connected assistants stop reaching it from their next request, and turning it back on means being given the project again.

The Connector URL at the top of the dialog is what your assistant needs — https://inkwell.net/api/mcp. It is the same URL for every book and every connection, and it is not a secret: it grants nothing on its own, and an assistant reaches only the books you have turned on, at the mode you set for each. Copy it with the button beside it and add it in your assistant as below. Every assistant ends the same way: it sends you to an Inkwell page asking whether to let it in, and you approve.

Claude

Plan you need: any Claude plan, though Free allows only one custom connector. On Team and Enterprise, an Owner of your Claude organisation has to add Inkwell first.

On claude.ai or in Claude Desktop:

1. Open Customize → Connectors.
2. Click +, then Add custom connector.
3. Name it Inkwell, paste the connector URL, and click Add.
4. Claude sends you to Inkwell; approve access.

On Team and Enterprise, the Owner does steps 1–3 under Organization settings → Connectors → Add → Custom → Web instead. Each member then finds Inkwell under Customize → Connectors, clicks Connect, and approves access in Inkwell.

To use it in a conversation, click + in the message box, choose Connectors, and turn Inkwell on. Claude asks before it uses each tool; Allow always stops it asking.

Once it is added on the web or desktop, the Claude apps for iPhone and Android can use it too.

Claude Code

Plan you need: any Claude plan, or an Anthropic API key.

If you added Inkwell on claude.ai and you sign in to Claude Code with that account, it is already there. Otherwise, add it from a terminal:

claude mcp add --transport http inkwell https://inkwell.net/api/mcp

Then start Claude Code, type /mcp, choose inkwell, and authenticate; your browser opens Inkwell's approval page.

ChatGPT

Plan you need: ChatGPT Business, Enterprise or Edu, on chatgpt.com in a browser.

On Business, only a workspace owner or admin can set it up, and members use what they publish:

1. A workspace owner turns on developer mode for the workspace, under Workspace settings → Permissions & roles.
2. The admin turns it on for themselves: Settings → Security and login → Developer mode.
3. The admin opens Settings → Plugins (Apps in some versions), clicks + or Create, names it Inkwell, pastes the connector URL, chooses OAuth for authentication, and creates it.
4. ChatGPT sends them to Inkwell; they approve access.
5. To share it with the workspace, the admin publishes it from Workspace settings → Apps.

Each person who uses it approves access in Inkwell for themselves, the first time they do.

To use it in a conversation, open the + menu in the message box, choose Developer mode, and select Inkwell. ChatGPT asks you to confirm each change before it makes it.

Grok

Plan you need: any Grok plan, Free included. On Grok Business and Enterprise, a team admin has to add Inkwell first.

1. Go to grok.com/connectors.
2. Click New Connector, then Custom.
3. Paste the connector URL and continue.
4. Grok sends you to Inkwell; approve access.

On Business and Enterprise, the admin adds it in the xAI console instead — Grok Business → Connectors → Add Connector → Other — and each member then connects it at grok.com/connectors and approves access in Inkwell.

Connectors work on grok.com and in the Grok apps for iPhone and Android.

Gemini

Plan you need: Google AI Pro or Ultra, signed in with a personal Google account, in the US, aged 18 or over, with Gemini's Keep Activity setting on. Work and school Google accounts — Google Workspace — cannot add one, and Google lists no free-tier access.

1. On a computer, go to gemini.google.com.
2. Open Settings → Connected Apps.
3. Under Custom apps, click Add a custom app.
4. Paste the connector URL and click Next.
5. Gemini sends you to Inkwell; approve access.

After that it works in the Gemini phone apps too. Type @ in a prompt to call on Inkwell by name. Gemini asks you to confirm each change before it makes it.

Gemini CLI

Plan you need: any Google account Gemini CLI accepts.

gemini mcp add --transport http inkwell https://inkwell.net/api/mcp

Then start Gemini CLI and run /mcp auth inkwell; your browser opens Inkwell's approval page.

Other MCP clients

Anything that speaks MCP over HTTP with OAuth — a coding agent, an editor, a desktop client — takes the same URL wherever it asks for a remote MCP server. Its own documentation will say where that is; Inkwell's side of the setup is the same either way, ending in the approval screen.

Revoking a connection

Connected assistants at the bottom of the dialog lists everything currently connected, with a button to revoke any of them. A connection lasts until you revoke it, or until a year after you approved it, whichever comes first. The list only shows connections that still work, so if an assistant disappears from it, approve it again the same way you set it up.

Letting an assistant start a project

A connected assistant can also create a new project for you, without you opening Inkwell to do it. Ask for one and it picks the kind — note, article, or book — and, if you have templates, one of those; you can say which if you care.

What arrives is what New Project would have given you, and no more. A note comes with one chapter, titled the way you named the project. An article or a book comes with the template's front matter — title page, copyright, and the rest — and no chapters yet, so ask for the chapters you want and the assistant will add them.

The new project appears in your projects list straight away, and it is turned on for AI access at Read-write so the assistant can go on to write in it. That is the same checkbox and the same Mode dropdown as any other book, in the dialog above, so you can turn it off, drop it to Comment, or delete the project outright.

One thing to expect: the starting content is not marked for review the way the assistant's later edits are. It came from the template, not from the assistant, so there is nothing to accept — everything it writes after that arrives under a chip as usual.

Pictures, and why an attached one may not arrive

A connected assistant can put a picture in your book: from a web address, from a file it can read itself (a coding agent working on your machine, say), or one it draws — a diagram, a chart, a title-page ornament. Ask for it in the ordinary way and it arrives as a figure, stored in the book and reviewed like any other edit.

A file you attach in your own chat app is the one case that does not work. Claude and ChatGPT show their model a picture of what you attached, and never send the file itself anywhere Inkwell can see, so the assistant has your photograph in front of it and no way to hand it over. It should tell you so rather than quietly inventing something similar. When it happens you have two ways round it: put the picture somewhere with a web address and give it that, or attach it in the book's own Agent panel, which is holding the actual file.

A file on the assistant's own computer is different. An assistant that can run programs — a coding agent working on your machine — can send a picture straight into the book without you putting it anywhere public first. That is also what makes the next section possible.

Turning a document into a project

If the assistant runs on your computer, it can convert a document you already have — a PDF, a Word file, a folder of notes — into chapters, pictures and all.

Ask for it in the ordinary way. What happens behind the scenes is worth knowing, because it explains the one thing you have to do first: the assistant writes a small program, runs it on your file, and sends the result to Inkwell directly. Your document's words and pictures never pass through the conversation with the assistant, which is what makes converting a whole book practical rather than ruinously slow.

The book has to be set to Read-write for this, in the dialog above. There is nothing else to set up and nothing new to see there: the assistant asks Inkwell for permission to send files each time, and that permission lasts an hour and covers only the one book. If you switch the book to Read-only or Comment part way through, the transfer stops there.

A converted document arrives as one large change under a single chip, like everything else the assistant writes. It is a lot to read through paragraph by paragraph, and it doesn't need to be: you never have to review a chip, and reading the chapters as you work on them is easier than reviewing them as a wall of edits.

Two things to expect. A conversion is an interpretation, not a photocopy — headings, block quotes and captions are the assistant's reading of your document's layout, and complicated page design (multiple columns, text wrapped around pictures, tables inside tables) is where it will be roughest. And an assistant that runs only in a chat window, with no way to run programs, cannot do this at all; it should say so rather than attempting it slowly.

Keep the book open when the assistant needs to see a page

An assistant can ask what the typeset book looks like — which page a chapter starts on, how long it runs, or for a picture of a page. Inkwell answers those from the same typeset preview your own window is showing, which is why the answer comes back almost immediately.

The catch is that it needs your window. If the book isn't open in Inkwell, the assistant can't measure or picture a page, and it will tell you so rather than guess, with a link that opens the book. Everything else — reading, editing, commenting — works whether or not you have the book open. So if you've asked an assistant to tidy up your page breaks, leave the book open in a tab while it works.

A window that has the book open can still occasionally miss a request — when it is busy typesetting a large book, say. The assistant is then told no window answered, which is not the same as the book being closed; ask it to try again.

An assistant's edits save as it makes them, so they appear in your window as it works rather than all at once when it finishes. That is also how it measures its own work: when it changes a chapter and then asks how long the chapter now runs, it is asking about the version your window has just been sent, so the answer accounts for the change it has only just made.

One case surprises people. While you are looking at an earlier version of the book in History, your window does not count as having the book open — it is showing the book as it was, not as it is, so it cannot answer a question about the book as it is. An assistant that asks will be told no window answered. Come back to the current version and it can measure again.