mech.app

Posted on Oct 19 Originally published at mech.app

Celorga: Org-Mode as Agent Orchestration Infrastructure

#agents #cli #mcp #node

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:

Parses all .org files in the configured directory
Filters TODO items by tags, state, and date
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.

DEV Community