# Project pack: Logseq @ 533ac43

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

> Logseq is a note-taking app built around a daily journal page. You write in bullet points, link to any page or idea with double square brackets, and everything that mentions it shows up there automatically. It also handles to-dos, flashcards and PDF notes, with themes and community plugins. The pinned 2.0.2 release is the new "database version": notes live in a local database instead of Markdown files, and your notes stay on your own device.

## Version and source
- Repository: https://github.com/logseq/logseq
- Pinned commit: `533ac4382a7b69baa98de3a973bff90305b212dc`. 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/logseq/logseq/archive/533ac4382a7b69baa98de3a973bff90305b212dc.zip
- Official docs: https://docs.logseq.com
- Live demo: https://app.logseq.com. The official web version, which may run newer code than the pinned 2.0.2. Notes are stored in your browser, not on Logseq's servers; try it with a test graph.
- 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/logseq/logseq bespoke-logseq
  cd bespoke-logseq
  git checkout --detach 533ac4382a7b69baa98de3a973bff90305b212dc
  # Prepare development requirements and local configuration first.
  # Setup notes: browser app on http://localhost:3001; pnpm dev-electron-app for the desktop app
  pnpm install && pnpm watch
  ```

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
  # Easiest: download the 2.0.2 desktop app from https://github.com/logseq/logseq/releases/tag/2.0.2
  # or try it in your browser at https://app.logseq.com.
  # Or run the official web app image on this computer with Docker:
  docker run -d --rm -p 127.0.0.1:3001:80 ghcr.io/logseq/logseq-webapp:latest
  # Then open http://localhost:3001 in Chrome or Edge.
  ```

- Needs: The desktop or phone app, or a modern Chromium-based browser for the web app (HTTPS needed for remote access), For development, Node.js and pnpm, Java and the Clojure CLI, and babashka (bb)
- Develop: `pnpm install && pnpm watch   # browser app on http://localhost:3001; pnpm dev-electron-app for the desktop app`
- Test: `bb dev:lint-and-test`
- Check/lint: `bb dev:lint-and-test   # bb lang:validate-translations and bb lang:lint-hardcoded for text changes`
- Build: `pnpm release   # static web app in static/; pnpm release-electron for the desktop app`
- Stack: clojurescript, clojure, typescript, javascript, css (shadow-cljs, Rum (React), DataScript, Electron, Capacitor, Tailwind CSS). Difficulty for a non-developer with an AI: **advanced**. config.edn, custom.css, themes and a large plugin marketplace cover most personal changes. The app itself is written in ClojureScript, which few people (and fewer AIs) know well, needs Java, Clojure and Node to build, and changes quickly now that the database version has shipped. Prefer a plugin or custom.css.

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

