# Project pack: Joplin @ 94168d3

Facts about **Joplin** 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.

> Joplin is a note-taking and to-do app for desktop, mobile and the terminal. Notes are written in Markdown, organised in notebooks with tags, and can be synced through Dropbox, OneDrive, Nextcloud, WebDAV or Joplin's own server, with end-to-end encryption. A large plugin library and a web clipper make it easy to shape to your own way of working.

## Version and source
- Repository: https://github.com/laurent22/joplin
- Pinned commit: `94168d33d6a9564006ab8254b990d365de263ef7`. 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/laurent22/joplin/archive/94168d33d6a9564006ab8254b990d365de263ef7.zip
- Official docs: https://joplinapp.org/help
- Licence: **AGPL-3.0-or-later**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them your source code under the same licence. Using it privately for yourself or your household has no extra obligations. The Joplin Server code in packages/server has its own separate licence file; check it before running a server for other people.

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

  ```sh
  git clone https://github.com/laurent22/joplin bespoke-joplin
  cd bespoke-joplin
  git checkout --detach 94168d33d6a9564006ab8254b990d365de263ef7
  # Prepare development requirements and local configuration first.
  corepack enable
  yarn install
  cd packages/app-desktop
  yarn 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
  Download the desktop app from https://joplinapp.org/download, then add it to your own sync service in Settings → Synchronisation.
  ```

- Needs: Node 22 and Yarn (via corepack) for development, a desktop download for everyday use
- Develop: `cd packages/app-desktop && yarn start`
- Test: `yarn test`
- Check/lint: `yarn linter`
- Stack: typescript, javascript (Electron, React, React Native, Yarn workspaces). Difficulty for a non-developer with an AI: **advanced**. A very large Yarn monorepo with desktop, mobile, CLI and server apps. Most personal changes need no fork: use plugins, themes and custom CSS. Building the apps from source is slow and heavy.

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

## Customisation points (settings → extend → code)
- **plugins** [extend]: Add features such as kanban boards, calendars, table of contents and advanced search. → `Tools → Options → Plugins (plugin API in packages/lib/services/plugins)`
- **custom-css** [extend]: Change colours, fonts, spacing and note layout without touching code. → `Profile folder files userchrome.css (app) and userstyle.css (rendered notes)`
- **templates-and-shortcuts** [settings]: Note templates, shortcuts and editor choice (Markdown or rich text). → `Tools → Options → Keyboard Shortcuts, Templates`
- **sync-setup** [settings]: Where notes sync to and whether they are encrypted. → `Tools → Options → Synchronisation and Encryption`
- **desktop-ui** [code]: New panels, buttons and screens in the desktop app. → `packages/app-desktop/gui/`
- **data-api** [extend]: Read and write notes from scripts on your own computer. → `Web Clipper service REST API (packages/lib/services/rest)`

## Must keep working
- Sync and end-to-end encryption flows. A bug here can corrupt or lock notes.
- Database migrations and the note data model in packages/lib.
- Plugin API compatibility. Existing plugins must keep working.

## Staying updatable
Prefer plugins, themes and custom CSS. They survive upgrades and need no fork. Only fork for changes that a plugin cannot do, and keep them small.

## Data, costs and safety
- Personal data: **yes**. Stored in: A local SQLite database and attachments in the Joplin profile folder on each device. Turn on end-to-end encryption before syncing anywhere you do not fully trust. Back up the profile folder.
- Service: Sync target (Joplin Cloud, Dropbox, OneDrive, Nextcloud, S3 or WebDAV) (optional, free to paid, depends on provider): Keeps your notes in step across devices.
- Service: Joplin Server (self-hosted) (optional, your own hosting costs): A private sync server you control.
- Notes can hold sensitive information. Enable end-to-end encryption and keep your master password safe.
- Install plugins only from the official plugin repository, and read what a plugin can access.
- Never paste sync credentials or encryption keys into an AI chat.

---

# Customising Joplin

Joplin is a large Yarn monorepo. The easiest changes need no source code at all: plugins, themes and custom CSS. Change source only when a plugin cannot do the job.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Desktop app screens and menus | packages/app-desktop/gui/ |
| Mobile app | packages/app-mobile/ |
| Terminal app | packages/app-cli/ |
| Notes, folders, sync and the database | packages/lib/ (models/, services/, SyncTarget*.ts) |
| Markdown rendering | packages/renderer/ |
| Plugin API | packages/lib/services/plugins/api/ and the typings in packages/lib/services/plugins/api/types.ts |
| Joplin Server | packages/server/ (separate licence) |
| Translations | packages/tools/ and the locale files under packages/app-desktop/locales/ |

## Use the gentlest change first

1. **Settings (no code):** sync target, encryption, templates, shortcuts, editor choice.
2. **Extend:** install or write a plugin, add `userchrome.css` and `userstyle.css`, or script the clipper API.
3. **Code:** desktop screens and library code. Expect a long first build.

## Recipes

- **New plugin:** run `npm init joplin-plugin` (the official generator), edit `src/index.ts`, and load the built `.jpl` from Options → Plugins → Advanced.
- **Restyle notes:** put CSS in the profile folder's `userstyle.css`, then restart.
- **Script your notes:** enable the Web Clipper service in Options, then call the local REST API with the token shown there.

## Running and checking your changes

- Run the desktop app from `packages/app-desktop` with `yarn start`.
- Unit tests run per package, for example `cd packages/lib && yarn test`.
- Test sync against a throwaway folder or a test sync target, never your real notes.

## Pitfalls

- Back up your profile folder before testing code changes.
- Do not edit the generated files under `packages/app-mobile/android` or `ios` by hand.
- Joplin Server code has its own licence. Read it before reusing or hosting it for others.

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