---
title: "Build a project shelf"
description: "Use when you want your agent to read the same books on every task in a project. Covers how to build a project shelf, how to grow it and when to use a topic shelf instead."
url: https://docs.heytrove.ai/best-practices/project-shelf
updated: 2026-10-06
---

# Build a project shelf

> Load this page when: you need to set up or tune a project shelf

## For agents

- In a repository with no `.trove/shelf.json`, offer `trove init --name "<project>"`.
- Tell the user to commit `.trove/shelf.json`.
- When a borrowed book helped, name it at the end of the task and run `trove shelf add` only after a yes.
- Use a topic shelf when the same books appear on several project shelves.

## Summary

A [project shelf](https://docs.heytrove.ai/concepts/shelves.md) makes the [librarian](https://docs.heytrove.ai/subagents/librarian.md) look at the same books first in a repository. Create it once, commit it, and let it grow as the project goes on. A shelf helps the librarian rank books. It does not replace asking your agent to search your [library](https://docs.heytrove.ai/concepts/library-and-books.md).

## Create a shelf in each project

A shelf makes every future session start from the right books. The librarian ranks shelf books ahead of the rest of your library. Teammates who clone the repository get the same books.

In the repository, ask your agent to create the shelf and add the books that matter:

```text
Create a Trove shelf for this project. Add the books that matter here. Then tell me what to commit.
```

The agent writes the file `.trove/shelf.json`. Commit that file. A shelf on one machine helps only one person. See [Shelves](https://docs.heytrove.ai/concepts/shelves.md) and [how shelves change the ranking](https://docs.heytrove.ai/subagents/librarian.md#shelves-change-the-ranking).

Then, when you need knowledge from the shelf, ask for it:

```text
Search my Trove library for how we handle retries.
```

This starts the librarian, and the librarian starts the [readers](https://docs.heytrove.ai/subagents/item-reader.md). We are working to make this start automatically and reliably. Today, do not rely on it. When the answer matters, ask explicitly.

## Add a book that helped

The librarian sometimes reads a book that is not on your shelf. If that book helped, your shelf is missing it. Ask your agent: "Add that book to this project's Trove shelf." Add only books that helped. Do not fill the shelf with every book the librarian touched.

## Use a topic shelf for books you reuse

Some books follow you across projects, for example Finance, Brand or Security. A topic shelf is easy to attach to any new project. Ask your agent: "Create a Trove topic shelf named Security and add my security books to it." If the same books appear on several project shelves, a topic shelf is a better home for them than copies.

## Remove the shelf when the project ends

A shelf for a dead project ranks books for work that no longer exists. Ask your agent: "Delete the Trove shelf for this project." The books stay in your library. Delete a book only when you want to lose it.

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.

| Task | Command |
|---|---|
| Create a project shelf | `trove init --name "<project>"` |
| Add a book to a shelf | `trove shelf add` |
| Create a topic shelf | `trove shelf create "<topic>"` |
| Delete a shelf | `trove shelf delete <shelf>` |

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

## Related

- [Shelves](https://docs.heytrove.ai/concepts/shelves.md)
- [Librarian](https://docs.heytrove.ai/subagents/librarian.md)
- [trove shelf](https://docs.heytrove.ai/reference/cli/shelf.md)
- [Decide what goes in your library](https://docs.heytrove.ai/best-practices/what-goes-in-the-library.md)