## Customisation points (settings → extend → code)
- **settings-and-themes** [settings]: Light or dark mode, accent colour, font, language, journal date format and keyboard shortcuts. → `Settings (src/main/frontend/components/settings.cljs) → light/dark, accent colour, language (25 dictionaries in src/resources/dicts/), editor options`
- **config-edn** [settings]: Start of week, default home page, hide empty properties, flashcards, scheduled-tasks view, custom CSS or JS URL. → `Settings → Edit config.edn (all options documented in deps/common/resources/templates/config.edn)`
- **custom-css** [settings]: Change fonts, colours, spacing and hide parts of the screen with CSS. → `Settings → Edit custom.css (logseq/custom.css in the graph)`
- **journals-and-queries** [settings]: What shows on each day's page, such as unfinished tasks or a reading list query. → `Journal pages (src/main/frontend/components/journal.cljs); journal queries and scheduled-tasks options in config.edn`
- **markdown-mirror** [settings]: Keep a plain Markdown copy of edited pages on disk, readable without Logseq (desktop app only). → `Settings → Features → Markdown mirror (markdown-mirror-row in src/main/frontend/components/settings.cljs)`
- **plugins-and-themes** [extend]: Install community plugins and themes, or write a plugin that adds commands, slash commands, panels and settings. → `Plugins marketplace (src/main/frontend/components/plugins.cljs); plugin SDK in libs/ (@logseq/libs), docs at plugins-doc.logseq.com`
- **mcp-and-http-server** [extend]: Let an AI assistant on your computer read and add to your notes through MCP. → `Settings → AI → MCP server and the local HTTP API server, desktop app only (mcp-server-row in src/main/frontend/components/settings.cljs)`
- **cli** [extend]: Read and add blocks in a graph from scripts. → `Logseq CLI (docs/cli/logseq-cli.md)`
- **ui-components** [code]: Change screens. Written in ClojureScript with Rum (a React wrapper). → `src/main/frontend/components/ (e.g. journal.cljs, page.cljs, editor.cljs), styles in src/main/frontend/*.css and tailwind.all.css`
- **data-model** [code]: New built-in properties or behaviour. Needs a database migration and great care. → `deps/db/ (schema, built-in properties in logseq.db.frontend.property), deps/outliner/, src/main/frontend/worker/`
- **text** [code]: Change interface wording. → `src/resources/dicts/en.edn (rules in docs/i18n-key-naming.md and .agents/skills/logseq-i18n/SKILL.md)`

## Must keep working
- Existing graphs. Back up (export the SQLite database or use automated backups) before any change.
- Block and page references. Links, embeds and backlinks depend on stable IDs.
- Database changes need a proper migration; new properties go in logseq.db.frontend.property/built-in-properties (AGENTS.md).
- The plugin API in libs/. Many community plugins rely on it.
- Shipped UI text must go through the i18n helpers; follow the logseq-i18n skill.

## Staying updatable
config.edn, custom.css, themes and plugins cover most personal needs and survive updates. Upstream accepts pull requests linked to an issue; its AGENTS.md says commits and PRs must never mention Codex or any agent name, and points agents to skills in .agents/skills/. Development moves fast on master, so large code changes are likely to conflict.

