I'm aware of C-c C-x C-i (org-clock-in) which starts the clock on the current heading.

Question: Is there a way to programmatically target a specific heading with this command? That is, if I have

* Task A
** Task B

Is there a way for me to execute a command which starts the clock for Task B no matter where I am?

EDIT: I have since discovered helm-org-agenda-files-headings, when -- when called -- allows you to search and jump to any heading across your agenda files. This is nearly perfect except you can't programmatically go to the first match with something like (helm-org-agenda-files-headings "Task A/Task B") You can only (helm-org-agenda-files-headings) with no arguments.

1 Answer 1


Org does seem to lack programmatic interfaces for many aspects like this. I would recommend using heading ID's for the application you describe as it virtually eliminates any ambiguity in finding your desired heading. Be sure your desired heading has an ID (you can create it by calling org-id-get-create with your point on the heading) like the following:

* Task A
:ID:       22cba7a6-137d-4f06-8547-47a8bf1eb19e
** Task B
:ID:       65d813d9-e513-482f-bb65-6430d1027666

You can then programmatically start the clock using a function like the following:

(defun my/start-heading-clock (id file)
  "Start clock programmatically for heading with ID in FILE."
  (require 'org-id)
  (if-let (marker (org-id-find-id-in-file id file t))
          (set-buffer (marker-buffer marker))
          (goto-char (marker-position marker))
    (warn "Clock not started (Could not find ID '%s' in file '%s')" id file)))

(my/start-heading-clock "65d813d9-e513-482f-bb65-6430d1027666" "~/your-task-file.org")

Note that there are other ways of locating the heading. To find a heading using the content of the heading itself you could use:

(find-file "your-task-file.org")
(org-find-exact-headline-in-buffer "Task B" (current-buffer))

(FWIW there is also org-find-exact-heading-in-directory)

I would recommend something like org-id-find as org can keep track of the locations of ID's in all agenda files (with org-id-track-globally). Using that, you only need to specify the heading ID:

(org-id-find "65d813d9-e513-482f-bb65-6430d1027666" t)

The only downside to using this strategy is that org can take a long time updating its ID locations index. I hope this helps!

  • Instead of searching a specific file, is there a way to make it default to all files in current agenda list?
    – George
    Nov 8, 2017 at 17:16
  • @George Yup. You should be able to just replace the (org-id-find-id-in-file id file t) instruction with (org-id-find id t).
    – ebpa
    Nov 8, 2017 at 17:18

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.