1---
  2name: Org
  3description: Org-mode file manipulation using Emacs batch mode. USE WHEN you need to programmatically read, parse, or modify org-mode files (.org) for TODOs, notes, or other structured content.
  4---
  5
  6# Org-Mode File Manipulation
  7
  8## Purpose
  9Provide reliable, programmatic access to org-mode files using Emacs batch mode and the org-element API. This skill is used by other skills (TODOs, Notes) for org-mode operations.
 10
 11### Context Detection
 12
 13**This skill activates when:**
 14- Other skills need to manipulate org-mode files
 15- Parsing TODO items, denote notes, or org content
 16- Updating TODO states, scheduling, or properties
 17- Querying org-mode structure or metadata
 18- Working with files ending in `.org`
 19
 20## Tool: org-manager
 21
 22### Location
 23`tools/org-manager` - Bash CLI wrapper around Emacs batch mode
 24
 25### Usage
 26
 27#### TODO Operations
 28```bash
 29# List TODOs
 30./tools/org-manager list ~/desktop/org/todos.org --state=NEXT
 31
 32# Add TODO
 33./tools/org-manager add ~/desktop/org/todos.org "Task name" \
 34  --section=Work --priority=2 --scheduled=2025-12-10
 35
 36# Update state
 37./tools/org-manager update-state ~/desktop/org/todos.org "Task name" DONE
 38
 39# Count by state
 40./tools/org-manager count ~/desktop/org/todos.org
 41
 42# Get scheduled items
 43./tools/org-manager scheduled ~/desktop/org/todos.org
 44
 45# Search
 46./tools/org-manager search ~/desktop/org/todos.org "term"
 47
 48# Get full TODO content (metadata + body)
 49./tools/org-manager get ~/desktop/org/todos.org "Task name"
 50
 51# Get overdue tasks (deadline before today)
 52./tools/org-manager overdue ~/desktop/org/todos.org
 53
 54# Get upcoming tasks (scheduled/deadline in next N days)
 55./tools/org-manager upcoming ~/desktop/org/todos.org --days=7
 56```
 57
 58#### Tag Management
 59```bash
 60# List all unique tags in file
 61./tools/org-manager list-tags ~/desktop/org/todos.org
 62
 63# Add tags to existing TODO
 64./tools/org-manager add-tags ~/desktop/org/todos.org "Task name" "urgent,review"
 65
 66# Remove specific tags
 67./tools/org-manager remove-tags ~/desktop/org/todos.org "Task name" "urgent"
 68
 69# Replace all tags with new set
 70./tools/org-manager replace-tags ~/desktop/org/todos.org "Task name" "done,archived"
 71```
 72
 73#### Property Operations
 74```bash
 75# List all properties of a heading
 76./tools/org-manager list-properties ~/desktop/org/todos.org "Task name"
 77
 78# Get specific property value
 79./tools/org-manager get-property ~/desktop/org/todos.org "Task name" "PR_URL"
 80
 81# Set property value
 82./tools/org-manager set-property ~/desktop/org/todos.org "Task name" "STATUS" "In Progress"
 83```
 84
 85#### Bulk Operations
 86```bash
 87# Update all tasks matching a state to a new state
 88./tools/org-manager bulk-update-state ~/desktop/org/todos.org "TODO" "DONE"
 89
 90# Update with tag filter (only tasks with specific tags)
 91./tools/org-manager bulk-update-state ~/desktop/org/todos.org "TODO" "DONE" "work,urgent"
 92
 93# Add tags to all tasks with a specific state
 94./tools/org-manager bulk-add-tags ~/desktop/org/todos.org "NEXT" "urgent,review"
 95
 96# Set priority for all tasks with a specific state
 97./tools/org-manager bulk-set-priority ~/desktop/org/todos.org "TODO" 1
 98```
 99
