Best practices
Build a project shelf
Updated 6 Oct 2026
On this page
For agents
Load this page when: you need to set up or tune a project shelf
- In a repository with no
.trove/shelf.json, offertrove 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 addonly after a yes. - Use a topic shelf when the same books appear on several project shelves.
Summary
A project shelf makes the librarian 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.
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:
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 and how shelves change the ranking.
Then, when you need knowledge from the shelf, ask for it:
Search my Trove library for how we handle retries.This starts the librarian, and the librarian starts the readers. 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.