AGENTS.md - LMMs-Lab Writer

Updated: 2026-02-08 | Branch: main

Overview

AI-native LaTeX editor. Tauri v2 desktop application - let Claude, Cursor, Codex, and OpenCode write your papers while you focus on research. Local-first, cross-platform (macOS, Windows, Linux).

Architecture

lmms-lab-writer/
├── apps/
│   ├── desktop/              # Tauri v2 desktop app
│   │   ├── src/              # Next.js frontend (React 19, static export)
│   │   │   ├── app/page.tsx  # Main editor page
│   │   │   ├── components/   # React components (40+ files)
│   │   │   │   ├── editor/   # Editor, file tree, terminal, diff, git panel
│   │   │   │   ├── opencode/ # AI chat panel, messages, tools, sessions
│   │   │   │   ├── auth/     # Login, deep-link, user dropdown
│   │   │   │   ├── latex/    # Compiler settings, install prompt, main file picker
│   │   │   │   └── ui/       # Shared UI (tabs, dialogs, toast, context menu, scroll)
│   │   │   └── lib/tauri/    # Tauri IPC hooks
│   │   └── src-tauri/        # Rust backend
│   │       └── src/commands/ # Tauri commands (fs, git, latex, terminal, opencode, auth)
│   ├── web/                  # Marketing website (Next.js 15, Vercel)
│   │   ├── src/app/          # Next.js pages (landing, docs, auth, download)
│   │   ├── content/docs/     # MDX documentation
│   │   └── src/lib/supabase/ # Supabase auth client
│   └── video/                # Marketing video (Remotion)
│       └── src/              # Video generation components
├── packages/
│   └── shared/               # Shared TypeScript types & utilities
│       └── src/index.ts      # FileNode, GitStatus, CompileResult, etc.
├── docs/                     # Project documentation
│   ├── DESIGN.md             # Design system (retro-terminal, monochrome + orange)
│   ├── MARKETING.md          # Marketing copy & launch strategy
│   ├── SCREENSHOT-GUIDE.md   # Asset capture guide
│   └── COPY-DAN-KOE.md      # Long-form copywriting
├── turbo.json
└── pnpm-workspace.yaml

Key Files

Desktop App

Rust Command Modules

Website

Commands

# Development
pnpm tauri:dev                              # Run Tauri desktop app in dev mode
pnpm --filter @lmms-lab/writer-web dev      # Run website in dev mode

# Build
pnpm build                                  # Build all packages
pnpm tauri:build                            # Build desktop app (.app/.dmg/.exe/.deb)
pnpm --filter @lmms-lab/writer-web build    # Build website

# Verify
cd apps/desktop/src-tauri && cargo check    # Check Rust
cd apps/web && pnpm tsc --noEmit            # Check website TypeScript

# Lint & Format
pnpm lint                                   # ESLint check
pnpm lint:fix                               # ESLint auto-fix
pnpm format                                 # Prettier format

Conventions

TypeScript

• noUncheckedIndexedAccess: true - Array access returns T | undefined
• Strict mode. No as any, no @ts-ignore

File Naming

• Files: kebab-case.ts
• Components: PascalCase
• Functions: camelCase

Design System

Retro-Terminal Fintech aesthetic. Monochrome + orange accent. No rounded corners.

Button Style (Neo-Brutalism):

• Primary: bg-accent text-white, sharp corners, uppercase monospace
• Secondary: bg-foreground text-white, sharp corners
• Ghost: border border-border, hover with accent
• Use btn btn-sm classes with box-shadow offset effect
• NEVER use rounded corners

See docs/DESIGN.md for full design system documentation.

Layout Alignment (OCD-Level Precision)

All visual elements must align perfectly across the site. Use consistent container patterns:

Standard Pattern (for sections, main content):
<section className="px-6">           // Padding OUTSIDE
  <div className="max-w-5xl mx-auto"> // Container INSIDE
    {content}
  </div>
</section>

For full-width elements with border (header, footer):
<header className="border-b border-border px-6">  // Padding on element
  <div className="max-w-5xl mx-auto">              // Container without px
    {content}
  </div>
</header>

Rules:

• px-6 goes on the OUTER element, not inside max-w-5xl
• All pages use max-w-5xl for main container width
• Inner content can use max-w-2xl, max-w-sm etc. for reading width
• This ensures logo, content, and footer all share the same left/right edge

Debugging (Tauri Desktop App)

Always debug from dev mode - don't waste time building. Dev mode has hot reload and DevTools.

Quick Start Debug

# 1. Start dev mode (frontend + Tauri)
pnpm tauri:dev

# 2. Open DevTools in app:
#    macOS:   ⌥⌘I (or View → Toggle Developer Tools)
#    Windows: Ctrl+Shift+I
#    Linux:   Ctrl+Shift+I
# 3. Check Console tab for errors

Diagnostic Commands

# Check frontend compiles
cd apps/desktop && pnpm tsc --noEmit

# Check Rust compiles
cd apps/desktop/src-tauri && cargo check

# Check dev server running (macOS/Linux)
lsof -i :3000

# Check dev server running (Windows)
netstat -ano | findstr :3000

# Kill stuck processes (macOS/Linux)
pkill -f "tauri" && pkill -f "next"

# Kill stuck processes (Windows)
taskkill /f /im "lmms-lab-writer.exe" 2>nul & taskkill /f /im "node.exe" /fi "WINDOWTITLE eq next" 2>nul

Debug Layers (check in order)

Common Issues

Key Debug Files

Build Locations

macOS:   apps/desktop/src-tauri/target/release/bundle/macos/LMMs-Lab Writer.app
         apps/desktop/src-tauri/target/release/bundle/dmg/LMMs-Lab Writer_*.dmg
Windows: apps/desktop/src-tauri/target/release/bundle/nsis/LMMs-Lab Writer_*-setup.exe
Linux:   apps/desktop/src-tauri/target/release/bundle/appimage/LMMs-Lab Writer_*.AppImage
         apps/desktop/src-tauri/target/release/bundle/deb/lmms-lab-writer_*.deb

Anti-Patterns

Performance Guidelines

Frontend (React/Next.js)

1. State Management: Split large state objects into smaller slices to prevent unnecessary re-renders
2. Memoization: Use React.memo for components that receive stable props
3. Parallel I/O: Use Promise.all for independent async operations
4. Dynamic Imports: Heavy components (Terminal, OpenCodePanel, Monaco) should use next/dynamic

Backend (Rust/Tauri)

1. Async I/O: Use tokio::fs instead of std::fs in async handlers
2. Process Management: Use tokio::process::Command instead of std::process::Command
3. IPC Throttling: Buffer high-frequency events (compile output, PTY) before emitting
4. Parallel Git: Run independent git commands with tokio::join!
5. Path Validation: All file operations must validate paths are within the project directory (see util.rs)