100#### Time Tracking
101```bash
102# Start time tracking on a task
103./tools/org-manager clock-in ~/desktop/org/todos.org "Implement feature X"
104
105# Stop time tracking (clocks out of currently active task)
106./tools/org-manager clock-out ~/desktop/org/todos.org
107
108# Check what task is currently being tracked
109./tools/org-manager get-active-clock ~/desktop/org/todos.org
110
111# Get total time spent on a task (returns minutes)
112./tools/org-manager get-clocked-time ~/desktop/org/todos.org "Implement feature X"
113```
114
115#### Statistics & Analytics
116```bash
117# Get comprehensive statistics (counts by state, priority, tags, overdue, etc.)
118./tools/org-manager get-statistics ~/desktop/org/todos.org
119
120# Get priority distribution across all tasks
121./tools/org-manager get-priority-distribution ~/desktop/org/todos.org
122
123# Get tag usage statistics (sorted by frequency)
124./tools/org-manager get-tag-statistics ~/desktop/org/todos.org
125```
126
127#### Export & Reporting
128```bash
129# Export to CSV for spreadsheet analysis
130./tools/org-manager export-csv ~/desktop/org/todos.org /tmp/todos.csv
131
132# Export to JSON for programmatic processing
133./tools/org-manager export-json ~/desktop/org/todos.org /tmp/todos.json
134```
135
136#### Recurring Tasks
137```bash
138# Set repeater for a task (+1w = weekly, .+2d = 2 days after completion)
139./tools/org-manager set-repeater ~/desktop/org/todos.org "Weekly Review" "+1w"
140
141# Get all recurring tasks
142./tools/org-manager get-recurring-tasks ~/desktop/org/todos.org
143```
144
145#### Dependencies & Relationships
146```bash
147# Set a blocker for a task
148./tools/org-manager set-blocker ~/desktop/org/todos.org "Deploy to production" "Complete testing"
149
150# Get blocker for a specific task
151./tools/org-manager get-blocker ~/desktop/org/todos.org "Deploy to production"
152
153# List all blocked tasks
154./tools/org-manager get-blocked-tasks ~/desktop/org/todos.org
155
156# Create task relationship (child/parent/related/depends-on)
157./tools/org-manager set-related ~/desktop/org/todos.org "Implement feature" "Design review" "depends-on"
158
159# Get all relationships for a task
160./tools/org-manager get-related ~/desktop/org/todos.org "Implement feature"
161```
162
163#### Denote Operations
164```bash
165# Create denote-formatted note
166./tools/org-manager denote-create "My Note Title" "tag1,tag2,tag3" \
167  --category=homelab --directory=~/desktop/org/notes
168
169# Create with signature (for automated notes)
170./tools/org-manager denote-create "Session Log" "history,session" \
171  --signature=pkai --category=history
172
173# Read note metadata
174./tools/org-manager denote-metadata ~/desktop/org/notes/20251205T*.org
175
176# Update note frontmatter
177./tools/org-manager denote-update ~/desktop/org/notes/20251205T*.org \
178  --title="New Title" --tags="new,tags" --category="updated"
179
180# Append content to note
181echo "* New Section" > /tmp/content.org
182./tools/org-manager denote-append ~/desktop/org/notes/20251205T*.org /tmp/content.org
183```
184
185### Output Format
186
187All commands return JSON:
188
189```json
190{
191  "success": true,
192  "data": [
193    {
194      "heading": "Task name",
195      "todo": "NEXT",
196      "priority": 2,
197      "tags": ["tag1"],
198      "level": 2,
199      "scheduled": "2025-12-05",
200      "deadline": null
201    }
202  ]
203}
204```
205
206## Implementation
207
208### Core Functions (batch-functions.el)
209
210**TODO Operations:**
211- `org-batch-list-todos` - Parse and filter TODOs
212- `org-batch-scheduled-today` - Get scheduled items
213- `org-batch-by-section` - Filter by section
214- `org-batch-count-by-state` - Count statistics
215- `org-batch-search` - Full-text search
216- `org-batch-get-children` - Get direct children of a heading
217- `org-batch-get-sections` - List all top-level sections
218- `org-batch-get-todo-content` - Get full TODO content (metadata + body + properties)
219- `org-batch-get-overdue` - Get tasks with deadline before today
220- `org-batch-get-upcoming` - Get tasks scheduled/due in next N days
221- `org-batch-add-todo` - Add new TODO
222- `org-batch-update-state` - Change states
223- `org-batch-schedule-task` - Set SCHEDULED
224- `org-batch-set-deadline` - Set DEADLINE
225- `org-batch-set-priority` - Set priority
226- `org-batch-archive-done` - Archive items
227
228**Tag Operations:**
229- `org-batch-add-tags` - Add tags while preserving existing
230- `org-batch-remove-tags` - Remove specific tags
231- `org-batch-replace-tags` - Replace all tags with new set
232- `org-batch-list-all-tags` - Get all unique tags in file
233
234**Property Operations:**
235- `org-batch-get-property` - Get specific property value
236- `org-batch-set-property` - Set property value
237- `org-batch-list-properties` - List all properties of a heading
238
239**Bulk Operations:**
240- `org-batch-bulk-update-state` - Update all tasks matching a state
241- `org-batch-bulk-add-tags` - Add tags to all tasks with specific state
242- `org-batch-bulk-set-priority` - Set priority for all tasks with specific state
243
244**Time Tracking:**
245- `org-batch-clock-in` - Start time tracking on a task
246- `org-batch-clock-out` - Stop time tracking
247- `org-batch-get-active-clock` - Get currently clocked task
248- `org-batch-get-clocked-time` - Get total time spent on a task
249
250**Statistics & Analytics:**
251- `org-batch-get-statistics` - Comprehensive statistics (counts, priorities, tags, overdue)
252- `org-batch-get-priority-distribution` - Priority distribution across tasks
253- `org-batch-get-tag-statistics` - Tag usage statistics
254
255**Export & Reporting:**
256- `org-batch-export-csv` - Export TODOs to CSV format
257- `org-batch-export-json` - Export TODOs to JSON format
258
259**Recurring Tasks:**
260- `org-batch-set-repeater` - Set repeater specification for a task
261- `org-batch-get-recurring-tasks` - List all tasks with repeaters
262
263**Dependencies & Relationships:**
264- `org-batch-set-blocker` - Set task blocker
265- `org-batch-get-blocker` - Get blocker for a task
266- `org-batch-get-blocked-tasks` - List all blocked tasks
267- `org-batch-set-related` - Create task relationships (child/parent/related/depends-on)
268- `org-batch-get-related` - Get all relationships for a task
269
270### Denote Functions (denote-batch-functions.el)
271
272**Note Creation and Management:**
273- `denote-batch-create-note` - Create denote note with proper naming and frontmatter
274- `denote-batch-create-note-from-file` - Create note with content from file
275- `denote-batch-append-content` - Append content to existing note
276- `denote-batch-update-frontmatter` - Update note metadata (title, tags, category)
277- `denote-batch-read-metadata` - Read note metadata as JSON
278
279**Features:**
280- Automatic timestamp generation (YYYYMMDDTHHMMSS)
281- Signature support for automated notes (e.g., `==pkai`)
282- Proper denote filename format: `TIMESTAMP==SIG--title__tags.org`
283- Org-mode frontmatter generation (#+title, #+date, #+filetags, etc.)
284- JSON output for programmatic integration
285
286### Configuration
287
288TODO keywords and priorities are configured for your setup:
289
290```elisp
291(setq org-todo-keywords
292      '((sequence "STRT(s)" "NEXT(n)" "TODO(t)" "WAIT(w)" "|" "DONE(d!)" "CANX(c@/!)")))
293
294(setq org-priority-highest 1
295      org-priority-lowest 5
296      org-priority-default 4)
297```
298
299## Performance
300
301Tested on 354-item todos.org:
302- Parse: <100ms
303- Filter: <50ms
304- Updates: <100ms per item
305
306## References
307
308- [[file:~/desktop/org/notes/20251205T092927--emacs-batch-mode-for-org-automation__emacs_orgmode_automation_elisp_reference.org][Research Note]]
309- See `README.md` for full documentation
310
311## Examples
312
313**Example 1: Reading and parsing org file**
314```
315User: "What TODOs are in my project.org file?"
316→ Uses Emacs batch mode to parse org file
317→ Extracts TODO items with org-element-map
318→ Returns formatted list with priorities and tags
319→ Shows deadlines and scheduled dates
320→ Result: Complete overview of project TODOs
321```
322
323**Example 2: Updating org file programmatically**
324```
325User: "Mark all DONE items as archived"
326→ Reads org file with Emacs batch mode
327→ Finds all DONE entries
328→ Moves them to archive section
329→ Preserves timestamps and properties
330→ Saves updated file
331→ Result: Clean org file with archived history
332```
333
334**Example 3: Extracting information from org**
335```
336User: "Get all meeting notes from last month"
337→ Parses org files for date range
338→ Filters entries with :meeting: tag
339→ Extracts content and metadata
340→ Formats as summary report
341→ Result: Month's meeting notes compiled
342```