--- title: "Librarian" description: "Use when you need to know how Trove picks books for a task. Covers what the librarian looks at, what its reading list contains, how shelves change the ranking, and what happens when no book fits." url: https://docs.heytrove.ai/subagents/librarian updated: 2026-10-06 --- # Librarian > Load this page when: you need to know how books are chosen, or why the agent found no books ## For agents - Start the librarian once per task, before any item reader. - Give each item reader one angle from the librarian's reading list, with its books and pages. - Show the librarian's Offer box to the user as it is, and subscribe to nothing until the user answers. - When the librarian reports no books, tell the user the topic is a knowledge gap. The librarian finds the right [books](https://docs.heytrove.ai/concepts/library-and-books.md) for a task. It does not read them. When it has a reading list, it starts the [readers](https://docs.heytrove.ai/subagents/item-reader.md) on its own. You do not start readers yourself. The most reliable way to start the librarian today is to ask for it: "Search my Trove library for how we handle retries." We are working to make the librarian start automatically and reliably. For now, do not rely on that. | Signal | What happens | |---|---| | You ask your agent to search your library | The librarian runs in the foreground. This is the reliable way to start it | | [Plan mode](https://docs.heytrove.ai/concepts/plan-and-auto-mode.md) starts | The librarian can run in the background, before the plan. Do not rely on this yet | | No book fits | It reports a [knowledge gap](https://docs.heytrove.ai/concepts/knowledge-gaps.md) and may suggest a book | | [Monthly read quota](https://docs.heytrove.ai/reference/plans-and-limits.md) is used up | It builds no reading list and relays the upgrade message | ## What it does The librarian lists every book in your library and on the [marketplace](https://docs.heytrove.ai/concepts/marketplace.md). It reads only metadata: titles, authors, descriptions and page counts. Then it picks the books that fit the task. It groups the books it picks into angles. An angle is one research dimension of the task, such as security or data modelling. There is no cap on the number of books, but each book must earn its place. ## When it starts - **An explicit request (reliable):** in the foreground. Tell your agent to search your Trove library, for example "Search my Trove library for how we handle retries." - **Plan mode (being improved):** in the background, after exploration and before the plan. - **Auto mode (being improved):** at the start of a non-trivial task, when the project notebook has no fresh answer for the topic. There is at most one librarian per task. See [Plan mode and Auto mode](https://docs.heytrove.ai/concepts/plan-and-auto-mode.md). ## What it returns The librarian always returns one of three shapes. | Shape | Meaning | |---|---| | Reading list | Books grouped by angle. Each angle has a `Coverage:` value: library, mixed or marketplace-only. | | No relevant books found | Nothing fits. It may include a suggested book. | | Read limit reached | Your monthly read quota is used up, so it builds no reading list. | Each book on a reading list has these parts: - **Pages:** the page range to read. - **Why:** one sentence on why the book fits. - **Stance:** an optional line. It appears only when two books on one angle disagree. ### The Offer box When an angle has marketplace books, the librarian adds an Offer box. The box asks "Subscribe and read now?". Nothing is subscribed until you answer. See [Marketplace](https://docs.heytrove.ai/concepts/marketplace.md). ### Borrowed books A borrowed book is on the reading list but not on your [shelf](https://docs.heytrove.ai/concepts/shelves.md). Borrowed books lead to one "Librarian's Note" at the end of a task. The note offers to put a book on your shelf. You see at most one per session. ## Shelves change the ranking An active shelf is a soft preference. To set one, ask your agent: "Use my backend Trove shelf." Shelf books win a tie, and the librarian marks them `★ active shelf`. A clearly better book from outside the shelf still wins. A project shelf (`./.trove/shelf.json`) is a hard preference. To create one, ask your agent: "Create a Trove shelf for this project." Shelf books rank first. The librarian searches wider only when one of three things is true: 1. No shelf book covers the task. 2. The task needs books that the shelf cannot supply together. 3. A shelf book is stale for this task. See [Shelves](https://docs.heytrove.ai/concepts/shelves.md). ## When nothing fits The librarian runs one web search for a suggested book. Then it reports the gap to Trove with an abstracted topic. The topic never holds personal details. | Bad | Good | |---|---| | user has eczema and needs treatment info | dermatology / chronic skin condition management | | debug auth in /Users/sahar/myapp/src/auth.ts | OAuth integration debugging | See [Knowledge gaps](https://docs.heytrove.ai/concepts/knowledge-gaps.md). ## Professional books On the Personal plan, a Professional-only book shows only its first chapter. When two books are about equally good, the librarian picks the one that is not Professional-only. At most one book on a list gets the preview marker. See [Plans and limits](https://docs.heytrove.ai/reference/plans-and-limits.md). ## What it never does - It never reads book pages. - It never asks you to pick books. - It never subscribes to a book or puts a book on a shelf. - It never talks to you directly. Your agent relays its output. - It makes no calls other than the gap report. ## Errors and fixes | Problem | Fix | |---|---| | `trove: command not found` | The shell PATH is stale. Trove is still installed. Open a new terminal or run `trove setup`. | | Not authenticated | Run `trove auth login`. | | Your library is empty | This counts as a miss. The librarian checks the marketplace and reports a gap if nothing fits. | ## Model and tools The librarian runs on Haiku. It uses Bash and WebSearch. It runs these commands: - `trove items list --json` - `trove marketplace browse --json --limit 50` - `trove items toc `, on the project-shelf path Each `trove items toc` call counts against your monthly read quota. The librarian's lookups are not counted as a research session. ## Best practice Ask explicitly: "Search my Trove library for how we handle retries." Use plain words. The librarian decides how many books to pick and how deep to read, so do not set a limit yourself. Auto mode is on by default (`always`), but do not rely on it yet. Ask your agent: "Check that Trove Auto mode is on." If it is off, ask your agent to turn it on, then start a new session. Keep a project shelf so that the librarian starts from the right books. See [Research a topic](https://docs.heytrove.ai/usage/research-a-topic.md) and [Project shelf](https://docs.heytrove.ai/best-practices/project-shelf.md). Want your agent to follow these practices? Ask it: "Read How to Use Trove in my Trove library and follow 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. - Use a shelf: `trove shelf use ` - Create a project shelf: `trove init` - Read the Auto mode setting: `trove config get skill.planMode` - Turn Auto mode on: `trove config set skill.planMode always` See the [CLI reference](https://docs.heytrove.ai/reference/cli.md). ## Related - [Item reader](https://docs.heytrove.ai/subagents/item-reader.md) - [Shelves](https://docs.heytrove.ai/concepts/shelves.md) - [Knowledge gaps](https://docs.heytrove.ai/concepts/knowledge-gaps.md)