## Data, costs and safety
- Personal data: **yes**. Stored in: On your device. Each graph is a SQLite database (in the browser's private storage for the web app). Older Markdown "file graphs" can be imported and converted; Org-mode files are not supported. Nothing is sent to Logseq unless you turn on sync. Upstream's README at this release still calls the database version beta and says data loss is possible. Turn on automated backups or export the SQLite database regularly, and back up before trying code changes. Importing a Markdown graph makes a copy and leaves the original folder untouched. For the web app, clearing browser data can delete your graph.
- Service: Logseq Sync (real-time collaboration, RTC) (optional, For Open Collective backers and sponsors, or self-hosted; still alpha): End-to-end encrypted sync of graphs between devices, or sharing them with others in real time.
- Service: Plugin and theme marketplace (optional, free): Community plugins and themes, installed from inside the app. Some plugins call outside services, including AI providers.
- Upstream's README still labels the database version beta and warns data loss is possible; sync (RTC) and the new phone app are alpha. Keep automated backups.
- Plugins and custom.js run with full access to your notes. Install only plugins you trust, and check what AI plugins send to their provider.
- The desktop MCP and HTTP API servers are off by default. Turning them on lets local programs read and change your notes.
- The Docker web app should stay on this computer (127.0.0.1) or behind HTTPS; it has no login of its own.

---

# Customising Logseq

Logseq is written in ClojureScript (a dialect of Lisp that compiles to JavaScript). This listing is pinned to release 2.0.2, the "database version": each graph is a SQLite database rather than a folder of Markdown files. Older Markdown graphs can be imported (Org-mode is no longer supported, and whiteboards have been removed); the old file-graph app now lives separately at https://github.com/logseq/og. **Do almost everything with settings, `config.edn`, `custom.css` and plugins.** They survive updates; code changes are hard and likely to conflict.

## Level 1: Settings (no code)
- **Look:** Settings → General. Light or dark mode and an accent colour. Themes come from the marketplace.
- **Language and editor:** Settings → General / Editor. Interface language (25 dictionaries), font, spell check, date format, and Settings → Keymap for shortcuts.
- **config.edn:** Settings → General → Edit config.edn. Every option is listed with comments in `deps/common/resources/templates/config.edn`: start of the week, the page shown at startup, hide empty properties, flashcards on/off, how many days of scheduled tasks to show, extra queries on the journal page, and a URL for custom CSS or JS.
- **custom.css:** Settings → General → Edit custom.css. Change fonts, colours, spacing and hide parts of the screen.
- **Markdown mirror (desktop):** Settings → Features. Writes a readable Markdown copy of edited pages to the graph's `mirror/markdown` folder.
- **Backups:** the desktop app keeps the last 12 automatic backups in the graph's `backups` folder; in the browser, choose a backup folder under Export Graph.

## Level 2: Extend (no fork)
- **Marketplace:** the Plugins screen installs community plugins and themes. Plugin settings appear under Settings → Plugins.
- **Write a plugin:** JavaScript/TypeScript with `@logseq/libs` (source in `libs/`). Plugins can add slash commands, toolbar buttons, panels, settings and react to edits. Docs: https://plugins-doc.logseq.com
- **MCP and HTTP API (desktop):** Settings → AI → MCP server lets an AI assistant on your computer read and write your notes; it switches on the local HTTP API server too.
- **CLI:** `docs/cli/logseq-cli.md` describes the command-line tool for reading and adding blocks.

## Level 3: Code
Read upstream `AGENTS.md` and `CODEBASE_OVERVIEW.md` first, plus any `AGENTS.md` in the folder you edit and the skills in `.agents/skills/`.

| Change | Where |
|---|---|
| Screens and UI components | `src/main/frontend/components/` (`journal.cljs`, `page.cljs`, `editor.cljs`, `settings.cljs`, `plugins.cljs`…) |
| Styles | `src/main/frontend/*.css`, component `.css` files, `tailwind.all.css` |
| Database schema and built-in properties | `deps/db/` (`logseq.db.frontend.property/built-in-properties`) |
| Editing logic (blocks, outliner) | `deps/outliner/`, `src/main/frontend/worker/` |
| Plugin API | `libs/src/` |
| Text | `src/resources/dicts/en.edn` (see `docs/i18n-key-naming.md`) |
| Desktop shell | `src/electron/` |

## Running locally
- **Just use it:** download the 2.0.2 desktop app from https://github.com/logseq/logseq/releases/tag/2.0.2, or try it at https://app.logseq.com (which may run newer code). Docker, this computer only: `docker run -d --rm -p 127.0.0.1:3001:80 ghcr.io/logseq/logseq-webapp:latest`, then open http://localhost:3001 in Chrome or Edge.
- **Develop** (`docs/develop-logseq.md`, or `docs/develop-logseq-on-windows.md`):
  1. Install Node.js and pnpm, Java and the Clojure CLI, and babashka (`bb`).
  2. `git checkout 2.0.2`, then `pnpm install`
  3. `pnpm watch`, then open http://localhost:3001. For the desktop app, `pnpm dev-electron-app` in a second terminal.
- **Check:** `bb dev:lint-and-test`. For text changes, `bb lang:validate-translations` and `bb lang:lint-hardcoded`.

## Pitfalls
- Upstream's README at 2.0.2 still calls the database version beta and warns data loss is possible; sync (RTC) and the new phone app are alpha. Keep automated backups and try code changes on a test graph.
- New user-facing text must go through the i18n helpers, or `bb lang:lint-hardcoded` fails.
- Database changes need a migration; don't add new classes or properties unless you must (AGENTS.md).
- Upstream's AGENTS.md forbids naming Codex or any agent in commits or pull requests.

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