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://org2.avi.press/tooling-reference.html#plugins.

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

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://org2.avi.press/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 corpus documents as resources, authored workflows as prompts, and five typed tools for agent-profile resolution, durable runs, and background thread posting. It is 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://org2.avi.press/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 an optimized release binary by default. It assembles and verifies 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:

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; only the explicit :debug command authorizes that. 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.