The library

The library is Oleafly’s home screen. Every project appears as a book on a shelf, with the most recently active first, and everything you need to manage projects happens here.

The shelf

Each card shows the project’s name and cover color. The cover also says what kind of project it is: Document, Image, Diagram, or External for a folder you opened in place. Under the card are the engine (LaTeX, Typst, or Markdown) and the time of the last change. Open a project to return to its source and preview.

The buttons at the top right switch between the grid, which shows covers, and the list, which is easier to scan.

With an empty library, the welcome screen offers New project and Open a folder.

Creating a project

Click New project and choose how to start:

• Use a template for a paper, thesis, resume, presentation, or blank document. Browse the template gallery, choose a template, and name your project.
• Import a project to bring in existing files. See the import guide for each format.
• Research project to organize a research workspace with documents, sources, and tasks.

If you don’t pick a cover color, the new project gets a random one from the palette. Oleafly also records the project’s files as a first Git commit called “Create project”. See Git and source control.

You can also open the gallery from anywhere with the search omnibar: press ⌘⇧F (Ctrl+Shift+F) and type /create.

Folders opened in place

Open folder (⌘⇧O / Ctrl+Shift+O) lets you work on a folder where it already is, without copying it into the library. Builds, settings, checkpoints, and chats for that folder go in Oleafly’s own data folder, so nothing is added to yours. The folder sits on the shelf marked External, and its card tells you when the folder is missing or its drive isn’t connected.

Oleafly limits some features in a folder you open this way, such as Git, external agents, and system LaTeX through latexmk. A banner above the editor offers Trust this folder to turn them on. Trust only folders whose contents you know. Until then the folder compiles on the built-in Tectonic engine. Once you trust it, a folder with no engine of its own follows the default compile engine. External commands still need their own permission after that.

Cloud sync backs up projects in your library only, so a folder opened in place isn’t synced.

Right-click an External card to show the folder in your file manager, Copy into library to make a project you own, or Remove from Oleafly, which leaves the files where they are. You can also open folders from Finder, File Explorer, or a terminal; see System integration.

Hover previews

Hover a book and the first page of its last compiled PDF slides across the cover, so you can tell your papers apart at a glance. Previews come from the real compiled output and are cached, so the shelf stays fast.

If you’d rather not see them, turn off Preview PDF on hover in Settings → Appearance → PDF Preview.

Bookmarks

Hover a book and click its bookmark icon to bookmark the project. To show only bookmarked projects, type is:bookmarked in the search box or set Bookmark to Bookmarked in Advanced filters.

The right-click menu

Right-click any book:

• Open project
• Project details: the name, ID, engine, kind, main document, dates, and other metadata the search uses.
• Export history: the files you exported from this project.
• Project color: eleven cover swatches (Blue, Cream, Peach, Rose, Pink, Lilac, Sky, Aqua, Cyan, Mint, Spring). The color is stored in the project itself, so it travels with the project if you sync it to another machine.
• Fork project: copies the project and its full Git history into a new project. The dialog suggests <name> (copy); give it any name you like. Use a copy to try another version of a resume or paper. The copy starts with no checkpoints.
• Delete project: moves the project to the Recycle Bin, where it can be restored.

Renaming a project

Open the project and click its title in the top toolbar. It becomes editable in place: type the new name and press Enter. The rename is saved to the project’s own metadata.

Search your projects

The search box at the top of the home screen filters the shelf as you type. It uses the same syntax as GitHub’s issue and pull request search. Plain words match the project name, ID, main file, folder path, exports, engine, kind, and cover color. Qualifiers narrow the list:

