Openleaf Install

Openleaf Docs

Complete setup and usage reference for Openleaf, a local desktop app for writing LaTeX papers with an editor, PDF pane, project library, compile tools, and docked agent terminals.

Overview

Openleaf is built for LaTeX manuscript work. It keeps the file tree, source editor, rendered PDF, compile output, and terminal sessions in one project window.

The app is free and open source. It is designed to work with local LaTeX compilers and command-line agent tools.

Requirements

  • Node.js LTS for installing and running the app from source.
  • Git for cloning the repository.
  • A LaTeX compiler: Openleaf supports tectonic, latexmk, or pdflatex. The macOS installer installs tectonic with Homebrew if none are found.
  • Optional agent CLIs: install and sign in to Codex or Claude separately if you want those terminal profiles.

On macOS, install Openleaf first; it will provision tectonic when Homebrew is available. Source installs on other platforms should have a compiler on PATH before compiling PDFs.

Install

macOS app bundle

curl -fsSL https://alex-dils.com/openleaf/install.sh | bash

One command does everything: it installs Node.js with Homebrew if needed, installs the Openleaf CLI, builds Openleaf.app into Applications, and opens it. The installer also checks for tectonic, latexmk, or pdflatex and installs tectonic with Homebrew when none are found.

Windows

git clone https://github.com/axel-slid/openleaf.git
cd openleaf
npm install
npm start

Linux

git clone https://github.com/axel-slid/openleaf.git
cd openleaf
npm install
npm start

Prefer npm directly?

npm install -g github:axel-slid/openleaf
openleaf install
openleaf open

Source is available at github.com/axel-slid/openleaf.

Projects

The project library is the starting point for new and existing work.

  • Blank project: create a fresh workspace when you are starting a manuscript from scratch.
  • Single TeX file: import one .tex file and let Openleaf create a project around it.
  • Folder: open an existing manuscript directory with figures, bibliography files, classes, and subfiles intact.
  • Archive: import .zip, .tar, or .tar.gz packages.

Openleaf reopens projects where you left them, including the last active file and workspace layout.

Workspace

A project window is split into resizable panes:

  • Files: browse project files and switch between source, figure, PDF, and support files.
  • Editor: edit LaTeX in tabs using Code or Visual mode.
  • PDF: preview the compiled manuscript and inspect compile status.
  • Terminal: run Shell, Codex, or Claude sessions from the project context.
  • Compile log: review compiler output when a build fails or emits warnings.

Drag dividers to resize panes. Layout choices are part of your local app state.

Editor

Code mode

Code mode is the raw LaTeX editor. It includes line numbers, LaTeX syntax highlighting, wrapped lines, multiple text tabs, and a minimap for long manuscripts.

Visual mode

Visual mode presents a page-like paragraph editor for prose work. Edits still write back to the same source file, so you can switch between modes without managing a second document format.

Vim shortcuts

If enabled in settings, Vim-style navigation and editing shortcuts apply inside the text editor. Disable them from settings if you want standard editor behavior.

PDF Preview

The PDF pane shows the latest compiled output for the active project. Use Compile PDF for manual builds, or enable Auto compile so saved edits trigger a rebuild after a short pause.

Openleaf can compile with tectonic, latexmk, or pdflatex. Use the compiler that matches your project and local TeX setup.

  • If the PDF does not update, check the compile log first.
  • If a compiler is not found, verify it works from a system terminal.
  • If a bibliography or class file is missing, confirm it is inside the project folder or available to your TeX distribution.

Agent Terminals

Terminal sessions run from the project workspace, so commands and agents see the same files that are open in the editor.

  • Shell: use a normal command-line session for Git, compiler checks, file operations, and scripts.
  • Codex: start Codex in the project when you want code or manuscript edits from an agent.
  • Claude: start Claude in the project if you use Claude's CLI workflow.

Put project instructions in AGENTS.md when you want agents to follow repo-specific rules. Review agent edits before committing or submitting a manuscript.

Settings

Settings control workspace behavior and visual preferences.

  • Theme: switch between light and dark modes.
  • Compiler: choose the LaTeX engine or build command that works for your manuscript.
  • Auto compile: rebuild the PDF after edits are saved.
  • PDF rendering: adjust preview behavior for your machine and document size.
  • Editor: toggle wrapping, Vim shortcuts, minimap visibility, and other editing preferences.
  • Shortcuts: customize keyboard shortcuts for common actions.

CLI

The Openleaf CLI exposes the openleaf command after global install.

npm install -g github:axel-slid/openleaf
openleaf install
openleaf open

Use openleaf install to create the local app entry point, then openleaf open to launch it.

Recommended Workflow

  1. Install Node.js and Git. On macOS, Openleaf installs tectonic if no LaTeX compiler is found.
  2. Clone Openleaf and launch the app.
  3. Create a blank project or import an existing manuscript folder.
  4. Open the main .tex file and compile once manually.
  5. Fix missing package, figure, bibliography, or compiler errors until the PDF builds.
  6. Turn on Auto compile when the project is stable.
  7. Add an AGENTS.md file if you want agent sessions to follow project rules.
  8. Use Shell, Codex, or Claude terminals for editing, review, scripts, and Git operations.

Files and Privacy

Openleaf works with local project files. Opening a project gives the app access to that project directory so it can edit source files, compile outputs, and show assets.

Commands you run in terminals may read, write, upload, or delete files depending on the tools you invoke. Treat agent CLIs and shell commands as active project collaborators, and review important file changes with Git or your preferred diff tool.

Troubleshooting

npm install fails

Check that Node.js LTS is installed and that you are running the command inside the cloned openleaf folder.

The app opens, but compile fails

Open the compile log and look for the first LaTeX error. Then test the same compiler in a system terminal, for example tectonic main.tex or latexmk -pdf main.tex.

The PDF pane is stale

Run a manual compile. If that works, check whether Auto compile is enabled. If manual compile fails, fix the compiler error first.

Codex or Claude does not start

Install the relevant CLI, sign in, and verify the command works outside Openleaf. Then restart the app so it picks up your PATH.

An imported archive is missing files

Extract the archive manually and open the resulting folder. This makes it easier to verify nested folders, hidden files, bibliography assets, and custom classes.

FAQ

Is Openleaf free?

Yes. Openleaf is a free, open source project.

Does Openleaf replace online LaTeX editors?

No. It is a local desktop workflow for people who want direct access to files, compilers, terminals, and agents.

Can I use my existing LaTeX project?

Yes. Open a folder or import an archive, then compile the main TeX file.

Do I need Codex or Claude?

No. Openleaf works as a LaTeX workspace without agent terminals. Agent tools are optional.

Where should project-specific agent instructions go?

Use AGENTS.md in the project root.