1) Install the Mac app

OpenOrg is the recommended starting point. It gives you capture, daily notes, Agenda, search, rendered files, agent threads, and Agent Work without requiring you to learn the Org2 format first.

1. Download the latest OpenOrg.dmg from the downloads page.

2. Open the disk image and drag OpenOrg.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.

OpenOrg creates a small Org2 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. OpenOrg never requires an app-specific canonical database.

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

The public 0.4.2 Org2 Workspace downloads are developer-signed but not notarized. OpenOrg Alpha ships after its Developer ID build passes Apple notarization, has a stapled ticket, and opens normally through Gatekeeper.

2) Capture one scheduled commitment

Open Capture, keep Task selected, give the commitment a concrete title, and leave Scheduled enabled for today. OpenOrg appends the task to today's daily note and refreshes Agenda.

Open Agenda and select the task. The task stays connected to the source file and any surrounding decision, meeting, or project context.

You can also click New Note 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 for everyday work and open the readable source 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) Ask an agent for bounded work

AI is optional. Your files work without a model or agent.

To connect one, open OpenOrg → Settings… → AI Chat. Add or enable a named local, remote, hosted, or self-hosted destination. Agents outside the native app can use the same corpus through CLI JSON and MCP.

With the captured task selected, open AI Chat and ask for one concrete outcome with a clear boundary:

Prepare a one-page launch brief using this task and its linked context. Cite every input and leave the result for review; do not publish or message anyone.

The destination is replaceable. OpenOrg records the selected files, thread, run, citations, and resulting artifact as durable workspace context.

5) Review the cited result

Open Agent Work. Inspect the run status, cited inputs, artifact, validation, and anything awaiting approval. Approve, revise, or reject consequential work based on that evidence.

Finally, reveal the workspace in Finder and open the resulting .org2 file in another editor. The first useful loop ends with portable work you control.

Know what leaves your Mac

Your workspace is an ordinary folder on your Mac. OpenOrg does not require a hosted corpus account. Context leaves the Mac when you send it to an agent, model, or source provider you configured, so choose destinations whose retention and data-use policies fit your work.

• Provider tokens and other credentials belong in macOS Keychain or another machine-local protected store.

• External messages, publication, deletion, and other consequential actions require an explicit approval.

• Back up the workspace folder with Git, Time Machine, iCloud Drive, Syncthing, or another file-oriented system you understand.

Open Agent Work to inspect cited inputs, artifacts, validation, pending decisions, and failures. For help with a reproducible issue, use GitHub issues with sanitized diagnostics; never attach credentials or private corpus content.

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. Org2 keeps source locations and backlinks, so a person, project, meeting, or decision stays 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.

Configure more agent workflows

You can create a shared room and explicitly mention multiple destinations with @mentions or @all. Each response stays attributed to the agent that produced it, and the corpus provides durable context across every destination.

Try a source-finding 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.

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, including where they came from and which decisions shaped them.

Prefer an editor? Start there instead

The Mac app is the easiest onramp. You can also install the Org2 extension in VS Code 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

OpenOrg for iOS 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, and file viewing. Its AI sidebar can also control Mac-hosted chats over Tailscale: enable Mobile Remote in the Mac app's settings, create a one-time pairing code, then open Settings → Connect a Mac from the iOS sidebar and scan it. The Mac remains responsible for model access and corpus context and must be awake with OpenOrg running. Workflow controls are intentionally desktop-only for now.

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. Org2 accepts .org as 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 supports outlines, TODO states, planning lines, properties, links, tables, source blocks, agendas, and publishing. 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/OpenOrg.app

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 OpenOrg Preview.app and leave the daily app untouched.

Next steps

• See what OpenOrg can do

• Learn OpenOrg for macOS

• Connect agents and models

• Learn more of the file format

• Explore the CLI

• Check current semantics and maturity