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.

Celorga reimplements Org-mode's core features as a Node.js CLI:

.org files 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.

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.

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:

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.

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:

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.

Celorga adds several primitives beyond basic Org-mode:

:AGENT: properties map TODOs to runnable code 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.

Celorga's stateless design creates specific failure modes:

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:

Celorga makes sense when:

Avoid it when:

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.

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.