---
title: "Write a book with your agent"
description: "Use when you want your agent to write a book in your library. Covers the outline, the draft, import of a file, and how to review and edit the result."
url: https://docs.heytrove.ai/usage/write-a-book
updated: 2026-10-06
---

# Write a book with your agent

> Load this page when: you need your agent to write a book

## For agents

- Write each chapter as a short explanation, then RULE, WHY and APPLY lines for agents.
- Use one `# ` heading per chapter, because each `# ` heading starts a new page.
- Create a book with `trove items create`, or import a file with `trove items import <file.md>`.
- Edit one page at a time with `trove items put <id>:<page> --file page.md --expect-version N`.

You get a new book in your [library](https://docs.heytrove.ai/concepts/library-and-books.md) that your agent can read and cite, written from what you know or what you learned.

## Before you start

- Trove is installed (see [Install](https://docs.heytrove.ai/install.md)).
- You know the topic and who the book is for.
- For a book you already have as a markdown file, ask your agent: "Import ./notes.md into my Trove library as a book." See [trove items: write](https://docs.heytrove.ai/reference/cli/items-writing.md).

## Steps

1. **Ask for an outline first.** Tell the agent the topic. The [book writer](https://docs.heytrove.ai/subagents/book-writer.md) drafts one chapter per topic. You approve the outline before it writes.
2. **Use the chapter shape.** Each chapter starts with a short explanation for a person. Then it has a short "Rules for agents" part, so agents know what to do. Each rule is one sentence, with its reason and the action to take. The book "How to Use Trove" in your library shows this format.
3. **Write the draft.** The book writer creates the book, or imports your file. Each `# ` heading starts a new page, so keep one chapter on each page.
4. **Review the book.** Ask your agent: "Show me the table of contents of the new book." Read a few pages. Check the title and the description. The description must say when to read the book.
5. **Edit one page at a time.** The agent reads the book, notes its version, and writes only the page that changes. If someone wrote in the meantime, the write is refused. The agent reads again and redoes the edit.
6. **Set the approval rule.** Each book has its own rule. Some books the agent updates on its own. Others need your approval for every change.

## Prompt to paste

```text
Write a book on <topic> from what we learned. One chapter per topic. Each chapter has a short explanation, then a "Rules for agents" part with each rule, its reason and the action to take. Show me the outline before you write.
```

## What you will see

The book writer shows an outline of chapters and waits for your yes. Then it writes the book and reports the title and the id. To check the result, ask your agent for the table of contents. It lists one entry for each chapter. The book writer prints:

```terminal
✓ Created: <title> (ID: <id>)
```

When you ask for a change later, the writer edits the one page that changes. A refused write means nothing was written. The writer reads the book again and retries.

## After you write it

To use the new book, ask your agent explicitly: "Search my Trove library for <topic>." That starts the [librarian](https://docs.heytrove.ai/subagents/librarian.md), which picks the books and pages and starts the [readers](https://docs.heytrove.ai/subagents/item-reader.md) on its own. We are actively working on making the librarian start automatically and reliably, but today you should not rely on it.

## Direct CLI

Your agent runs these through the `trove` command. You can run them yourself in a terminal, but asking your agent is the recommended way: it picks the right flags, waits for processing and checks the result.

| Task | Command |
| --- | --- |
| Create a book | `trove items create` |
| Import a markdown file | `trove items import <file.md>` |
| Show the table of contents | `trove items toc <id>` |
| Replace one page | `trove items put <id>:<page> --file page.md --expect-version N` |

See the [CLI reference](https://docs.heytrove.ai/reference/cli.md).

## Next

- [Book writer](https://docs.heytrove.ai/subagents/book-writer.md)
- [Write books agents can read](https://docs.heytrove.ai/best-practices/write-books-agents-can-read.md)
- [Log what you learn](https://docs.heytrove.ai/usage/log-what-you-learn.md)