1) Install the Mac app

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

2. Open the disk image and drag the app (OpenOrg.app) into Applications.

3. Open the app. Connect an agent you already use, or choose to continue without one.

4. Choose Continue to Home.

Celorga creates a small workspace automatically, then opens Home with today's note and an optional chat box. Everything is plain text that you can inspect in Finder, Git, or another editor. Celorga never requires an app-specific canonical database.

If you already keep notes in another folder, expand Workspace options during setup or open it later. Use Celorga → Settings… → General to rename the corpus identity, reveal its folder, or switch locations.

2) Write today's note

Type a thought, decision, or rough plan directly into today's note on Home. The note is an ordinary local file, and you can bring it into an agent conversation later if useful.

If you connected an agent, you can also try:

Help me turn today's rough notes into a short plan. Show me the proposed structure before changing any files.

3) Capture one scheduled commitment

Open Capture, keep Task selected, give the commitment a concrete title, and leave Scheduled enabled for today. Celorga 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, the note is a simple Org 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.

4) 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. To revisit another day, choose Daily → Choose Date… in the sidebar or press Cmd-Shift-7; Celorga opens the existing note or creates it in the configured daily folder. If an external job creates your daily files, enable Disable automatic daily note creation in Settings → General. A missing date will then show a message and a Create Daily Note button without writing anything automatically.

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.

When you're ready: the mental model

Celorga is the shared workspace that holds and coordinates work; it is not one autonomous agent that is always awake inside your notes. Your corpus (the ordinary folder of .org and related files) is the durable memory and source of truth. Celorga turns those files into useful views, gives configured agents bounded access to them, and keeps delegated work and decisions inspectable across every agent you use.

The agent harness you connect is a runtime: the engine that actually reasons and acts. Codex, Claude Code, Pi, OpenCode, and OpenClaw are the runtimes Celorga supports out of the box today, but they are examples rather than the architecture. Other local, remote, hosted, or self-hosted harnesses can use the same files and Celorga interfaces as adapters are added.

A runtime sees the current conversation, the context you selected or authorized, the active corpus's instructions and capabilities, and the tools Celorga exposes for that turn or run. It does not silently absorb the whole workspace or keep watching it after the turn ends.

That leads to a useful rule: put durable intent in the corpus, not only in chat. Chat is a good place to explore and ask for help setting something up, but the result should become the appropriate inspectable record when you want Celorga to remember or repeat it.

Agent profiles are not background processes, and a goal does not execute itself. A profile says who this worker is across runtimes; a workflow says how this recurring process works; a run records what happened this time; and a runtime supplies the actual compute.

Review approvals and agent work

For a bounded delegated task, select the relevant note or commitment and ask for one concrete outcome. Celorga records the selected files, thread, run, citations, and resulting artifact as durable workspace context.

Open Agent Work for one queue across every configured runtime. Inspect what is blocked, answer clarifying questions, and review the run status, cited inputs, artifacts, and validation before you approve, revise, or reject consequential work.

Finally, reveal the workspace in Finder and open the resulting .org 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. Celorga 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. Celorga keeps source locations and backlinks, so a person, project, meeting, or decision stays connected to the work that came from it.

Celorga's agent connection is provider-neutral. Other local, remote, hosted, or self-hosted tools can work with the same corpus through CLI JSON and MCP interfaces: local stdio MCP or the headless server's read-only Streamable HTTP MCP endpoint. Codex, Claude Code, Pi, OpenCode, and OpenClaw are convenient built-in starting points, not requirements. A hosted service still needs a reachable authenticated HTTPS path to the private endpoint.

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, Celorga 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 Celorga 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 celorga
org2 --version
celorga agenda --dir /path/to/your/corpus --recursive
celorga agenda --dir /path/to/your/corpus --recursive --tui

You can try the CLI without a global install:

npx celorga --help

See Editor integrations and VS Code for setup details.

iOS app

Celorga 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. Corpus-backed projects appear in that sidebar with their active chats; project menus create a chat in-place, and thread menus add or remove project membership through the canonical project note on the host. Settled chats remain available under Settled without cluttering their project groups. The selected host remains responsible for model access and corpus context. You can also pair with a headless Celorga server to keep chats available without the laptop. Updated iOS builds save multiple hosts under Host Connection.

Long chats display a page of messages at a time. Use Earlier messages, Newer messages, or Back to latest messages to navigate the complete history. Large messages show a preview with Read full message; copying a message always includes its complete text.

The chat microphone keeps the screen awake while dictation is recording so you can follow the live transcript without touching the phone. Normal auto-lock behavior resumes when recording stops. Leaving the app stops recording and preserves the draft.

Developers can also build the iOS app from source.

Coming from Emacs Org mode?

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

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

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

Celorga 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 Celorga behavior has been verified. Both tools can work over the same readable source where their semantics overlap.

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

Build from source

For contribution work or local dogfooding:

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

Build the self-contained daily Mac app for local development with:

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

This command reuses the incremental debug cache shared with Swift tests, which keeps the edit-build loop short. Use npm run build:macos-app:release when you specifically need an optimized distribution or performance-validation build. Keep the Swift package's .build/ directory between iterations; SwiftPM rebuilds changed inputs automatically. Standalone Mac DMG packaging and coordinated releases also reuse persistent, architecture-specific Swift caches under ~/Library/Caches/OpenOrg/release-build/. Override the cache root with OPENORG_RELEASE_BUILD_CACHE when needed.

For a local dogfooding loop, make macos-app-restart (or npm run build:macos-app:restart) leaves the current daily app open while it compiles and verifies a staged replacement. It requests a graceful quit only when the new bundle is ready, swaps the bundle atomically, and reopens Celorga. A failed build leaves the running app untouched. This is a short restart rather than hot reload; finish active recordings or provider turns before invoking it.

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 Celorga can do

• Learn Celorga for macOS

• Connect agents and models

• Learn more of the file format

• Explore the CLI

• Check current semantics and maturity