OpenOrg and Org2

OpenOrg is a local-first suite of apps for building knowledge locally and putting it to work with people and AI agents. Org2 is the independently specified compiler/runtime and semantic profile that powers those apps, plus the CLI, npm package, schemas, and editor tooling. Human-facing documents use ordinary .org files by default; existing .org2 files and structured runtime records remain supported. This repository contains both the shared Org2 foundation and the OpenOrg apps built on it; repository and developer identifiers remain Org2 for compatibility.

The initial plugin runtime installs self-contained Git packages through org2 plugin, pins exact commits and SHA-256 contents in a corpus lock file, and requires machine-local trust before contributed CLI commands or sandboxed document renderers execute. The same renderer contribution is used by CLI HTML export and OpenOrg; there is no separate native-app plugin ABI. See https://openorg.so/tooling-reference.html#plugins.

OpenOrg product site: https://openorg.so/ Current developer docs: https://openorg.so/

For now, the canonical project docs live on the website.

The independently implementable Org2 v0 language standard lives under spec/v0/. It combines a normative surface grammar, deterministic contextual parsing rules, the canonical AST schema, and executable conformance cases. The optimized TypeScript parser and editor parsers implement that contract; they do not define separate language dialects.

Agent discovery

After installing the CLI, agents can inspect the exact capabilities of that version without relying on model memory:

org2 agent capabilities
org2 agent --help

The first command emits the versioned org2:capabilities:v1 JSON manifest with workflow families, safety rules, client roles, and canonical documentation links. See https://openorg.so/agent-quickstart.html.

MCP and the general Org2 skill

Connect any stdio MCP client to one explicit corpus with:

org2 mcp serve --dir /absolute/path/to/notes

The server exposes canonical corpus documents as paginated resources, authored workflows as prompts, and eight typed tools: bounded cited search, stable-ID fetch, context assembly, agent-profile resolution, durable runs, and background thread posting. The headless OpenOrg server can expose the five read-only tools through bearer-authenticated Streamable HTTP while retaining hash-only, per-client credentials. It remains intentionally narrower than the CLI.

The npm package also ships a portable general skill. Its installer previews by default and never overwrites a corpus-managed copy:

org2 skill install --dir /absolute/path/to/notes
org2 skill install --dir /absolute/path/to/notes --apply

See https://openorg.so/mcp-and-skills.html for Codex, Claude Code, and generic client setup; the exact MCP resource/tool surface; safety boundaries; and the CLI fallback contract.

Development

Run the full test suite with:

npm test

Benchmark read-only CLI operations against a representative corpus with:

npm run benchmark:cli -- --dir /path/to/corpus
npm run benchmark:cli -- --dir /path/to/corpus --suite full --runs 3

The interactive suite covers startup, agenda, search, approvals, and an isolated full index build. The full suite also covers full and incremental compilation, lint, graph audit, and cold/warm agent context. Index and cache output is redirected to a temporary directory; the source corpus and its live index are not modified.

The normal test suite also includes a reproducible performance regression test over a generated 500-file, 5,500-node corpus. Run it independently with:

npm run test:performance

It enforces explicit budgets for CLI startup, compilation, lint, graph audit, cold/warm agent context, and a one-file incremental rebuild. On known slower CI hardware, multiply all budgets with ORG2_PERF_BUDGET_SCALE=2 npm run test:performance rather than weakening the checked-in defaults.

Build or update the local macOS app bundle with:

make macos-app

The equivalent npm script is npm run build:macos-app. The daily-app command builds a self-contained development bundle with Swift’s shared incremental debug cache, so focused Swift tests and app builds reuse the same compiled objects instead of recompiling the large workspace module under -O. The explicit :release variant retains whole-module optimization for distribution and performance validation. Both paths assemble and verify a complete staged app before replacing the installed bundle, so a failed build leaves the existing app untouched. Use the explicit variants when switching modes during development:

make macos-app-restart

The restart target keeps the installed OpenOrg running throughout compilation and staged-bundle verification. Once the replacement is ready, it asks OpenOrg to save and quit (sending Quit again after five seconds if it is still running), atomically installs the verified bundle, and immediately reopens it. If the build fails, the running app is not interrupted. This is a short restart rather than hot reload, so active recordings and provider turns should be allowed to finish first.

npm run build:macos-app:restart
npm run build:macos-app:release
npm run build:macos-app:debug
npm run build:macos-app:codex          # isolated debug app
npm run build:macos-app:codex:release  # isolated optimized app

The build refuses to place an implicit debug binary at the daily app’s bundle identifier; the normal local-fast command and explicit :debug command are the two authorized development modes. The app reports Debug or Optimized release under its audio/runtime settings, and the bundle records the same mode as Org2BuildConfiguration in Info.plist.

By default this writes to ~/Applications/OpenOrg.app, signs it with bundle id org.org2.workspace, and uses the first available stable code-signing identity. Stable signing matters for macOS Screen/System Audio permissions; ad-hoc signing changes the app’s TCC identity on each rebuild. Override the signing identity with ORG2_WORKSPACE_CODE_SIGN_IDENTITY, or set it to adhoc to force ad-hoc signing. Override the app path or bundle id with ORG2_WORKSPACE_APP_PATH or ORG2_WORKSPACE_BUNDLE_ID when needed. On Apple Silicon it builds arm64 by default; override with ORG2_WORKSPACE_SWIFT_ARCH if needed.

The isolated development commands write OpenOrg Preview.app. Release packaging uses tools/package-openorg-macos.mjs to build in temporary staging, preserve the compatibility identifiers, apply hardened runtime, notarize and staple the DMG, and verify it with Gatekeeper. It never writes to the daily app path.

The canonical test layout is test/ for Node test scripts, with feature subdirectories for nearby fixtures when useful. Agent/context-pack coverage lives under test/agent/; run a targeted agent test with node test/agent/test-agent-context.mjs after npm run build.