Qualifier	Example	Matches
is:	is:bookmarked, is:folder, is:library, is:forked	Bookmarked projects, folders opened in place, projects stored in Oleafly, forks
has: and no:	has:preview, no:exports	Projects with or without a compiled PDF preview or exports
engine:	engine:typst, engine:latex	LaTeX, Typst, or Markdown
kind:	kind:image	Document, image, or diagram projects
color:	color:mint	Cover color, by swatch name
created:, updated:, opened:	created:>2026-01-01, updated:>@today-1w	Creation, last change, or last opened date
in:	draft in:name	Limits words to name, id, file, path, or export
sort:	sort:name-asc, sort:created	Order of the shelf

engine:latex finds every LaTeX project, whichever LaTeX engine it uses. The older engine:tectonic still works and finds the same projects.

Combine terms

The rules follow GitHub’s:

• A space means AND. Upper-case AND and OR and parentheses group terms, up to five levels deep. AND binds tighter than OR.
• Commas list alternatives: engine:typst,markdown matches either engine. Repeating a qualifier means both, so engine:typst engine:markdown matches nothing.
• A leading - excludes: -kind:image, -is:bookmarked. NOT works too, and -word leaves out projects that contain that word.
• Quotes keep spaces together: "lab notes", in:path "My Papers".

(engine:typst OR engine:markdown) is:bookmarked -kind:image sort:updated-desc

Dates and sorting

Dates take >, >=, <, and <=, ranges such as 2026-01-01..2026-03-31 (use * for an open end), and relative dates: @today, @today-7d, @today-2w, @today-1m, or @today-1y. created:>@today-1w means the past seven days.

sort: takes activity, updated, created, opened, or name, each with -asc or -desc. Without a direction it sorts descending. The default is recent activity.

Suggestions and warnings

Click the search box while it’s empty and a dropdown lists the qualifiers. As you type, it suggests qualifiers, their values, AND, OR, and Exclude. Move through it with the arrow keys and press Enter to take a suggestion. Tab or Escape closes it without taking anything.

Qualifiers and values show in color as you type. A mistake gets an amber tint and a short note saying what’s wrong: an unclosed parenthesis, say, or a value the qualifier doesn’t accept. An unknown qualifier is searched as plain text, and an invalid value is ignored.

Advanced filters

The sliders button beside the search box opens Advanced filters, with menus for Engine, Project kind, Bookmark, PDF preview, Created, Modified, and Sort by. A Location menu joins them once you have opened a folder in place. Every menu edits the search text, so the box and the panel always agree. When the panel can’t show your query as one choice, the menu reads Custom. Reset removes the qualifiers and keeps your plain words.

Search everything

The search omnibar (⌘⇧F / Ctrl+Shift+F, or Search Documents in the dock) searches project metadata and the full text of every document in every project. It jumps straight to the matching project, file, and line. Type / for scoped commands such as /projects, /docs, or /create.

The omnibar has its own simpler filters, such as name:resume or bookmark:yes. The GitHub-style syntax above belongs to the search box on the home screen.

The home dock

A small dock on the home screen collects everything that is not a project:

• New project: start from a template, import files, or create a research workspace.
• Search Documents: the search omnibar (⌘⇧F / Ctrl+Shift+F).
• Diagram Composer: the diagram composer, without opening a project first. It asks what the diagram is for: TikZ diagram, Typst diagram, or Mermaid diagram.
• Oleafly Tools: a searchable gallery of document utilities (below).
• Appearance: switch between Light, Dark, and System.
• Settings: the gear, or ⌘, (Ctrl+,), opens the full settings window.

Oleafly Tools

Turn on LaTeX tools in Settings → Experimentation to show the Oleafly Tools gallery. It holds converters between LaTeX, Typst, Markdown, Word, HTML, and images, plus reference builders, validators, research lookups, statistics calculators, and writing helpers. The Oleafly Tools guide covers each one.

Where the shelf lives on disk

Every book is a plain folder under ~/.oleafly/projects/, with a human-readable random name like flying-pink-pikachu. Nothing about the library is proprietary: see Where your data lives.

Recycle Bin

A deleted project stays in the Recycle Bin until you restore it or delete it permanently. Both actions are in Settings → Data Storage. See Storage & Recycle Bin.