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:
- The plugin (what you run). A TypeScript Obsidian plugin (
src/main.ts+src/*.ts, compiled by rollup intodist/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.- 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 isdocs/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:
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.,20250221134527for 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
YYYYMMDDformat. It then inserts a list of dates from the start to the end date (inclusive) inYYYY-MM-DDformat, 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 descriptionand grouped into daily files to be synced with ICAL services (like2025-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.
This repository is documentation-driven (OpenSpec workflow). The key references are:
docs/AGENTIC_ARCHITECTURE.md— the canonical architecture of the Python agentic pipeline (module map, the three-phase workflow, and the deterministic merge floor that writessrc/main.ts).docs/architecture/— agentic design docs: dependency management, LLM code validation, test suite guide, and the integration test plan.docs/openspec-engineering-loop-harness.md— the OpenSpec harness + loop engineering reference (durable behaviours B1–B27).AGENTS.md— the agent execution manual for this OpenSpec-driven repo (how changes are proposed, generated, verified, and archived).docs/openspec-loop-harness-guide.md— a short redirect note that now points to the harness reference above.
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.
- Scaffold the change.
make openspec-new NAME=<name>createsopenspec/changes/<name>/(via theopenspecCLI — never hand-authored) withproposal.md,specs/<cap>/spec.md, andtasks.md. - Work in an isolated
wt/<name>sandbox. The agent runsmake openspec-flow NAME=<name>, which spins up a throwaway local worktreeworktrees/<name>on branchwt/<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), andopenspec archivehappen inside that worktree. The parent branch stays untouched. - Auto-deliver the PR on completion (B27). As soon as the change is complete — every
tasks.mdcheckbox ticked, the loop gate green, and the pre-commit hook passing — the flow automatically promoteswt/<name>→feat/<name>, pushes it, and opens the PR. No second "make the PR" prompt: green-lighting a change is the delivery authorization. (--no-pushopts out and keeps the work in the local sandbox.) - 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.
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.
- Download the latest release from [link to releases] (e.g., a ZIP file).
- Extract the downloaded archive to obtain the plugin files (e.g.,
main.js,manifest.json). - In your Obsidian vault, navigate to the
.obsidian/pluginsdirectory. If it doesn’t exist, create it. - Create a new folder named
timestamp-plugin(this name should match the plugin’s ID inmanifest.json). - Copy the extracted plugin files into this new folder.
- Restart Obsidian.
- Go to Settings > Community plugins, find "Timestamp Plugin", and toggle it on to enable it.
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:
- Clone this repository: Use the command
git clone https://github.com/andyholst/obsidian-timestamp-utility.gitto clone the repository to your local machine, then navigate to the project directory withcd obsidian-timestamp-utility. - Build the plugin: Run
make build-appto compile the plugin. This will generate the plugin files in thedistfolder. - Install the plugin: Follow steps 3-7 from the "From Release" section above,
using the files from the
distfolder.
To insert a timestamp at the cursor position:
- Open the command palette (Ctrl+P or Cmd+P).
- Search for "Insert Current Timestamp".
- Press Enter to insert the timestamp at the cursor.
To rename the active file by adding a timestamp prefix:
- Open the command palette (Ctrl+P or Cmd+P).
- Search for "Rename Current File with Timestamp Prefix".
- Press Enter to rename the file.
To rename the active file using a timestamp prefix and the first heading title:
- Open the command palette (Ctrl+P or Cmd+P).
- Search for "Rename Current File with Timestamp as Prefix and First Heading Title as Filename".
- Press Enter to rename the file based on the first heading (e.g.,
# My Awesome Title) or "untitled" if no heading exists.
To rename the active file using the first heading title:
- Open the command palette (Ctrl+P or Cmd+P).
- Search for "Rename Current File with the First Heading Title as Filename".
- Press Enter to rename the file based on the first level 1 heading (e.g.,
# My Awesome Title) or "untitled" if no heading exists.
To insert a list of dates in YYYY-MM-DD format between a start and end date:
- Open the command palette (Ctrl+P or Cmd+P).
- Search for "Insert Dates in Range".
- Press Enter to open a modal.
- In the modal, enter the start date in
YYYYMMDDformat (e.g.,20250101for January 1, 2025). - Enter the end date in
YYYYMMDDformat (e.g.,20250105for January 5, 2025). - 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-DDformat 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
YYYYMMDDformat (e.g.,20250230is 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.").
To process reminder files and convert them into organized time-blocked tasks:
- Open the command palette (Ctrl+P or Cmd+P).
- Search for "Convert Reminders to Date Time-Blocked Tasks".
- Press Enter to open a folder selection modal.
- Select the source folder containing your reminder files using the fuzzy search interface.
- Select the output folder where processed tasks will be saved.
- 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.
To insert a time-sortable UUID v7 at the cursor position:
- Open the command palette (Ctrl+P or Cmd+P).
- Search for "Insert UUID v7 (timestamp-based)".
- 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.
To Base64-encode a message:
- Open the command palette (Ctrl+P or Cmd+P).
- Search for "Encode Base64 Message".
- Press Enter to open the encode modal.
- Type or paste your message into the text area.
- Click "Encode" — the Base64 result appears in the modal, ready to copy.
To Base64-decode a message:
- Open the command palette (Ctrl+P or Cmd+P).
- Search for "Decode Base64 Message".
- Press Enter to open the decode modal.
- Paste the Base64 text into the text area.
- Click "Decode" — the decoded message appears in the modal.
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.
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
-
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.
-
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
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).
- 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:
- TEST_ISSUE_URL: A base GitHub repository URL (e.g., https://github.com/andyholst/obsidian-timestamp-utility) used by integration tests.
Set the additional variable: export TEST_ISSUE_URL=https://github.com/andyholst/obsidian-timestamp-utility
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
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
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).
For those interested in contributing:
- Clone the Repository: git clone https://github.com/andyholst/obsidian-timestamp-utility.git
- Install Dependencies:
- Ensure you have a container runtime (either Docker or nerdctl) and Make installed.
- Build and Test:
- Use the Makefile commands to build, test, and run the plugin and agent as described above.
- Contribute:
- Follow standard Git workflows to submit pull requests with your changes.
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).