org-workspace

Python library that makes org-mode files first-class citizens for AI agent workflows.

If you need to read and write org-mode task lists from Python — create tasks, transition states, query deadlines, or coordinate multiple agents over a shared org file — org-workspace is the library for it.

Built on a vendored fork of orgparse with write support (PR #77), it adds:

• Multi-file workspace management — load a directory, track dirty files, save only what changed
• Safe serialization — round-trip invariant: unmodified nodes are byte-identical on save
• GTD query layer — agenda(), deadlines(), overdue(), next_action(), ai_tasks()
• Concurrency primitives — TaskClaim (atomic claiming), OptimisticLock, FileLock
• Dependency DAG — parse DEPENDS_ON properties, topological sort, ready_tasks()

Install

pip install org-workspace

Quick start

from pathlib import Path
from org_workspace import OrgWorkspace, Query

# Load workspace
ws = OrgWorkspace(roots=[Path.home() / "org"])

# Query tasks
q = Query(ws)
next_up = q.next_action()
ai_tasks = q.ai_tasks(states=["TODO"])
deadlines = q.deadlines(days=14)

# Create a task
task = ws.create_node(
    file=Path.home() / "org" / "inbox.org",
    heading="Research org-mode parsing",
    state="TODO",
    tags=["AI", "research"],
    body="Investigate approaches for org-mode mutation",
)

# Transition state
ws.transition(task, "DONE", agent="my-agent")

# Save changes (only modified files are written)
ws.save()

Documentation

• Quick start guide — from install to first AI-readable task list in five minutes
• Comparison: org-workspace vs orgparse vs organice — factual feature comparison for developers choosing a library

Features

Workspace management

• Multi-file loading with dirty-file tracking
• Content-addressed ID generation with dedup
• Round-trip safe serialization (zero byte-diff on unchanged files)

NodeView pattern

• Stateless, non-caching read-only views over org nodes
• Generation-counter staleness detection
• Safe for concurrent access patterns

Mutations (via OrgWorkspace)

• create_node() — create headings with state, tags, properties, body
• refile() — move nodes between files preserving subtree
• remove_node() — delete nodes from files
• transition() — state changes with LOGBOOK entries
• set_property(), set_heading(), set_tags()

Query system

• agenda(), deadlines(), overdue(), stale()
• by_state(), by_tag(), by_property()
• ai_tasks() — find :AI: tagged tasks for agent execution
• next_action() — GTD next action selection

Dependency DAG (Plan)

• Parse DEPENDS_ON properties into dependency graphs
• Topological sort for execution ordering
• ready_tasks(), blocked_tasks(), cycle detection

Concurrency

• FileLock — file-level locking
• OptimisticLock — hash-based conflict detection
• TaskClaim — agent-level task claiming with staleness timeout
• multi_lock() — deadlock-free multi-file locking (lexicographic order)

LOGBOOK and session logging

• add_logbook_entry(), add_state_change_entry(), add_clock_entry()
• SessionLog for buffered per-session logging

Archive

• archive_node() — archive with hierarchy preservation
• archive_done() — bulk archive completed tasks
• archive_plan() — archive entire dependency plans

Context extraction (for AI agents)

• build_execution_context() — structured context from task properties
• get_prompt() — PROMPT property with body fallback
• get_role() — agent persona from ROLE property

GTD state configuration

from org_workspace import StateConfig

# Default GTD states
config = StateConfig.default()
# sequences: {"gtd": ["TODO", "NEXT", "WAITING", "DONE"]}

# With nightshift (autonomous execution) states
config = StateConfig.nightshift()
# adds: QUEUED, EXECUTING, REVIEW, FAILED

License

BSD 2-Clause. See LICENSE.

This library includes a vendored copy of orgparse (BSD 2-Clause, Copyright 2012 Takafumi Arakaki) with modifications from datacore-one/orgparse PR #77 adding write support.