1) Install the Mac app

Org2 Workspace is the recommended starting point. It gives you capture, daily notes, Agenda, search, rendered files, AI threads, and agent review without requiring you to learn the file format first.

1. Download the latest Org2Workspace.dmg from the Org2 downloads page.

2. Open the disk image and drag Org2Workspace.app into Applications.

3. Open the app and choose Create a new corpus.

4. Pick a folder that you can easily find and back up.

Org2 creates a small starter workspace with a welcome note and folders for daily notes, ordinary notes, generated views, and workflows. Everything is plain text that you can inspect in Finder, Git, or another editor. Org2 never requires you to maintain an app-specific database.

If you already keep notes in a folder, choose Open an existing corpus instead. Markdown and other plain-text material can remain alongside Org2 files while you adopt Org2 gradually.

The initial downloadable disk image is built for Apple Silicon Macs. Current release builds are developer-signed, not notarized. If macOS blocks the first launch, open System Settings → Privacy & Security and allow Org2Workspace, or right-click the app in Finder and choose Open.

2) Make your first note

Click New Note, give the note a useful name, and write normally. A note might be a project, meeting, person, recipe, decision, or anything else you want to remember.

Under the rendered view, Org2 stores a simple outline. The same note in source form can look like this:

* Plan the launch

The goal is to publish a clear announcement and onboarding guide.

** TODO Draft the announcement
SCHEDULED: <2030-01-15 Tue>

** Decisions

- Start with a small private beta.
- Collect feedback after the first week.

Only a few conventions matter at first:

• A line beginning with * is a title; ** is a section inside it.

• TODO makes a heading actionable.

• SCHEDULED: gives the task a date so it appears in Agenda.

• Ordinary paragraphs and lists are just text.

You can use the app's controls instead of editing this syntax directly. The readable source remains available whenever you want it.

3) Use Today and Agenda

Open Today for a lightweight daily note. Use it for quick thoughts, a running log, or tasks that do not yet need their own file.

Open Agenda to see actionable items collected across the entire corpus. Mark an item done, reschedule it, assign a priority, or open its source note. You do not need to manually copy tasks into a separate task manager.

4) Find and connect what you know

Use Command-K to quickly open any file or heading. Global search finds text, tasks, agent work, and other indexed workspace records.

When two ideas belong together, add a link rather than duplicating the information. Org2 keeps source locations and backlinks, so a person, project, meeting, or decision can remain connected to the work that came from it.

Do not try to design the perfect folder structure on day one. A few notes plus daily capture are enough; reorganize later as useful patterns emerge.

5) Put the corpus to work with AI

AI is optional. Your files remain useful without a model or agent.

To connect one, open Org2 Workspace → Settings… → AI Chat. Add or enable a named destination backed by the local or remote runtime, hosted provider, self-hosted model, or compatible endpoint you prefer. Agents outside the native app can use the same corpus through CLI JSON and MCP. An AI thread can then search the corpus, cite the files it used, and—within the permissions you choose—preview or apply edits.

You can also create a shared room and explicitly mention multiple destinations with @mentions or @all. Each response stays attributed to the agent that produced it. The corpus, not any one model or chat provider, remains the durable context.

Start with a concrete request such as:

What open tasks are connected to this project? Cite the source of each one.

or:

Turn these notes into a one-page proposal, but show me the changes before writing them.

See Agent quickstart when you are ready for permissions, durable runs, workflows, approvals, and deeper agent integration.

6) Create useful outputs

The same corpus can produce more than notes and task lists. As your work grows, Org2 can render or export:

• filtered and sortable data tables,

• charts backed by explicit datasets and queries,

• slide decks and presentation PDFs,

• ordinary PDFs for proposals, quotes, and other documents,

• published HTML and documentation sites.

These outputs stay connected to inspectable source and provenance instead of becoming isolated files with no explanation of where they came from.

Prefer an editor? Start there instead

The Mac app is the easiest onramp, but it is not required. If you already live in VS Code, install the Org2 extension and open or create a corpus folder there. VS Code provides a strong source-editing workflow with Agenda, TODO and planning edits, capture, backlinks, formatting, navigation, and export commands.

The CLI also works well beside VS Code, Vim/Neovim, Emacs, or another editor:

npm install -g @aviaviavi/org2
org2 --version
org2 agenda --dir /path/to/your/corpus --recursive
org2 agenda --dir /path/to/your/corpus --recursive --tui

You can try the CLI without a global install:

npx @aviaviavi/org2 --help

See Editor integrations and VS Code for setup details.

iOS app

Org2 Mobile is available as a private TestFlight beta and as source. To join the beta, email Avi for an invitation and include the email address you use with TestFlight. It is not currently distributed through the public App Store.

The iOS app can open a Files-visible local corpus for capture, Agenda, approvals, workflows, and file viewing. It can also control Mac-hosted AI chats over Tailscale: enable Mobile Remote in the Mac app's settings, create a one-time pairing code, and scan it from the iOS Remote tab. The Mac remains responsible for model access and corpus context and must be awake with Org2 Workspace running.

To build it yourself, open apps/ios/Org2Mobile/Org2Mobile.xcodeproj in Xcode, select your Apple development team, configure the group.org.org2.mobile App Group for the app and share extension, and run it on a simulator or device. See apps/ios/Org2Mobile/README.md for details.

Coming from Emacs Org mode?

You can use your existing Org directory directly. .org remains a first-class input format, so there is no required bulk conversion and no need to rename files before trying Org2.

Point the Mac app at the existing folder with Open an existing corpus, or try the CLI without changing anything:

org2 agenda --dir /path/to/your/org-directory --recursive

For new Org2-specific files, .org2 makes intent clearer. To edit them with Org mode, add this association:

(add-to-list 'auto-mode-alist '("\\.org2\\'" . org-mode))

Org2 carries forward outlines, TODO states, planning lines, properties, links, tables, source blocks, agendas, and publishing, but it is not a bug-for-bug clone of every Org mode behavior. Keep complex Babel setups, custom Emacs Lisp, specialized export backends, and heavily customized agenda behavior in Org mode until their Org2 behavior has been verified. Both tools can work over the same readable source where their semantics overlap.

See Using Org2 from Emacs, Org2 vs Org Mode, and Migration guidance.

Build from source

For contribution work or local dogfooding:

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

Build the optimized daily Mac app with:

npm run build:macos-app
open ~/Applications/Org2Workspace.app

Safer side-by-side development uses npm run build:macos-app:codex for debug or npm run build:macos-app:codex:release for optimized behavior. Both target the isolated Org2Workspace Codex.app rather than replacing the daily app.

Next steps

• See what Org2 can do

• Learn the macOS Workspace

• Connect agents safely

• Learn more of the file format

• Explore the CLI

• Check current semantics and maturity