aviaviavi

@bugarela org-mode still ... with emacsclient to automate some things, but maybe trying aviaviavi/celorga

Celorga: Org-Mode as Agent Orchestration Infrastructure Celorga strips Emacs Org-mode down to a standalone CLI and rebuilds it as agent infrastructure. The project exposes TODO items, agenda views, and structured notes as MCP server tools, turning 15 years of plaintext task management conventions into coordination primitives for multi-agent workflows. The architecture is interesting because it decouples the data format (Org-mode's plaintext structure) from the editor (Emacs) and adds agent-facing APIs without breaking compatibility. You get a portable task manager that agents can read, write, and trigger actions from. What Celorga Actually Does Celorga reimplements Org-mode's core features as a Node.js CLI: - Agenda management (scheduled tasks, deadlines, recurring items) - Structured editing (headlines, properties, tags, links) - Search and filtering across .org files - Native Mac and iOS apps for human interaction - MCP server that exposes these capabilities as agent tools The MCP server is the bridge. It wraps Org-mode operations (query agenda, update TODO state, add notes) as callable functions that any MCP-compatible agent can invoke. This means Claude Desktop, custom harnesses, or any tool speaking the Model Context Protocol can treat your task list as a structured API. Architecture: Plaintext as State, MCP as Interface The stack looks like this: ┌─────────────────────────────────────┐ │ Agent (Claude, custom harness) │ └─────────────┬───────────────────────┘ │ MCP protocol ┌─────────────▼───────────────────────┐ │ Celorga MCP Server │ │ - agenda_query() │ │ - update_todo() │ │ - add_note() │ │ - trigger_agent() │ └─────────────┬───────────────────────┘ │ File I/O ┌─────────────▼───────────────────────┐ │ .org files (plaintext) │ │ * TODO Deploy staging │ │ SCHEDULED: <2026-10-20> │ │ :PROPERTIES: │ │ :AGENT: deploy-bot │ │ :END: │ └─────────────────────────────────────┘ State lives in plaintext .org files on disk. The MCP server parses these files, exposes structured operations, and writes changes back. Native apps and the CLI read the same files, so humans and agents share a single source of truth. The "kick off your agents easily from any TODO" feature works through custom properties. You tag a TODO item with an :AGENT: property pointing to a script, API endpoint, or agent harness. When the MCP server's trigger_agent() tool is called, it reads the property and spawns the corresponding process or makes the HTTP call. State Synchronization Without a Server Celorga avoids a central server by treating the filesystem as the coordination layer. All clients (CLI, native apps, MCP server) read and write the same .org files. Conflicts are handled at the file level using standard merge strategies. This works because Org-mode's format is line-oriented and human-readable. Git or Syncthing can merge changes without understanding the semantics. The MCP server doesn't hold state; it's a stateless adapter that translates MCP calls into file operations. Trade-offs: | Approach | Conflict Handling | Latency | Complexity | |----------|------------------|---------|------------| | Filesystem sync | Manual merge or last-write-wins | Local read/write speed | Low (no server) | | Central server | Operational transform or CRDT | Network round-trip | High (server ops, auth) | | Event log | Append-only, deterministic replay | Depends on log storage | Medium (replay logic) | Celorga picks filesystem sync because Org-mode users already expect to manage .org files in Git or Dropbox. The format's plaintext nature makes conflicts visible and resolvable. MCP Server Implementation The MCP server exposes Org-mode operations as tools. Here's what a typical tool definition looks like: { name: "agenda_query", description: "Query TODO items matching criteria", inputSchema: { type: "object", properties: { tags: { type: "array", items: { type: "string" } }, state: { type: "string", enum: ["TODO", "DONE", "WAITING"] }, scheduled_before: { type: "string", format: "date" } } } } When an agent calls agenda_query, the server: 1. Parses all .org files in the configured directory 2. Filters TODO items by tags, state, and date 3. Returns structured JSON with headline, properties, and context The trigger_agent tool reads the :AGENT: property from a TODO item and executes it. If the property is a shell command, it spawns a subprocess. If it's a URL, it makes an HTTP POST with the TODO's context as JSON payload. This design lets you wire up arbitrary automation without hardcoding agent types. A TODO item can trigger a GitHub Actions workflow, a local Python script, or another MCP server. Agent Coordination Primitives Celorga adds several primitives beyond basic Org-mode: - Structured output: MCP tools return JSON, not raw Org syntax - Execution hooks: :AGENT: properties map TODOs to runnable code - State transitions: Agents can move items between TODO/DONE/WAITING - Context injection: When triggering an agent, Celorga passes the full TODO context (tags, properties, notes) These primitives turn a task list into a lightweight orchestration layer. You can model multi-step workflows as nested TODO trees, where each item triggers a different agent and the parent tracks overall progress. Example workflow: * TODO Deploy new feature ** TODO Run tests :PROPERTIES: :AGENT: pytest-runner :END: ** TODO Build container :PROPERTIES: :AGENT: docker-build :END: ** TODO Push to staging :PROPERTIES: :AGENT: kubectl-deploy :END: An agent queries the agenda, sees the top-level TODO, and walks the subtree. It calls trigger_agent on each child in sequence, updating their state as they complete. Failure Modes and Observability Celorga's stateless design creates specific failure modes: - Concurrent writes: Two agents updating the same .org file simultaneously can corrupt it. Celorga doesn't implement file locking, so you need external coordination (like a queue) if multiple agents write frequently. - Parse errors: Malformed Org syntax breaks the MCP server. There's no schema validation on the plaintext, so agents or humans can introduce unparseable content. - Trigger failures: If an :AGENT: property points to a missing script or dead endpoint, the trigger_agent call fails silently unless you add logging. Observability is minimal. The MCP server logs tool calls to stdout, but there's no built-in tracing or metrics. You'd need to wrap the server in a logging proxy or instrument the triggered agents themselves. For production use, you'd want: - File locking or optimistic concurrency control - Schema validation on .org files (perhaps a pre-commit hook) - Structured logging with correlation IDs across agent invocations - Dead letter queue for failed triggers When to Use Celorga Celorga makes sense when: - You already use Org-mode and want to expose it to agents - You need a lightweight orchestration layer without standing up a workflow engine - Your agents are loosely coupled and can tolerate eventual consistency - You value plaintext portability over real-time collaboration Avoid it when: - Multiple agents need to write concurrently with strong consistency - You need built-in observability, retries, or dead letter queues - Your workflows require complex state machines or branching logic - You don't want to manage .org file sync across machines The project is most useful as a bridge between personal knowledge management and agent automation. If you're already tracking work in Org-mode, Celorga lets you hand off tasks to agents without migrating to a dedicated orchestration platform. Technical Verdict Celorga demonstrates how structured plaintext can serve as agent coordination infrastructure when you add the right APIs. The MCP server is a thin adapter that preserves Org-mode's simplicity while making it agent-callable. The architecture is appropriate for personal automation and small-team workflows where eventual consistency is acceptable. For production systems with high concurrency or strict observability requirements, you'd need to add locking, validation, and instrumentation layers. The interesting insight is that task management and agent orchestration share the same primitives: state transitions, scheduling, context passing, and execution triggers. Celorga exposes this overlap by treating TODO items as orchestration nodes. Source Links - Celorga GitHub Repository - Celorga Homepage - npm Package - Show HN Discussion

Show HN: Celorga – A portable re-implementation of Org for you and your agents I've been a heavy user of Emacs Org mode for a decade and a half. As AI has reduced how often I'm using a text-editor, I was finding myself tied to spacemacs just for Org, and I was searching for a way to keep those workflows and notes, but be fully decoupled from Emacs. (I blogged about that here: avi.press, the original idea for this project). Today I'm excited to launch Celorga: a portable re-implementation of Org, with no dependency on Emacs or elisp, and adds many primitives so you can use it with all of your agents. Celorga offers a portable CLI that covers most core Org capabilities like agenda management, structured editing, searching, and more. It also well offers a tons of capabilities for working with all of your agents (any agent, any harness), like an MCP server, and the ability to kick off your agents easily from any TODO in your notes. It offers most capabilities of multi-agent harnesses today, but aimed at a more general workload than just coding. I believe at this point, Celorga is most polished Org experience outside of Emacs. It comes with native Mac and iOS apps (Linux & android coming soon). Fully OSS, Apache 2. - GitHub: aviaviavi/celorga - Homepage: celorga.io - Install the CLI from npm: npmjs.com Feedback is welcome!

Follow-up: org2 is now Celorga. No new file format, just Org outside Emacs I recently posted here about org2, a project to use Org outside of Emacs. Thanks to everyone who tried it and left feedback. The strongest and most recurring feedback from the org community was: 1. The name was bad, for several reasons. 2. A new file format was not required for the expanded functionality we were trying to support. (We tried using a new .org2 extension to have separate support for some of our new features, rather than using Org's extensibility on top of the existing standard.) I agreed with both, so here's what's changed:  - It's called Celorga now. One name for the app, the runtime, and the CLI. - Celorga reads and writes ordinary .org files, no more .org2 format. Point it at your existing org folder: there's nothing to import or convert, for full compatibility with your current workflow and tools. - It's not being positioned as a successor to Org mode anymore. Celorga is an independent implementation of the Org format, not affiliated with GNU Org, and it doesn't try to replace Emacs. Use it alongside Emacs or instead of it. Why you might want it if: - You want a polished Org experience outside of Emacs. On a Mac, Celorga is a native app with a rendered reading view, source editing, an agenda built from all your files, backlinks, search, agent orchestration, and a whole lot more. There's an iPhone app to mange your agenda, approvals, etc from your phone. - You want your agents working in an Org-centered workflow. Claude Code, Codex, OpenCode, and others can all read and cite your notes, and easily hand off any TODOs to your agents. It also introduces a new Org-level primitive for Approvals, so you can sign off any any outputs or actions from your agents. Your notes stay the shared context, in plain text you own. Note that Celorga is a complete Org app even if you don't hook up any AI at all! - You're building something new on top of Org files. The parser, semantics, CLI, and language server run without Emacs anywhere in the stack. The npm cli gives the entire API across agenda queries, search, structured edits, and more. All with JSON output, so a script, server, or agent doesn't have to bundle Emacs or write yet another partial parser. - The CLI even offers a full MCP server, so your agents can all interact with your Org notes, even remotely. It's free, open source (Apache-2.0), and needs no account. The Mac app is macOS-only for now (Linux coming soon). The CLI runs anywhere Node does. Homepage: celorga.io For Org users: celorga.io Download: celorga.io Source: aviaviavi/celorga Thanks for reading, looking forward to any more feedback!