claudeleaf CLAUDE.md

CLAUDE.md

Internal documentation for Claudeleaf — the single source of truth for how the project works. (User-facing docs live in README.md.)

What this is

Claudeleaf bridges an Overleaf account to an API so Claude — or any agent/tool — can edit any of the account's projects programmatically through Overleaf's live web-editing channel (not git). Edits appear to collaborators in real time, attributed to the signed-in user. One instance is account-scoped: it lists every accessible project and edits any of them (by id or name); each project is backed by its own realtime connection.

TypeScript / Node, delivered as three layers over one core:

• a TypeScript SDK (OverleafClient, account-scoped; ProjectSession, per-project),
• a CLI (claudeleaf) — thin command wrapper,
• an MCP server — thin tool wrapper, for Claude Code.

Tech stack

• Node.js 20+, TypeScript (ESM, NodeNext), built with tsc to dist/. npm for tooling.
• ws — the realtime WebSocket transport.
• global fetch (Node) — the Socket.IO handshake and the REST tree/projects endpoints.
• playwright-core — drives the user's installed Chrome/Edge for the one-time manual login (no browser download). Loaded lazily (dynamic import in auth.browserLogin) so the SDK/CLI/MCP stay lightweight — important for npx.
• @modelcontextprotocol/sdk + zod — the MCP server.
• vitest — unit + live integration tests. tsx — run TS directly (dev / MCP launch).

Project structure (src/, flat)

src/
  index.ts        public API: OverleafClient, ProjectSession, Config, Document, errors
  config.ts       account-level Config (no project/credentials); env parsing
  errors.ts       error hierarchy (ClaudeleafError + subclasses)
  util.ts         async helpers: Mutex, Deferred, sleep, withTimeout
  protocol.ts     Socket.IO 0.9 frame encode/decode (pure)
  ot.ts           ShareJS ops, offset<->rowcol, diff, wire encoding, git-blob hash (pure)
  logParser.ts    parse pdfTeX/LaTeX output.log into errors/warnings/bad-boxes (pure)
  document.ts     Document: local mirror of one open doc (text + version + generation)
  types.ts        shared types (Entity, ProjectSummary, ProjectInfo, CompileResult, ...)
  realtime.ts     RealtimeConnection(projectId): WS transport, acks, heartbeat, reconnect
  auth.ts         SessionManager: manual browser login + session cookie cache
  rest.ts         listProjects() + RestClient(projectId) for tree CRUD + compile/output
  session.ts      ProjectSession: one project's realtime connection, tree, edits, compile
  client.ts       OverleafClient: account-scoped; listProjects + per-project delegation
  cli.ts          CLI (login, doctor, projects, doc ops, compile, mcp); the bin
  mcpServer.ts    MCP server exposing the SDK as tools (each takes a project)
test/             vitest unit (no network) + integration/mcp e2e (live, auto-skip)