Privacy-first note-taking and brainstorming tool for personal, local use.

Your notes are plain Markdown files on your own machine — no cloud, no account, no data leaving your computer. AI features are optional and work through your existing GitHub Copilot subscription or GitHub Models. Cloud backup via Git is available, but only if you want it. You own your data, completely.

Status: Active development · v1.0.0

Daily journaling	Technical notes with Mermaid & code	Dark mode

AI chat assistant	AI settings

Frontend

• React 18 + TypeScript
• Vite — sub-second HMR
• Tailwind CSS
• BlockNote — rich-text editor (ProseMirror/Tiptap)
• @dnd-kit — drag-and-drop
• Mermaid + KaTeX

Backend

• Node.js + Express + TypeScript
• isomorphic-git — Git operations in pure JS
• better-sqlite3 — FTS5 search index
• fs-extra — atomic file writes

Shared

• TypeScript monorepo (npm workspaces) with shared type definitions

pergament/
├── client/          # React frontend (Vite)
├── server/          # Express API server
├── shared/          # Shared TypeScript types
└── docs/            # ADRs and action plan

Data is stored separately from the source code, in your home directory:
~/.pergament/data/
├── workspace.json         # Page tree metadata
├── pages/
│   └── <uuid>/
│       └── index.md       # One Markdown file per page
└── .pergament/
    ├── config.json        # All settings (AI tokens, Git config, preferences)
    └── search.db          # SQLite FTS5 index (auto-rebuilt)

All settings — including AI tokens and Git credentials — are managed through the in-app Settings UI and stored in ~/.pergament/data/.pergament/config.json. No secrets are ever needed in environment variables or source code.

The data directory location can be overridden with the PERGAMENT_DATA_DIR environment variable (see .env.example).

For a detailed breakdown of every layer — frontend, backend, data model, request flow, and AI integration — see ARCHITECTURE.md.

See docs/adr/ for Architecture Decision Records covering every major design choice.

• Node.js 20+ and npm 10+
• A modern browser (Chrome, Firefox, Edge, Safari)
• Native build tools — required by better-sqlite3:
  • macOS: xcode-select --install
  • Ubuntu/Debian: sudo apt install build-essential python3
  • Windows: install windows-build-tools or use WSL2

git clone https://github.com/<your-github-username>/pergament.git
cd pergament
npm install

npm run dev

This starts:

• Express API server on http://localhost:3000
• Vite dev server on http://localhost:5173 — open this URL in your browser

On first run, Pergament automatically:

1. Creates ~/.pergament/data/ with a default config
2. Initialises a local Git repository inside the data directory
3. Builds the full-text search index

The browser does not open automatically in development mode. Navigate to http://localhost:5173 yourself.

npm run build
npm start

The server serves the compiled frontend and API from a single process on http://localhost:3000. In production mode the browser opens automatically on startup (configurable in Settings → General).

Optional: copy .env.example to .env to override the port or data directory path before starting.

All configuration is done through Settings → General / Git / AI in the app UI. There is no manual config file editing required.

The only runtime environment variables are optional overrides:

In Settings → AI, choose a provider and enter your credentials:

• GitHub Models — paste a GitHub Personal Access Token with models:read scope
• GitHub Copilot — click "Sign in with GitHub" and complete the device flow (requires an active Copilot subscription); no PAT needed

# All tests
npm test --workspaces

# Frontend only
npm test -w client

# Backend only
npm test -w server

client/src/
├── components/
│   ├── editor/          # BlockNote editor, AI bar, math/mermaid blocks
│   ├── layout/          # App shell, sidebar, panels
│   ├── sidebar/         # Page tree, search, git status
│   └── ui/              # Generic UI components
├── context/             # React contexts (pages, settings, toasts)
├── hooks/               # useTheme, useKeyboardShortcuts
└── utils/               # AI helpers, templates, tree utilities

server/src/
├── routes/              # Express route handlers
├── services/            # Business logic (git, search, config, AI)
└── utils/               # Shared server utilities

Architecture decisions are documented in docs/adr/.

High-level upcoming work:

• PWA support (installable, offline-capable)
• Plugin/extension system
• Multi-workspace support
• Mobile-responsive layout improvements

Contributions are welcome! Please read CONTRIBUTING.md before opening a pull request.

MIT © 2026 Radu Tămaș — Codify Idea

Proudly made in Cluj-Napoca, Romania 🇷🇴