Getting started

This guide is about starting practically with Org2: install CLI + editor tooling, point it at your existing notes, and know what works today.

1) Install the CLI

git clone https://github.com/aviaviavi/org2.git
cd org2
npm ci
npm run build

Run commands via:

npm run org2 -- --help

2) Install editor extension(s)

VS Code extension: editors/vscode-org2/
Vim/Neovim support: editors/vim-org2/

VS Code is currently the most complete editor integration.

3) Use your existing Org notes immediately

Org2 is designed as a drop-in workflow for existing Org files.

Keep your current .org files.
Point Org2 CLI/LSP/agenda at your existing notes directory.
You do not need to migrate everything up front.

Example:

npm run org2 -- agenda --dir /path/to/your/org-notes --recursive

4) Use `.org2` for new files

For new files, prefer .org2 extension.

Why:

clearer intent that the file is in the Org2 workflow,
easier editor/tooling targeting,
cleaner long-term migration path.

5) What’s here and what is not

Here today

Core Org language support is broadly there already.
Full day-to-day Org-style note workflow is already viable in VS Code.
CLI workflows (agenda/todo/plan/capture/export/publish).
Roam workflows (IDs/backlinks/node creation/wiki+id links).
Org-crypt subtree encrypt/decrypt workflows.
Spec draft + conformance fixtures.

Not here yet

100% feature-for-feature GNU Org Mode parity (not the project goal)
Mature recurring/habits/clocking ecosystem
Broad editor parity beyond VS Code
Stable final APIs (project is still early alpha)

6) Next docs