# Project pack: Trilium Notes @ a7cae93

Facts about **Trilium Notes** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Trilium is a note-taking app for building a large personal knowledge base. Notes sit in a tree you can arrange however you like, and one note can live in several places. It has a rich text editor, a daily journal, to-do lists, mind maps, drawings and maps. You can lock private notes with a password. Use it as a desktop app, or run it on your own server and open it from any browser or phone.

## Version and source
- Repository: https://github.com/TriliumNext/Trilium
- Pinned commit: `a7cae93a63adcf2beb2c76657b7624e0a40f1a80`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/TriliumNext/Trilium/archive/a7cae93a63adcf2beb2c76657b7624e0a40f1a80.zip
- Official docs: https://docs.triliumnotes.org
- Licence: **AGPL-3.0-only**. Free to use and change. If you run a changed version that other people use over the internet (not just you or your household), you must offer them your source code under the same licence. Private use has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/TriliumNext/Trilium bespoke-trilium
  cd bespoke-trilium
  git checkout --detach a7cae93a63adcf2beb2c76657b7624e0a40f1a80
  # Prepare development requirements and local configuration first.
  # Setup notes: dev server on :8080; pnpm desktop:start for the Electron app
  pnpm install && pnpm server:start
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --name trilium -p 8080:8080 -v ~/trilium-data:/home/node/trilium-data triliumnext/trilium:latest
  # then open http://localhost:8080 and set a password
  # (or download the desktop app from https://github.com/TriliumNext/Trilium/releases/latest)
  ```

- Needs: Docker, or the desktop app for Windows, macOS or Linux, For development, Node.js and pnpm
- Develop: `pnpm install && pnpm server:start   # dev server on :8080; pnpm desktop:start for the Electron app`
- Test: `pnpm --filter server test && pnpm --filter client test   # pass a spec path pattern to run fewer tests`
- Check/lint: `pnpm typecheck && pnpm dev:format-check`
- Stack: typescript, css (Node.js, Express, Preact, jQuery, CKEditor 5, Electron). Difficulty for a non-developer with an AI: **moderate**. Themes, custom CSS, attributes, scripts and widgets are written as notes inside Trilium, so a lot can change without touching the source. Source changes mean a large TypeScript monorepo (pnpm) with a Preact/jQuery client and a shared core used by server and desktop.

## The project's own AI instructions
Read these in the repository before changing code: `CLAUDE.md`.

## Customisation points (settings → extend → code)
- **themes-and-css** [settings]: Switch light/dark, change fonts, or write your own theme as a note. → `Options → Appearance; a CSS code note with`
- **attributes-and-templates** [settings]: Turn notes into simple records, e.g. books with author and rating, or recipes with cooking time. → `Labels, relations and promoted attributes (docs/User Guide/User Guide/Advanced Usage/Attributes.md)`
- **journal** [settings]: A daily diary note created automatically, grouped by year, month and week. → `#calendarRoot and date-pattern labels (docs/User Guide/User Guide/Advanced Usage/Advanced Showcases/Day Notes.md)`
- **sharing** [settings]: Publish selected notes as a read-only web page, with a custom template if you like. → `Share a note or subtree (docs/User Guide/User Guide/Advanced Usage/Sharing.md)`
- **scripts-and-widgets** [extend]: Add buttons, side-panel widgets and automations without rebuilding Trilium. → `Backend scripts and custom widgets written as notes (docs/User Guide/User Guide/Scripting/)`
- **etapi** [extend]: Add notes from other apps, phone shortcuts or scripts. → `ETAPI REST API with a token (docs/User Guide/User Guide/Advanced Usage/ETAPI (REST API).md; apps/server/src/etapi/)`
- **client-ui** [code]: Change the interface itself. → `apps/client/src/widgets/ (new UI in widgets/react/), styles in apps/client/src/stylesheets/, text in apps/client/src/translations/en/translation.json`
- **core-and-server** [code]: New data or behaviour. Always go through the Becca cache so sync keeps working. → `packages/trilium-core/src/ (entities in becca/entities/, services/), apps/server/src/`

## Must keep working
- Existing notes, attachments and revisions. Back up trilium-data before upgrading or changing code.
- Sync. All changes must go through the Becca cache so they create sync records; never write to the database directly.
- Protected (encrypted) notes. Never log or export their decrypted contents.
- Sync version compatibility between desktop, server and third-party phone apps.

## Staying updatable
Themes, custom CSS, attributes, day notes, scripts, custom widgets and ETAPI cover most personal needs inside Trilium itself, so you can keep upgrading without a fork. Upstream ships a CLAUDE.md with its own conventions for code changes.

## Data, costs and safety
- Personal data: **yes**. Stored in: A single SQLite file (document.db) in the trilium-data folder, plus automatic backups in its backup/ folder. Back up the whole trilium-data folder. Trilium makes daily, weekly and monthly backups itself; copy them to another disk too. Protected notes are encrypted with your password; if you forget it they cannot be recovered.
- Service: Sync server (another Trilium server) (optional, free (self-hosted) or paid third-party hosting): Keep notes in step between the desktop app, the server and phones.
- Service: OpenID Connect provider (optional, free (self-hosted) or varies): Log in with an existing account instead of a password.
- Setting `TRILIUM_NETWORK_PORT`: Port the server listens on (default 8080).
- Setting `TRILIUM_GENERAL_INSTANCENAME`: A name for this Trilium instance, usable by scripts.
- Setting `TRILIUM_GENERAL_NOAUTHENTICATION`: Turns off the login. Only for a computer nobody else can reach; leave unset otherwise.
- Setting `TRILIUM_MULTIFACTORAUTHENTICATION_OAUTHCLIENTSECRET` (**secret**: the person enters it themselves, never in chat): Only if you set up OpenID login. Never paste the value into an AI chat.
- Don't set TRILIUM_GENERAL_NOAUTHENTICATION on a server others can reach.
- Scripts and widgets run with full access to your notes. Only paste scripts you understand or trust.
- Shared notes are public to anyone with the link. Check what a shared subtree contains.

---

# Customising Trilium Notes

Trilium is unusual: **themes, styles, scripts and widgets are themselves notes** inside Trilium. Most adaptations need no source changes and survive upgrades. Exhaust levels 1 and 2 before touching code.

User guide paths below are under `docs/User Guide/User Guide/` in the repo (also in the app with `F1`, and at docs.triliumnotes.org).

## Level 1: Settings (no code)
- **Theme:** Options → Appearance (light, dark and more). Fonts: `Basic Concepts and Features/Themes/Personalizing the font.md`.
- **Your own theme:** a CSS code note with `#appTheme=my-theme`, then pick it in Options → Appearance. See `Basic Concepts and Features/Themes.md`.
- **Small style tweaks:** a CSS code note with `#appCss`, applied on top of any theme. See `Theme development/Custom app-wide CSS.md`.
- **Journal:** mark a note with `#calendarRoot`. Trilium creates a note per day, grouped by year and month (optional week and quarter notes, custom date patterns). See `Advanced Usage/Advanced Showcases/Day Notes.md`.
- **Structured notes:** labels, relations and *promoted attributes* turn notes into simple records (books, recipes, contacts). See `Advanced Usage/Attributes.md`.
- **Collections:** show a subtree as a table, board, calendar or map (`Collections/`).
- **Privacy:** protected notes are encrypted with your password (`Basic Concepts and Features/Notes/Protected Notes.md`).
- **Publishing:** share a note or subtree as a read-only web page (`Advanced Usage/Sharing.md`).

## Level 2: Extend (no fork)
- **Custom widgets** (front-end JS notes): buttons, side-panel widgets, launchers. See `Scripting/Frontend Basics/Custom Widgets.md` (includes a word-count widget example).
- **Backend scripts:** run on events, on a schedule or on demand. See `Scripting/Backend scripts.md` and `Backend Events.md`.
- **ETAPI** (REST API): get a token in Options → ETAPI. See `Advanced Usage/ETAPI (REST API).md`. Good for phone shortcuts and imports.
- **Web Clipper:** save web pages into Trilium (`Installation & Setup/Web Clipper.md`).
- **Community themes and scripts:** awesome-trilium (linked from the README). Read scripts before installing them.

## Level 3: Code
Read upstream `CLAUDE.md` first. It is detailed and strict.

| Change | Where |
|---|---|
| Interface (new UI in Preact) | `apps/client/src/widgets/react/`; older jQuery widgets in `apps/client/src/widgets/` |
| Styles | `apps/client/src/stylesheets/` (`style.css`, `theme-light.css`, `theme-dark.css`) |
| Interface text | `apps/client/src/translations/en/translation.json` |
| Notes, attributes, sync | `packages/trilium-core/src/becca/entities/` and `packages/trilium-core/src/services/` |
| REST API (ETAPI) | `apps/server/src/etapi/` |
| Published (shared) pages | `packages/share-theme/src/` |

## Running locally
- **Just use it:** download the desktop app from the latest release, or run
  `docker run -d -p 8080:8080 -v ~/trilium-data:/home/node/trilium-data triliumnext/trilium:latest`
  and open http://localhost:8080. The repo's `docker-compose.yml` does the same with Compose.
- **Develop:**
  1. Install Node.js and pnpm (`npm install -g pnpm`).
  2. Run `pnpm install`.
  3. Run `pnpm server:start` and open http://localhost:8080 (or `pnpm desktop:start` for the Electron app).
- **Check:** `pnpm typecheck`, `pnpm dev:format-check`, and narrow tests such as `pnpm --filter server test <pattern>`.

## Pitfalls
- Back up `trilium-data` before upgrades or code changes. Restoring means swapping `document.db` with a backup file.
- Never write to the database directly. Use the Becca cache so changes sync.
- Upstream says not to run ESLint (it runs out of memory) or the full test suite during development; use `pnpm typecheck` and narrow tests.
- Desktop, server and third-party phone apps must share the same sync version. Upgrade them together.
- Forgetting the password for protected notes means losing them. There is no reset.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/trilium/a7cae93/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/trilium/a7cae93/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/trilium/a7cae93/r2/SKILL.md)