Skip to content

About

Obsidian Timestamp Utility: Enhance your Obsidian experience with time-based functionalities.

Resources

Stars

2 stars

Watchers

1 watching

Forks

Latest commit

 

History

53 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Timestamp Plugin for Obsidian

What this project is (helicopter view). This repository contains a complete Obsidian community plugin plus the machinery that builds and maintains it. There are two halves:

  1. The plugin (what you run). A TypeScript Obsidian plugin (src/main.ts + src/*.ts, compiled by rollup into dist/main.js) that adds nine timestamp / date-range / UUID / Base64 / reminder commands to Obsidian. This is the product a user installs and the detail listed in the Commands and Usage sections below.
  2. The agentic pipeline (how it is built). A Python pipeline (agents/agentics/) that reads an OpenSpec change (proposal + tasks + specs) and deterministically generates the plugin's TypeScript code and jest tests — it never hands the LLM the final file. Generation is gated by a self-correcting OpenSpec loop / harness that re-runs until the build and tests are green and every spec requirement is met, then archives the change. The plugin you install is the output of that loop.

In short: the OpenSpec loop drives the Python pipeline, which generates the TypeScript plugin. The authoritative map of the whole system — plugin surface, pipeline, and loop — lives in docs/AGENTIC_ARCHITECTURE.md; the operational "how the loop runs and verifies" reference is docs/openspec-engineering-loop-harness.md.

This plugin enhances your Obsidian experience by adding nine convenient commands for working with timestamps, date ranges, UUIDs, Base64 encoding, and task processing to support the Zettelkasten notes and efficient planning:

Commands

The plugin registers nine commands. Each is described below and demonstrated in Usage; a machine-readable list of their ids is in src/main.ts and manifest.json.

  • Insert Current Timestamp (YYYYMMDDHHMMSS): Inserts a timestamp at the cursor position in the format YYYYMMDDHHMMSS (e.g., 20250221134527 for February 21, 2025, 1:45:27 PM).
  • Rename Current File with Timestamp Prefix (YYYYMMDDHHMMSS): Renames the active file by adding a timestamp prefix in the format YYYYMMDDHHMMSS_filename (e.g., 20250221134527_notes.md).
  • Rename Current File with Timestamp as Prefix and First Heading Title as Filename: Renames the active file using a timestamp prefix and the first heading title from the file content in the format YYYYMMDDHHMMSS_title (e.g., 20250221134527_my_awesome_title.md). If no heading is found, it uses "untitled" (e.g., 20250221134527_untitled.md).
  • Rename Current File with the First Heading Title as Filename: Renames the active file using the first level 1 heading (e.g., # My Awesome Title) as the filename (e.g., my_awesome_title.md). If no heading is found, it uses "untitled" (e.g., untitled.md).
  • Insert Dates in Range (YYYY-MM-DD, one per line): Opens a modal where you can input a start and end date in YYYYMMDD format. It then inserts a list of dates from the start to the end date (inclusive) in YYYY-MM-DD format, each on a new line.
  • Convert Reminders to Date-Time-Blocked Tasks: Processes reminders in notes in a selected source folder and converts them into time-blocked tasks organized by date in a selected output folder. Reminders in the format - [ ] Task description (@YYYY-MM-DD HH:MM) are transformed into tasks like - [ ] HH:MM - HH:MM Task description and grouped into daily files to be synced with ICAL services (like 2025-01-01.md).
  • Insert UUID v7 (timestamp-based): Inserts a UUID v7 at the cursor position. UUID v7 embeds a millisecond timestamp in its first 48 bits, so generated IDs are time-sortable (e.g., 01971a2b-3c4d-7e5f-8a9b-0c1d2e3f4a5b).
  • Encode Base64 Message: Opens a modal where you type a message and copy its Base64-encoded form — useful for embedding binary-safe payloads in notes.
  • Decode Base64 Message: Opens a modal where you paste Base64 text and view the decoded message.

Documentation

This repository is documentation-driven (OpenSpec workflow). The key references are:

How a change is built and delivered

Every feature/fix starts as an OpenSpec change and is built, verified, and delivered through a per-change git worktree — the parent working tree is never touched until the work is green.

  1. Scaffold the change. make openspec-new NAME=<name> creates openspec/changes/<name>/ (via the openspec CLI — never hand-authored) with proposal.md, specs/<cap>/spec.md, and tasks.md.
  2. Work in an isolated wt/<name> sandbox. The agent runs make openspec-flow NAME=<name>, which spins up a throwaway local worktree worktrees/<name> on branch wt/<name>. All generation, the loop gate (make loop-harness — collect → ts-floor → unit → unit-real → e2e → integration → build-app → test-app → secret-scan → docs-sync), and openspec archive happen inside that worktree. The parent branch stays untouched.
  3. Auto-deliver the PR on completion (B27). As soon as the change is complete — every tasks.md checkbox ticked, the loop gate green, and the pre-commit hook passing — the flow automatically promotes wt/<name> → feat/<name>, pushes it, and opens the PR. No second "make the PR" prompt: green-lighting a change is the delivery authorization. (--no-push opts out and keeps the work in the local sandbox.)
  4. Parallel by design. Each change uses a unique worktree (worktrees/<name>), a unique branch (wt/<name> during work, feat/<name> on delivery), and a unique compose project name (COMPOSE_PROJECT_NAME=otu-<name>), so many changes deliver concurrently to distinct PR branches with no collision.

For the full machinery (the deterministic merge floor, self-correct loop, and the B1–B27 durable behaviours), see docs/openspec-engineering-loop-harness.md.

Installation

You can install the plugin either by downloading a pre-built release or by building it from source. Most users should use the From Release method, which does not require any additional tools. Developers who want to modify or contribute to the plugin can use the From Source method, which requires a container runtime (Docker or nerdctl), Make, and Git.

From Release

  1. Download the latest release from [link to releases] (e.g., a ZIP file).
  2. Extract the downloaded archive to obtain the plugin files (e.g., main.js, manifest.json).
  3. In your Obsidian vault, navigate to the .obsidian/plugins directory. If it doesn’t exist, create it.
  4. Create a new folder named timestamp-plugin (this name should match the plugin’s ID in manifest.json).
  5. Copy the extracted plugin files into this new folder.
  6. Restart Obsidian.
  7. Go to Settings > Community plugins, find "Timestamp Plugin", and toggle it on to enable it.

From Source

To build the plugin from source, you will need:

  • A container runtime: Either Docker or nerdctl. The build process will automatically use whichever is available.
  • Make: Required for building and running the Makefile to manage the plugin’s build process.
  • A Git repository initialized in the project directory: Required for automatic versioning and tagging.

Follow these steps:

  1. Clone this repository: Use the command git clone https://github.com/andyholst/obsidian-timestamp-utility.git to clone the repository to your local machine, then navigate to the project directory with cd obsidian-timestamp-utility.
  2. Build the plugin: Run make build-app to compile the plugin. This will generate the plugin files in the dist folder.
  3. Install the plugin: Follow steps 3-7 from the "From Release" section above, using the files from the dist folder.

Usage

Insert Current Timestamp

To insert a timestamp at the cursor position:

  1. Open the command palette (Ctrl+P or Cmd+P).
  2. Search for "Insert Current Timestamp".
  3. Press Enter to insert the timestamp at the cursor.

Rename Current File with Timestamp Prefix

To rename the active file by adding a timestamp prefix:

  1. Open the command palette (Ctrl+P or Cmd+P).
  2. Search for "Rename Current File with Timestamp Prefix".
  3. Press Enter to rename the file.

Rename Current File with Timestamp as Prefix and First Heading Title as Filename

To rename the active file using a timestamp prefix and the first heading title:

  1. Open the command palette (Ctrl+P or Cmd+P).
  2. Search for "Rename Current File with Timestamp as Prefix and First Heading Title as Filename".
  3. Press Enter to rename the file based on the first heading (e.g., # My Awesome Title) or "untitled" if no heading exists.

Rename Current File with the First Heading Title as Filename

To rename the active file using the first heading title:

  1. Open the command palette (Ctrl+P or Cmd+P).
  2. Search for "Rename Current File with the First Heading Title as Filename".
  3. Press Enter to rename the file based on the first level 1 heading (e.g., # My Awesome Title) or "untitled" if no heading exists.

Insert Dates in Range

To insert a list of dates in YYYY-MM-DD format between a start and end date:

  1. Open the command palette (Ctrl+P or Cmd+P).
  2. Search for "Insert Dates in Range".
  3. Press Enter to open a modal.
  4. In the modal, enter the start date in YYYYMMDD format (e.g., 20250101 for January 1, 2025).
  5. Enter the end date in YYYYMMDD format (e.g., 20250105 for January 5, 2025).
  6. Click "Insert Dates" to insert the list of dates, each on a new line, at the cursor position. The output will be a list of dates in YYYY-MM-DD format from the start date to the end date, inclusive.

Note:

  • The start date must be before or equal to the end date.
  • Both dates must be valid and entered in YYYYMMDD format (e.g., 20250230 is invalid and will trigger an error message).
  • If the input is invalid, a notice will appear in Obsidian (e.g., "Invalid start date. Please use YYYYMMDD and ensure it's a valid date.").

Convert Reminders to Date-Time-Blocked Tasks

To process reminder files and convert them into organized time-blocked tasks:

  1. Open the command palette (Ctrl+P or Cmd+P).
  2. Search for "Convert Reminders to Date Time-Blocked Tasks".
  3. Press Enter to open a folder selection modal.
  4. Select the source folder containing your reminder files using the fuzzy search interface.
  5. Select the output folder where processed tasks will be saved.
  6. The plugin will scan all Markdown files in the source folder (recursively), extract reminders in the format - [ ] Task description (@YYYY-MM-DD HH:MM), convert them to time-blocked tasks like - [ ] HH:MM - HH:MM Task description, and organize them into daily files (e.g., 2025-01-01.md) in the output folder.

Note:

  • The source and output folders must be different.
  • Existing checked tasks (- [x]) in output files are preserved.
  • Unchecked tasks are updated if they match current reminders.
  • New tasks are added to existing files or new files are created as needed.

Insert UUID v7

To insert a time-sortable UUID v7 at the cursor position:

  1. Open the command palette (Ctrl+P or Cmd+P).
  2. Search for "Insert UUID v7 (timestamp-based)".
  3. Press Enter to insert the UUID v7 at the cursor.

Note: the generated UUID v7 embeds a millisecond timestamp in its first 48 bits, so IDs are monotonically sortable by creation time.

Encode Base64 Message

To Base64-encode a message:

  1. Open the command palette (Ctrl+P or Cmd+P).
  2. Search for "Encode Base64 Message".
  3. Press Enter to open the encode modal.
  4. Type or paste your message into the text area.
  5. Click "Encode" — the Base64 result appears in the modal, ready to copy.

Decode Base64 Message

To Base64-decode a message:

  1. Open the command palette (Ctrl+P or Cmd+P).
  2. Search for "Decode Base64 Message".
  3. Press Enter to open the decode modal.
  4. Paste the Base64 text into the text area.
  5. Click "Decode" — the decoded message appears in the modal.

Running the Agentic Pipeline

The agentic pipeline is an AI-powered tool that turns an OpenSpec change (or a GitHub issue) into TypeScript code and tests for the plugin, using LangChain and LangGraph. It reads the change's proposal, tasks, and specs, generates the implementation and jest tests, then merges them into the plugin source via a deterministic floor and verifies the result with make build-app / make test-app.

Prerequisites

Before running the ticket interpreter agent, ensure you have the following:

  • A container runtime: Either Docker or nerdctl.
  • Make: Required to execute the Makefile commands.
  • Environment Variables:
    • GITHUB_TOKEN: A GitHub personal access token with repository access. Obtain one from GitHub Settings.
    • OLLAMA_HOST: The URL of your Ollama LLM service (default: http://localhost:11434).
    • OLLAMA_REASONING_MODEL: The LLM model for reasoning tasks (default: sorc/qwen3.5-claude-4.6-opus:9b).
    • OLLAMA_CODE_MODEL: The LLM model for code generation (default: sorc/qwen3.5-claude-4.6-opus:9b).

Set these environment variables in your terminal: export GITHUB_TOKEN=your_token_here export OLLAMA_HOST=http://localhost:11434 export OLLAMA_REASONING_MODEL=sorc/qwen3.5-claude-4.6-opus:9b export OLLAMA_CODE_MODEL=sorc/qwen3.5-claude-4.6-opus:9b

Steps to Run the Agent

  1. Run the Agent:

    • Execute the agentic pipeline against a LOCAL OpenSpec change (no GitHub fetch, no MCP) using the following command: make run-agentics CHANGE=
    • Replace with the name of an existing change under openspec/changes/ (e.g. uuid-modal-agentic-generation). The pipeline reads the change's proposal.md / tasks.md / specs locally and generates + verifies TypeScript and tests.
  2. View the Output:

    • The agent processes the change and writes the generated code/tests into the plugin source (src/main.ts, src/tests/main.test.ts), merging via the deterministic floor.
    • Check the console for immediate feedback.

Example: To run the pipeline on the local change uuid-modal-agentic-generation, run: make run-agentics CHANGE=uuid-modal-agentic-generation

Running the Tests

The agentic pipeline includes unit and integration tests to verify its functionality. These tests are defined under agents/agentics/tests/unit/ (unit tests) and agents/agentics/tests/integration/ (integration tests).

Prerequisites

  • A container runtime: Either Docker or nerdctl.
  • Make: Required to execute the Makefile commands.
  • Environment Variables: Same as for running the agent (GITHUB_TOKEN, OLLAMA_HOST, OLLAMA_REASONING_MODEL, OLLAMA_CODE_MODEL), plus:

Set the additional variable: export TEST_ISSUE_URL=https://github.com/andyholst/obsidian-timestamp-utility

Running Unit Tests

Unit tests cover individual components, such as URL validation, issue fetching, and LLM response processing, using mocked data.

  • Run the unit tests with: make test-agents-unit

Running Integration Tests

Integration tests validate the full workflow with real GitHub API calls and LLM interactions, testing scenarios like well-structured tickets, sloppy tickets, empty tickets, and invalid inputs.

  • Run the integration tests with: make test-agents-integration

Running All Tests

To execute both unit and integration tests together: make test-agents

Notes:

  • Ensure the TEST_ISSUE_URL points to a valid repository with accessible issues (e.g., issues #20, #22, #23) for integration tests to pass.
  • Integration tests require a live Ollama LLM service and a valid GITHUB_TOKEN. If these are unavailable, tests may fail with appropriate error messages (e.g., GithubException or ValueError).

Development

For those interested in contributing:

  1. Clone the Repository: git clone https://github.com/andyholst/obsidian-timestamp-utility.git
  2. Install Dependencies:
    • Ensure you have a container runtime (either Docker or nerdctl) and Make installed.
  3. Build and Test:
    • Use the Makefile commands to build, test, and run the plugin and agent as described above.
  4. Contribute:
    • Follow standard Git workflows to submit pull requests with your changes.

Release / Changelog

Current plugin version: 0.4.16 (tag v0.4.16).

The changelog is SECTIONED by commit type (git_chglog, chglog/config.yml):

  • 🚀 New Features (feat)
  • 🐞 Bug Fixes (fix)
  • ⚡ Improvements (perf)
  • 🔧 Improvements (refactor)
  • 📝 Documentation (docs)
  • 🚠️ Maintenance (chore)

The full, per-version, categorized history lives in CHANGELOG.md. The squashed release commit is written with a Conventional type(scope): prefix so it lands in the correct section and decides the version bump (feat/fix/perf -> minor, refactor/docs/chore -> patch).

About

Obsidian Timestamp Utility: Enhance your Obsidian experience with time-based functionalities.

Resources

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages