Implement #+BEGIN: clocktable dynamic block

[Sandyeee0094]

Does this feature exist in Emacs orgmode core?

Yes, Here’s the official Emacs Org Mode documentation for the clocktable dynamic block.

Orgmode link (https://orgmode.org/manual/The-clock-table.html)

This page explains:

• How to insert and update #+BEGIN: clocktable … #+END: blocks
• How clock tables automatically summarize clocked time by headline
• How to set options like :scope file, :maxlevel, :block, etc.

clocktable is a core feature of Emacs Org, not an add-on. It’s the bridge between raw CLOCK:LOGS and derived, in-file analytics. Right now, nvim-orgmode already has all the primitives components required for this.

• CLOCK entries with LOGBOOK support
• Accurate duration computation
• Agenda clock reports via <space>oaR
• Formatting via gqgq
• Scope resolution via org_agenda_files

What’s missing is the Glue the dynamic block evaluator that lets a file contain a projection of its own data.

In Emacs Org:

#+BEGIN: clocktable :scope file
#+END:

generates an in-file table by:

1. Scanning CLOCK entries in the requested scope (file, subtree, etc.)
2. Aggregating by headline
3. Computing totals
4. Rendering a table in place

raw facts → derived views in the same document by this clocktable feature.

In nvim-orgmode, the same data already exists and is already aggregated in Agenda. The engine that computes clock reports exists. The missing piece is exposing that engine as a dynamic block renderer inside files.

Proposed minimal MVP:

1. Recognize blocks of the form:

#+BEGIN: clocktable :scope file
#+END:

2. Add a command (e.g. :Org CreateDynamicClockTable or :Org UpdateDynamicClockTable ) that parses the block.
3. Calls the existing clock-report logic.
4. Replaces the block body with a rendered table

Even a first version that supports only:

1. :scope file
2. `:scope subtree'
   would unlock a major part of Org’s workflow.

This is not a “nice-to-have”.
It is one of Org’s core features, and nvim-orgmode already has 90% of the machinery. Implementing this would complete the loop between logging and reflection inside the same document.

[celsobenedetti]

To clarify, is it virtual text rendered inside the table, without actually modifying the buffer text content?

[Sandyeee0094]

To clarify, is it virtual text rendered inside the table, without actually modifying the buffer text content?

In Emacs Org, clocktable is implemented as a dynamic block. Running the update command generates the table and inserts it as actual buffer text between #+BEGIN: and #+END:. It is not virtual text or an overlay; the table becomes part of the document and is replaced when the block is updated.

Example:

1. You write this source block in the document.

#+BEGIN: clocktable :scope file
#+END:

2. Run a command or keybinding or auto (which is not native in emacs org), example command names.
   :Org CreateDynamicClockTable or :Org UpdateDynamicClockTable

3. You get a view on total time spent based on each heading respective to the declared scope.

#+BEGIN: clocktable :scope file
| Headline        | Time |
|-----------------+------|
| * Research      | 2:30 |
| * Implementation| 1:15 |
|-----------------+------|
| Total time      | 3:45 |
#+END: