Folio icon
Folio
A LaTeX writing workspace for DeepSeek Harness.
Source beside its PDF, with an assistant that proposes edits — and you decide.
English · 简体中文
Folio workspace: file tree, LaTeX source, typeset PDF and the Harness assistant
Folio is a DeepSeek Harness (DSH) plugin. It adds a Folio page to the Harness sidebar where you write LaTeX, typeset it to PDF, and work with an AI assistant that runs on the models you have already configured in Harness. Everything is local: manuscripts are plain folders on your disk, TeX runs on your machine, and there are no extra accounts or API keys.
Highlights
- Looks and feels like Harness. Every color, font, radius and the light/dark theme come from the host's design tokens.
- Native Harness chat. The assistant is the Harness conversation: model picker, Markdown, reasoning, tool calls and stop/queue all work exactly as in the main chat.
- Edits you review. The assistant reads your files and builds the PDF, but it can only propose changes. Each proposal opens as a diff that you apply or discard.
- Context without copy-paste. Each turn quietly tells the model which manuscript, file, cursor line and selection you are on, plus the latest build errors.
- Real TeX builds. pdfLaTeX, XeLaTeX or Tectonic, with BibTeX/Biber and reruns. Errors become a clickable list that jumps to the file and line.
- Your layout. Toggle and resize every panel. Drag the assistant by its header to pull it out into a window, resize the window from any edge or corner, and drop it on the left, right or bottom edge to dock it again.
Features
Editor
- CodeMirror 6 with LaTeX highlighting for commands, environments, math, references and citations.
\ completion. About 150 common commands and 30+ environments, with Tab stops for arguments.- Project-aware arguments.
\ref{ / \cref{ complete every \label in the project, \cite{ completes keys from your .bib files, and \input{, \includegraphics{, \usepackage{ and \documentclass{ complete files, packages and classes.
- Autosave about a second after you stop typing. Hash checks guard against overwriting changes made on disk.
- Search and replace, bracket matching, and word count (CJK-aware).
Builds
- Engines: pdfLaTeX, XeLaTeX and Tectonic; choose the main file and engine from the Compile menu.
- ⌘/Ctrl + S saves and compiles; ⌘/Ctrl + Enter compiles. Optionally compile on every save.
- The last good PDF is kept on disk and shown as soon as you open a manuscript, even after a failed build.
- Build issues (errors, warnings, bad boxes, bibliography messages) appear as a list; click one to jump to its line.
Assistant
- Each manuscript is a Harness Workspace named after its title; every conversation is a Harness Session inside it, so it also shows up in the Harness sidebar.
- The chat switcher lists this manuscript's chats. Switch between them, start a new chat, archive one, or archive all empty chats at once.
- The assistant uses a single tool,
folio_project: list and read files, compile, read the last build, and propose_patch (exact find/replace edits, or a full file).
- Writing sessions are restricted at the tool-runtime level to that tool, so the model cannot bypass review with shell or file-system tools. Your other Harness sessions are unaffected.
Reviewing a suggested edit as a diff
A suggested edit opens as a diff. Apply writes it, but only if the file hasn't changed since the suggestion was made.
Layout
Manuscript library
The library: create from the Article, Chinese (ctexart) or Blank template.
Requirements
- DeepSeek Harness
0.2.1-rc.2 series (web profile) and Node.js 24+.
- A TeX distribution on the
PATH that Harness starts with:
- macOS: MacTeX / TeX Live (
pdflatex, xelatex, bibtex, biber).
- Linux:
texlive-latex-base texlive-latex-recommended texlive-latex-extra texlive-xetex; for Chinese add texlive-lang-chinese and CJK fonts.
- Tectonic is optional; it runs with
--only-cached --untrusted (see Configuration).
Installation
git clone https://github.com/Meinianda-L/folio.git
cd folio
npm install --omit=dev
dsh plugin --profile web add "$(pwd)"
Restart dsh web and open Folio in the Harness sidebar. The repository ships the built browser bundle (client.js), so no build step is needed to use it.
To update later:
git pull
npm install --omit=dev
Then restart Harness. If only client.js changed, reloading the page is enough.
Usage
- Create a manuscript in the library (Article, 中文 ctexart, or Blank).
- Write: the file tree, source and PDF sit side by side. The star marks the main file; drag files onto the tree to upload images or
.bib files.
- Compile with the toolbar button, ⌘/Ctrl + S or ⌘/Ctrl + Enter. Click the build status to see issues.
- Ask the assistant: pick a model in the composer and ask, e.g. "Tighten the abstract" or "Fix the build error". Select text first to point at a passage.
- Review: when a Suggested edit bar appears, open it, read the diff, then Apply or Discard.
| Shortcut | Action |
|---|
| ⌘/Ctrl + S | Save and compile |
| ⌘/Ctrl + Enter | Compile |
\ | Command completion |
| Tab | Next snippet field |
| ⌘/Ctrl + F | Search and replace |
| Double-click the assistant header | Switch between floating and docked |
Configuration
By default manuscripts live in ~/Documents/DSH-Folio. To use another folder, add this to your profile's cordis.patch.yml (e.g. ~/.dsh/profiles/web/cordis.patch.yml):
- id: folio
config:
projectRoot: /Users/you/Papers
| Environment variable | Purpose |
|---|
DSH_FOLIO_TEX_CACHE | XDG cache root with a pre-warmed Tectonic bundle (defaults to XDG_CACHE_HOME or ~/.cache). |
How it works
Harness web client Harness host (Node)
┌──────────────────────────────┐ ┌──────────────────────────────────────┐
│ Folio page (React slot) │ fetch │ /api/folio project & file RPC │
│ ├ CodeMirror editor │──────────▶│ /api/folio/pdf last PDF │
│ ├ PDF viewer │ │ /api/folio/raw images (sandboxed) │
│ └ embedded Harness chat ────┼─ session ▶│ agent/pre-step hidden context │
│ (conversation.content) │ │ folio_project read/compile/propose │
└──────────────────────────────┘ └──────────────────────────────────────┘
- File and build operations use exact, owner-only routes registered on the Harness connection, so they use Harness's own authentication and no separate server.
- The assistant panel renders Harness's own
conversation.content component bound to the manuscript's session.
- A pre-step hook adds a non-user context message at the start of each turn. Harness keeps these messages in the session log but hides them in the chat.
Data on disk
<projectRoot>/<manuscript-id>/
├── project.json title, main file, engine, current chat
├── main.tex, … your sources (plain files)
└── .folio/
├── output.pdf last successful build
├── build.json last build summary and issues
└── proposals.json pending and recent suggestions
Deleting a manuscript moves its folder to <projectRoot>/.trash/ instead of erasing it. Back up projectRoot like any other folder.
Build sandboxing
Builds run one at a time (at most 4 queued) in a temporary snapshot of the project, with a 60-second limit, no shell escape, and a minimal environment that never includes your model keys. Limits: 500 files and 40 MiB per project (20 MiB of sources per build), 2 MiB per text file, 10 MiB per upload. Native TeX is not an operating-system sandbox: Folio is meant for your own, trusted projects.
Development
npm install # includes the build toolchain
npm run build # bundles client-src.jsx + client.css into client.js
npm test # domain, proposals and host tests (real pdfLaTeX/BibTeX when installed)
| File | Role |
|---|
index.js | Host plugin: routes, context hook, folio_project tool, session restriction |
domain.js | Projects, files, uploads, templates, build records |
compiler.js | TeX pipeline and log parser |
proposals.js | Suggested edits and find/replace application |
client-src.jsx, client.css | Browser UI (bundled into client.js) |
locale/ | English and Chinese strings |
Not included
Multi-user collaboration, share links, public/tunnel access, accounts or a separate API-key store. Folio is a single-user, local tool built on your existing Harness setup.
License
MIT
