citegeist

Install

Install citegeist

citegeist runs on Macs with Apple Silicon. The installation takes six steps in the Terminal, and each step tells you what you should see.

or let your agent do it
  1. 01

    Open the Terminal

    Press Cmd and Space together, type Terminal and press Return. A window with a blinking cursor opens. You paste every command of this guide there and press Return after each one.

    If something goes wrong
    Spotlight does not find Terminal.
    Open Finder, go to Applications, then Utilities, and double-click Terminal.
  2. 02

    Install uv

    citegeist uses uv to set up the Python environment that converts your PDFs into text. If you use Homebrew, take the first command, otherwise the second.

    With Homebrew

    $ brew install uv

    Without Homebrew

    $ curl -LsSf https://astral.sh/uv/install.sh | sh

    You should see

    $ uv --version
uv 0.x.y
    If something goes wrong
    zsh: command not found: brew
    Homebrew is not installed. Use the command without Homebrew.
    zsh: command not found: uv, right after the installation
    Close the Terminal window and open a new one, so that it picks up the new path.
  3. 03

    Install an agent and log in once

    The chat in citegeist runs on a command line agent that you are logged in to, on your own subscription. Claude Code is the example here. Codex and Cursor work the same way.

    Install Claude Code

    $ curl -fsSL https://claude.ai/install.sh | bash

    Start it and log in

    $ claude

    You should see

    claude opens a login page in your browser. After the login, type /exit to leave Claude Code.
    If something goes wrong
    You would rather use Codex or Cursor.
    Codex: npm install -g @openai/codex, then codex login. Cursor: curl https://cursor.com/install -fsS | bash, then cursor-agent login.
    zsh: command not found: claude
    Open a new Terminal window and try again.
  4. 04

    Install citegeist

    This command downloads the latest release, checks its checksum, copies citegeist.app to your Applications folder and links the cg command. Run it again later to update.

    $ curl -fsSL https://citegeist.si/install.sh | sh

    You should see

    Looking up the latest citegeist release ...
Downloading citegeist v0.x.y ...
sha256 verified.
Installing to /Applications/citegeist.app ...
citegeist v0.x.y is installed.
Linked /Users/you/.local/bin/cg to the cg command of the app.
    If something goes wrong
    install: citegeist needs a Mac with Apple Silicon (arm64).
    citegeist runs on Macs with an M1 chip or newer. Intel Macs are not supported.
    install: could not read https://api.github.com/...
    GitHub could not be reached. Check your internet connection and run the command again.
    install: sha256 mismatch
    The download was damaged, and nothing was installed. Run the command again.
  5. 05

    Add the cg command to your path

    You only need this step if the installer ends with the line “/Users/you/.local/bin is not on your PATH”. The app works without it. The cg command is for agents and for the Terminal.

    $ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

    You should see

    $ which cg
/Users/you/.local/bin/cg
    If something goes wrong
    cg is still not found.
    Open a new Terminal window. The change applies to new windows only.
  6. 06

    Open citegeist and add your first paper

    The installer opens citegeist when it is done. Choose New library and pick an empty folder, for example Documents/Research. Then drag a PDF into the window, or paste a DOI into the field at the top.

    If something goes wrong
    macOS says the app cannot be opened.
    This happens when citegeist.app was downloaded in the browser. Install it with the command from step 4 instead, which replaces the copy.
    The chat says it has no agent.
    Open Settings in citegeist. The list of AI backends shows whether your agent was found and what is missing.

First steps

The first ten minutes in the app

Add a paper

Paste a DOI, arXiv link, ISBN or URL into the field at the top of the library, or drop a PDF into the window. The bar at the top right shows the conversion.

Read and quote

Open the paper and switch to Read. Select a passage and choose Quote. The quote card appears in the right column with its page number.

Write a text

Create a project, open Texts and choose New text. Type [@ to cite a source or one of your cards.

Export

The export bar of the text writes a Word file, a LaTeX project for Overleaf, a PDF or Markdown into the exports folder of the project.

The documentation covers every screen of the app.