Org-supertag is a note-taking tool, an alternative to org-roam, based on org-mode but with a database for speed and query capabilities and support for inline #tags, views…and more.
org-supertag is a package that enhances the tag function of org-mode. It allows tags not only to set properties for nodes, but also to operate nodes directly, and can automatically perform certain actions based on time, providing a more flexible way of managing information.
org-supertag brings a more modern note experience to org-mode, which is reflected in various visual interfaces and more convenient interactions. Please try M-x org-supertag-view-tag, M-x org-supertag-tag-edit-fields and other commands.
org-supertag adopts a non-intrusive design, harmoniously coexisting with the original functions of org-mode, while providing more possibilities.
While adding tags to Org headlines, set multiple properties at the same time, reduce repetitive operations, and make information organization more efficient.
M-x org-supertag-tag-add-tag Add tag
M-x org-supertag-tag-set-field-and-value Set org-properites
Convert ordinary Org headlines into searchable and referable nodes, enhance the accessibility and relevance of content.
- Automatically create nodes, no need to create manually
- Establish reference relationships between nodes
- View node references in a dedicated backlink panel
Related commands:
M-x org-supertag-node-add-referenceKey bindingC-c t rM-x org-supertag-backlink-showShow backlink panel
The reference relationship of the node will be automatically recorded in the database.
If the node fails to be created automatically, you can directly run the M-x org-supertag-node-create command to convert the current headline into a node.
To avoid some situations where the node cannot be synchronized to the database, you can use M-x org-supertag-node-update to update all the information of the node to the database.
- You can directly enter #inline tags, breaking through the limitations of org-mode’s native
- You can customize the style of inline tags to distinguish them from normal body text
- Allow to complete tags by adding ‘#’ suffix, and create new tags (currently only support Company as the backend)
Related commands M-x org-supertag-inline-insert-tag Enter inline tags
Note: The input of inline tags should comply with the requirements of org-mode, only accept “numbers”, “English”, “@”, “underscore”. Do not use - as a connector.
;; Whether to hide the '#' symbol in front of the tag
(setq org-supertag-inline-style-hide-prefix t)
;; Background and foreground colors of the tag
(setq org-supertag-inline-background "#e8f0ff") ;; Light blue background
(setq org-supertag-inline-foreground "#0066cc") ;; Dark blue text
;; Border style setting - choose one of your favorite configurations:
;; 1. Simple thin border
(setq org-supertag-inline-box '(:line-width 1 :color "#b0b0b0" :style nil))
;; 2. No border (comment out the above and use this one)
;; (setq org-supertag-inline-box nil)
;; 3. Raised button effect (comment out the above and use this one)
;; (setq org-supertag-inline-box '(:line-width 1 :color "#808080" :style released-button))
;; 4. Use different vertical and horizontal line widths (comment out the above and use this one)
;; (setq org-supertag-inline-box '(:line-width (1 . 2) :color "#a0a0a0" :style nil))
;; 5. Thin border inside the text, does not increase the height of the tag (comment out the above and use this one)
;; (setq org-supertag-inline-box '(:line-width -1 :color "#b0b0b0" :style nil))
;; Font weight setting
(setq org-supertag-inline-weight 'semi-bold) ;; Optional values: 'normal, 'bold, 'semi-bold
;; Apply style update
(when (fboundp 'org-supertag-inline-style-update)
(org-supertag-inline-style-update))Related commands M-x org-supertag-query
Supports entering multiple keywords at once, uses AND logic for search, accurately locates the required content.
The search results page has been optimized for easy browsing.
To improve search speed, the content is temporarily not searched.
- Export search results to another file
- Export search results to a newly created file (can customize the location and file name)
- Insert the search results directly at the current cursor position (in the form of a reference)
Convenient for users to organize and sort search results.
By integrating multiple operations into one tag, achieve one-click completion of complex operations, improve work efficiency.
- 🚀 Tag triggers preset actions, achieving automation
The behavior system makes tags “smart”, automatically triggers preset actions when adding/deleting tags (such as changing styles, setting status, etc.).
- 🧩 Behaviors can be scheduled, combined, and with parameters
Behaviors can be scheduled, used in combination, and with parameters, making the workflow of Org-mode more automated and efficient.
- 🧱 Built-in behavior library and custom support
Built-in behavior library, users can use predefined common behaviors, and can also create custom behaviors. The modular design makes it easy to share, reuse and extend behaviors between different Org files or users.
Related commands
M-x org-supertag-behavior-attach Add behavior to the current tag
M-x org-supertag-behavior-detach Detach behavior from the current tag
Create custom behaviors, edit the ~/.emacs.d/org-supertag/org-supertag-custom-behavior.el file:
Here is an example
;; Register a behavior named "@urgent"
;; Parameter description:
;; - @urgent: The name of the behavior, used to identify and reference this behavior
;; - :trigger: Trigger condition, :on-add means trigger when adding a tag
;; - :list: List of actions to be executed, each action is a command string
;; - :style: Tag display style, including font and prefix icon settings
(org-supertag-behavior-register "@urgent" ;; Register a behavior named "@urgent"
:trigger :on-add ;; Trigger when adding a tag
:list '("@todo=TODO" ;; Set the TODO status
"@priority=A" ;; Set the priority to A
"@deadline=today") ;; Set the deadline to today
:style '(:face (:foreground "red" :weight bold) ;; Set the tag to display in red and bold
:prefix "🔥")) ;; Display a flame icon in front of the tagFor more examples, please refer to DEMO.org.
For more usage, please refer to Org‐supertag Advance Usage
- Display the title and property values of nodes (Node) at the same time, the information is clear at a glance.
- Directly modify the property values in the table, saving cumbersome steps.
- Support full keyboard operation, improve operation efficiency.
Related commands
M-x org-supertag-view-table
- In-depth exploration of the co-occurrence relationship between tags, revealing potential connections.
- Dynamically add or remove filters, adjust the view in real time.
- Real-time display of matching nodes, quickly locate the target information.
Related commands M-x org-supertag-tag-discover
- Simultaneously compare nodes under different tag combinations, intuitively analyze differences.
- Dynamically add or remove comparison columns, meet diverse needs.
- Support adding additional tags to the column, deepening the comparison dimension.
- Full keyboard support
Related commands M-x org-supertag-tag-columns
🖇️ Intelligent management of tag relationships, revealing hidden associations
Related commands M-x org-supertag-relation-manage
(defcustom org-supertag-relation-types
'((contrast . "A ⋮ B, A compare with B") ; contrast relationship
(relate . "A ~ B, A relate to B") ; general relation
(influence . "A → B, A influence B") ; influence relationship
(contain . "A ⊃ B, A contain B") ; containment (parent)
(belong . "A ⊂ B, A belong to B") ; belonging (child)
(parallel . "A ∥ B, A parallel with B") ; parallel relationship
(dependency . "A ⇒ B, A depend on B") ; dependency relationship
(prerequisite . "A ⊃ B, A prerequisite B") ; prerequisite relationship
(cause . "A ⤳ B, A cause B") ; causal relationship
(effect . "A ⤝ B, A effect B") ; effect relationship
(cooccurrence . "A ⋈ B, A co-occur with B")) ; co-occurrence relationship
"Predefined relation types.
Each relation type contains a symbol and a description text."
:type '(alist :key-type symbol :value-type string)
:group 'org-supertag-relation)
When applying two-way relationships, the corresponding relationship will be automatically set in the two tags. For example:
If there are two tags #climate_change and #glacier_melting, and you want to express the causal relationship between them.
;; Select through the relationship management interface (org-supertag-relation-manage) ;; Open the relationship management interface ;; Select the "climate_change" tag ;; Click the [Select] button to select the "glacier_melting" tag ;; Select "cause - A ⤳ B, A cause B" in the relationship type prompt ;; The system will automatically create: ;; 1. climate_change cause glacier_melting ;; 2. glacier_melting effect climate_change
;; Custom relationship types
(setq org-supertag-relation-types
'((contrast . "A ⋮ B, A compare with B")
(relate . "A ~ B, A relate to B")
(influence . "A → B, A influence B")
(contain . "A ⊃ B, A contain B")
(belong . "A ⊂ B, A belong to B")
(parallel . "A ∥ B, A parallel with B")
(dependency . "A ⇒ B, A depend on B")
(prerequisite . "A ⊃ B, A prerequisite B")
(cause . "A ⤳ B, A cause B")
(effect . "A ⤝ B, A effect B")
(cooccurrence . "A ⋈ B, A co-occur with B")
;; Add custom types
(is-part-of . "A ◐ B, A is part of B")
(leads-to . "A ⟿ B, A leads to B")))
;; Custom complementary relationship pairs
(setq org-supertag-relation-complementary-pairs
'((contain . belong)
(cause . effect)
(dependency . prerequisite)
;; Add custom complementary relationships
(is-part-of . contains-part)))
When different tags are applied to the same object, there is a “co-occurrence” relationship between these tags, which is abbreviated as “co-occurrence”.
org-supertag automatically recognizes the co-occurrence relationship between tags, helps users understand the relationship between tags, and simplifies the operation of tag relationships.
It will be displayed in the Tag Discovery panel, when you click the [+] in front, it will add one more layer of filtering:
When tags appear in parent-child nodes, org-supertag automatically establishes a special kind of co-occurrence relationship:
- The tags of the parent node have a one-way influence on the tags of the child node
- This influence is propagated from top to bottom, expressing the hierarchical containment relationship of concepts
- The strength of this influence is weaker than ordinary co-occurrence, reflecting the characteristic of indirect association
For example:
* Project Planning #project #planning
** Technical Research #research
Here, #project and #planning have a one-way influence on #research, indicating that this is a research task under project planning. This automatically recognized hierarchical relationship helps to:
- Provide more context-appropriate suggestions during tag recommendation
- Display more abundant association relationships in the tag discovery view
- Assist in building the hierarchical structure of knowledge
This feature is fully automated, and users only need to organize their document structure naturally, and the system will automatically establish these semantic associations.
Statistical analysis of the co-occurrence and mutual information of tags, real-time update of relationships when adding or deleting tags, ensuring the accuracy of the information.
Based on the context, intelligently recommend related tags, improving the convenience of tag management.
Related commands M-x org-supertag-sim-auto-tag-node
- Automatic synchronization of the position and changes of the Org headline that has been converted to a node, reducing manual operations.
- Automatic synchronization will check the situation of adding, modifying, moving, and deleting nodes, automatically maintain the database.
- Provide a manual command to synchronize all nodes, ensure the consistency of the data.
If some nodes need to be synchronized, but cannot be synchronized automatically, you can directly run the M-x org-supertag-sync-force-all command to synchronize all node information to the database.
In some functions of org-supertag, AI/NLP is used as the backend, providing more dimensions of tag performance and reducing the pressure of operations. Since AI/NLP is only used as the backend, users only need to call the corresponding command, and will not feel the existence of AI/NLP in daily use.
In org-supertag, artificial intelligence is seen as a supporting function, not a direct front-end function, to prevent people from getting caught in the whirlpool of dialogue (while also avoiding redundant implementation, because Emacs already has a large number of assistant AI tools, such as gptel, chatgpt-shell, Ellama, Ollama-buddy......
Currently, the following commands use AI/NLP support:
M-x org-supertag-sim-auto-tag-node This command will analyze all the content (title and content) in the current Node, and automatically provide several tag suggestions.
ATTENTION: AI function requires installation of dependencies, the installation method has been described in the “Basic Installation” section.
org-supertag’s artificial intelligence function architecture:
- The backend is Ollama
- The communication framework is epc
- The large model is hf.co/unsloth/gemma-3-4b-it-GGUF:latest
The tag suggestions of org-supertag-sim-auto-tag-node are provided by tag_generator.py, if you are not satisfied with the tag suggestion effect, you can directly modify the Prompt in the file.
(use-package org-supertag
:straight (:host github :repo "yibie/org-supertag")
:after org
:config
(org-supertag-setup))
(setq org-supertag-sync-directories '("~/Documents/notes/")) ;; Configure sync foldersorg-supertag requires some Python dependencies, including `torch`, `sentence-transformers`, `epc` and `ollama`:
- Use the automated script to install dependencies
cd /path/to/org-supertag sh ./run_simtag_epc_venv.sh
Normal tags are suitable for classification. For example: :project:, :issue:, etc.
Inline tags are suitable for directly using semantics. For example: #org_supertag.
For example:
* org-supertag :#project: #org_supertag is a #emacs package based on #org_mode.
In this way, your document will be very readable and provide rich associations. This makes it very efficient and rewarding to explore and retrieve your notes or documents during use.
Node represents the org-headline that has been converted by org-supertag, indicating that it has been recorded by org-supertag and can be operated by it.
Conceptually, Node is equivalent to a note block in general note-taking software. It includes: an org-headline with an ID + the content contained below the org-headline.
When org-supertag operates on a Node, it actually operates on the entire note block. For example: M-x org-supertag-node-delete, will directly delete the entire Node, clean up the ID, Node and Node reference relationships recorded in the database, the Link relationship of the Tag, etc., clean up the related Field Value.
Field is roughly equivalent to org-properties, and like Node, it represents the org-properites converted and recorded by org-supertag.
This conceptual distinction is to let users know clearly the state of the notes, whether they have been recorded in the database.
When a tag, and another tag, are applied to the same Node, there is a relationship between them, called “co-occurrence”.
The “co-occurrence” relationship is the most basic relationship among all tag relationships. But what is its use?
- When you are in the “tag discovery view”, you can filter layer by layer through co-occurrence tags
- When you are managing “tag relationships”, you can quickly find tags that have relationships behind them through “co-occurrence relationships”
- ......
I think “co-occurrence” is the most wonderful phenomenon in the world. This allows us to automatically obtain meaningful connections when adding tags.
For details, see CHANGELOG
- 2025-04-05 3.0.0 release
- feat AI backend for tag auto suggestion
- feat Bidirectional tag relation management
- feat Table View
- refactor sync-mechanism
- 2025-01-13 2.0.0 release
- Added behavior scheduling system
- Added behavior template variables
- Added automatic synchronization system
- And many other improvements
- 2024-12-31 1.0.0 release
- feat behavior-system: Complete implementation of behavior system, forming an automatic workflow
- Three-layer behavior architecture (basic/derived/combined)
- Complete trigger system
- Rich behavior library functions
- Style system support
- docs: Provide interactive demo document DEMO.org
- refactor: Core refactoring
- Optimize data structure
- Improve error handling
- Improve performance
- feat behavior-system: Complete implementation of behavior system, forming an automatic workflow
- 2024-12-20 0.0.2 release
- fix org-supertag-remove: Fixed the problem that removing tags does not take effect
- fix org-supertag-tag-add-tag: Fixed the problem that duplicate tags can be added to org-headline when adding tags
- feat org-supertag-tag-edit-preset: Edit preset tags
- feat org-supertag-query-in-buffer: Query in the current buffer
- feat org-supertag-query-in-files: Query in specified files, can specify multiple files
- 2024-12-19 0.0.1 release
- ✅Provide a wider range of queries, such as queries for a single file or multiple files
- ✅Preliminary implementation of a command system, let tags automatically trigger commands, such as when a node is tagged with a tag named Task, it will automatically be set to TODO, and automatically set the priority to A, and automatically change the background color of the node to yellow
- ✅Implement a task scheduling system, let multiple nodes combine to complete a series of tasks, such as automatically set the daily review to 9 PM, and automatically insert the review results into the review node (experimental feature, may not be implemented)
- ✅Combine with AI, different tags are associated with different Prompts, such as when a node is marked as “task”, it automatically triggers an AI command to make the node generate a task list
- ✅Like Tana, provide more views (experimental feature, may not be implemented)
org-supertag is deeply influenced by Tana, especially its core concept of “treating nodes as the operation objects of tags”, which brings a lot of inspiration.
org-supertag is also deeply influenced by ekg and org-node:
- ekg is the first note-taking tool in my eyes that is centered on tags. I once used it to record many days of diaries
- org-node deeply influenced the basic working mechanism of org-supertag with its parsing of org-mode files and the application of hash tables
Thank simplex5d to genearte a good summary to org-supertag, I put it in the TL;DR section at the beginning of README.
Contributions are welcome! Please see Contribution Guide.