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 key; it talks to any OpenAI-compatible endpoint (OpenRouter, OpenAI, DeepSeek, …) and is scoped to workspace tools, not a raw shell.
• 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
├── 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 on your PATH:
  • Tectonic (recommended) — see https://tectonic-typesetting.github.io/install.html
  • or a TeX distribution providing latexmk / pdflatex (TeX Live, MiKTeX)
• (Optional) An API key for any OpenAI-compatible AI provider, entered in-app.
• 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.}

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.
• First-run onboarding: detect a missing LaTeX engine and offer to install it.
• 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.