Poiesis

A local Overleaf, with your own GitHub as the backend and an AI that fixes your LaTeX errors.

pipx install poiesis && poiesis

poiesis (ποίησις) — "to bring into existence." The act of making thought into form.

Poiesis runs entirely on your machine: a FastAPI backend and a React/Monaco frontend. You bring your own AI key, and collaboration runs through your own private GitHub repos — there is no Poiesis server, no account, and nothing to sign up for.

Status: active alpha. Everything listed under What works today is built and used daily, but APIs and UI still move quickly.

Why not Overleaf?

_{Reflects Overleaf's published free tier at the time of writing; check their pricing page for the current terms. Poiesis is not affiliated with Overleaf.}

What works today

• LaTeX editor (Monaco) with syntax highlighting, a formatting toolbar, and LaTeX-aware autocompletion — \cite{ completes from your .bib files, \ref{ from every \label{} in the project, \begin{ auto-closes its environment, and file paths complete inside \includegraphics{.
• Live PDF preview that recompiles as you type and refreshes in place.
• Inline compile diagnostics — log errors become red squiggles in the editor, and "Fix with AI" sends the error plus surrounding source to the assistant, which edits the file and recompiles until it builds.
• SyncTeX — click the PDF to jump to the source line, and vice versa.
• Swappable compile backend — Tectonic by default (auto-downloads packages, no multi-GB TeX install), with latexmk / pdflatex as a fallback.
• AI assistant — an in-app chat that reads and edits files in your project. Bring your own endpoint: save as many OpenAI-compatible connections as you like (hosted gateways, a lab server, or Ollama / LM Studio / llama.cpp running locally with no key at all) and switch between them. The model list is read from the endpoint itself, and the assistant is scoped to workspace tools rather than a raw shell.
• Three privacy stages for what the assistant may see, shown in the chat header so you always know which one is live:
  1. Open — it reads the whole project.
  2. Selective — hide any file from its row in the file tree, or a single passage with Ctrl+Shift+H in the editor.
  3. Structure only — every word in every .tex and .bib is replaced by a meaningless one of the same length and all assets are withheld, so the model can still debug syntax, packages, references and line numbers without reading a sentence. Enforced on file reads, the file listing, the outline, compile logs and the Python tool alike. A model running locally is the only arrangement where nothing leaves your machine at all.
• Matplotlib figure builder — code-centric figure authoring with \includegraphics injection.
• Version history — commit list per project, per-file diffs, one-click restore. Works on synced projects and on local-only ones.
• Citation picker — searchable \cite insert over your .bib files; paste a DOI or arXiv link to fetch the BibTeX, append it, and cite it in one step.
• arXiv-ready export — comment-stripped sources, .bbl when present, styles and graphics only.
• Multi-file projects with a file tree and a workspace hub.

Collaboration (GitHub sync)

Poiesis uses GitHub as an invisible backend for collaboration — each project becomes its own private GitHub repo. No Poiesis servers, and every file stays on your machine.

• One-click GitHub sign-in via OAuth Device Flow — click Sign in with GitHub, authorize once, and you're connected forever. No client IDs, secrets, or config (the public client ID is embedded; nothing sensitive ships).
• Share a project to a new private repo and sync automatically in the background (pure-Python git via dulwich — no system git required).
• Invite collaborators with a github.com-style username autocomplete (type a few letters, pick from a live dropdown of GitHub users).
• See your team — collaborator profile pictures appear on each shared project card in the hub.
• Team chat per project — a sidebar chat where collaborators talk and leave comments, stored persistently as comments on a dedicated GitHub Issue in the repo (history syncs to everyone, survives restarts).
• Real-time co-editing (optional) — live cursors and shared editing via Yjs/WebRTC, end-to-end encrypted between repo members.
• Conflict resolution — a visual, per-hunk merge picker (Mine / Theirs / Both) when two people edit the same lines.

Architecture

src/poiesis/
├── web.py                    # `poiesis` entry point: serve + open a browser or window
├── server.py                 # FastAPI app: projects, files, compile, AI, sync
├── services/
│   ├── chat_service.py       # in-app AI assistant (OpenAI-compatible, stdlib urllib)
│   ├── sync_service.py       # GitHub-as-backend sync: OAuth device flow, dulwich git,
│   │                         #   collaborators, team chat (Issue comments), conflicts
│   ├── compile_service.py    # LaTeX compile pipeline
│   ├── synctex_service.py    # PDF ↔ source position mapping
│   └── history_service.py    # per-project commit list, diffs, restore
├── core/                     # compiler backends, document model, paths
├── static/                   # built frontend (generated; not in git)
└── ui/                       # legacy PySide6 desktop shell (app.py / main_window.py)

frontend/src/
├── App.tsx                   # editor shell, routing, shared state
├── Chat.tsx                  # AI assistant panel
├── PdfPreview.tsx            # live preview + inline PDF editing
├── FileTree.tsx              # project tree, context menus, drag/drop
├── latexIntelligence.ts      # completions, compile-log parsing, editor markers
├── sync/                     # GitHub sign-in, Share & Sync, collaborators
├── TeamChat.tsx              # per-project team chat panel
├── ConflictResolver.tsx      # visual per-hunk merge picker
└── realtime.ts               # Yjs/WebRTC live co-editing

Design principle: separation of concerns. The frontend talks only to the FastAPI backend over HTTP. The sync engine never imports the server (it's wired in via callables), GitHub REST/OAuth calls use only the stdlib, and git mechanics are hidden behind a small API. A legacy PySide6 desktop shell (poiesis.app) is still in the tree but the web app is the primary interface.

Requirements

• Python 3.10+
• A LaTeX engine — but you don't have to install one yourself. On first run, if nothing is found, Poiesis offers to fetch its own private copy of Tectonic (~20 MB), which downloads LaTeX packages on demand instead of installing several gigabytes up front. An engine already on your PATH — Tectonic, latexmk or pdflatex from TeX Live or MiKTeX — is used in preference and skips the prompt.
• (Optional) For the AI assistant: any OpenAI-compatible endpoint, added in-app. A hosted one needs an API key; a local runtime such as Ollama needs neither a key nor an internet connection.
• Node.js 18+ — only to develop the frontend. Installing Poiesis does not need it; the UI ships prebuilt.

Install

pipx install poiesis
poiesis

That's it — poiesis starts the server and opens the editor in your browser. The UI ships prebuilt inside the package, so Node is not required to run it. Use --port, --host, or --no-browser to change how it starts.

_{pip install poiesis works too; pipx just keeps it out of your global environment.}

As a desktop app

Prefer a real window over a browser tab?

pipx install "poiesis[app]"
poiesis --app

This uses the webview your OS already ships — WebView2 on Windows, WKWebView on macOS, WebKitGTK on Linux — so it adds about a megabyte rather than a second browser engine, and renders the identical UI. poiesis-app is the same thing without a console window, which is what you want behind a shortcut.

_{On Linux this also needs the system WebKitGTK packages (for example gir1.2-webkit2-4.1 on Debian/Ubuntu); pip cannot install those. If a window can't be opened, Poiesis falls back to your browser instead of failing.}

Run from source (development)

git clone https://github.com/tygopoodt/Poiesis
cd Poiesis
python -m venv .venv && .venv\Scripts\activate     # macOS/Linux: source .venv/bin/activate
pip install -e ".[dev]"

python dev.py        # FastAPI backend (:8000) + Vite dev server (:5173)

Then open http://localhost:5173. dev.py runs npm install on first launch. The backend API docs live at http://127.0.0.1:8000/docs.

To build the frontend into the package the way a release does:

python build_frontend.py && poiesis

A legacy PySide6 desktop shell is still in the tree: pip install poiesis[desktop], then poiesis-desktop. New features land in the web app.

Testing

pytest                                  # backend
cd frontend && npm run build            # typecheck + build

CI runs both on every push, then builds a wheel, installs it into a clean environment and checks that it actually serves the app.

Roadmap

• LaTeX-aware spell check (ignoring commands, math and preamble).
• Comments anchored to line ranges in the document.
• Zotero integration in the citation picker.
• A WYSIWYG editing mode.
• Threaded replies / reactions in team chat.
• A guided tour of the keyboard shortcuts on first run.
• Packaged installers (.exe / .dmg) via GitHub Actions.

Contributing

Issues and pull requests are welcome — the project is early enough that most things are still up for discussion. Good places to start are labelled good first issue.

License

MIT — see LICENSE.