gerodp/hermes-productivity-skills / notes/obsidian-notes
obsidian-notes
VerifiedRead and write notes in an Obsidian vault — list notes (all or modified in a window), show a note, and save the current chat as a note.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.4 KB |
| scripts/obsidian_notes.py | script | 24.3 KB |
| scripts/test_obsidian_notes.py | script | 11.7 KB |
scripts/obsidian_notes.py
View on GitHub#!/usr/bin/env python3
"""obsidian-notes — read and write notes in an Obsidian vault.
An Obsidian vault is just a folder of Markdown (``.md``) files. This tool reads
that folder and answers four things, plus a config check:
check Verify the vault loads and summarise what's in it.
list List notes — all of them, or only those modified in a time window.
show Print a single note's contents.
save Write a new note into the vault (e.g. save the current chat).
The vault location is read from an environment variable (Hermes injects this
from ~/.hermes/.env into the sandbox), or passed with ``--vault``:
OBSIDIAN_VAULT absolute path to the Obsidian vault folder
All time windows are computed in **local time** with **Monday-start** weeks, the
same vocabulary as the other Hermes report skills. ``list`` filters by each
file's **modified** time by default (``--by created`` switches to creation
time). Hidden folders (``.obsidian``, ``.trash``, ``.git``, anything starting
with a dot) are skipped.
Python standard library only — no third-party dependencies, so it runs fast and
deterministically in the Hermes terminal sandbox.
"""
from __future__ import annotations
import argparse
import json
import os
import re
import sys
import tempfile
from datetime import date, datetime, timedelta
ENV_VAULT = "OBSIDIAN_VAULT"
# Folders that are never notes — Obsidian internals, trash, VCS, and any
# dot-folder. Matched on the directory's base name during the walk.
SKIP_DIRS = {".obsidian", ".trash", ".git", ".stversions", ".smart-env"}
# Characters that are illegal in filenames on common filesystems (Windows is
# the strict one); we strip them when turning a title into a file name.
ILLEGAL_FILENAME_RE = re.compile(r'[\\/:*?"<>|\x00-\x1f]')
# Control characters (except newline/tab) stripped from text-mode output — a
# synced/shared vault can carry note content or filenames with terminal escape
# sequences that would spoof or hide lines. JSON output is safe as-is (escaped).
CONTROL_CHARS_RE = re.compile(r"[\x00-\x08\x0b-\x1f\x7f]")
def sanitize_text(s):
return CONTROL_CHARS_RE.sub("", s)
class ObsidianError(Exception):
"""User-facing error — message is safe to print (never contains secrets)."""
# --------------------------------------------------------------------------- #
# Vault discovery / scanning
# --------------------------------------------------------------------------- #
def resolve_vault(path):
if not path:
raise ObsidianError(
f"no vault configured — set {ENV_VAULT} in ~/.hermes/.env "
"(see SKILL.md) or pass --vault PATH."
)
path = os.path.expanduser(path)
if not os.path.isdir(path):
raise ObsidianError(f"vault folder not found: {path}")
return os.path.realpath(path)
def _created_ts(st):
"""Best-effort creation time: birthtime where the OS exposes it (macOS),
else the inode-change time (``st_ctime``) as a fallback (Linux)."""
bt = getattr(st, "st_birthtime", None)
if bt:
return bt
return st.st_ctime
def _local_date(ts):
return datetime.fromtimestamp(ts).date()
def scan_notes(vault):
"""Return a list of note dicts for every ``.md`` file under the vault.
Each dict: rel (path relative to vault), path (absolute), name (basename
without extension), mtime/btime (epoch seconds), size (bytes), and the
derived ``modified``/``created`` local-date ISO strings.
"""
notes = []
for root, dirs, files in os.walk(vault):
# Prune hidden / internal folders in place so os.walk skips them.
dirs[:] = [d for d in dirs if d not in SKIP_DIRS and not d.startswith(".")]
for fn in files:
if not fn.lower().endswith(".md"):
continue
ap = os.path.join(root, fn)
try:
st = os.stat(ap)
except OSError:
continue
btime = _created_ts(st)
notes.append({
"rel": os.path.relpath(ap, vault),
"path": ap,
"name": fn[:-3],
"mtime": st.st_mtime,
"btime": btime,
"size": st.st_size,
"modified": _local_date(st.st_mtime).isoformat(),
"created": _local_date(btime).isoformat(),
})
return notes
def sort_notes(notes, sort="modified"):
if sort == "name":
return sorted(notes, key=lambda n: n["rel"].lower())
if sort == "created":
return sorted(notes, key=lambda n: n["btime"], reverse=True)
return sorted(notes, key=lambda n: n["mtime"], reverse=True)
# --------------------------------------------------------------------------- #
# Date windows (local time, Monday-start weeks) — shared vocabulary with the
# other Hermes report skills.
# --------------------------------------------------------------------------- #
PERIODS = ("today", "this-week", "last-week", "this-month",
"last-month", "this-year", "last-year")
_CURRENT = {"today", "this-week", "this-month", "this-year"}
def _monday(d):
return d - timedelta(days=d.weekday())
def _first_of_month(d):
return d.replace(day=1)
def _last_of_month(d):
nxt = (d.replace(day=28) + timedelta(days=4)).replace(day=1)
return nxt - timedelta(days=1)
def _parse_date(s):
try:
return datetime.strptime(s, "%Y-%m-%d").date()
except ValueError:
raise ObsidianError(f"invalid date (use YYYY-MM-DD): {s}")
def compute_range(today, *, period=None, days=None, start=None, end=None):
"""Return (start_date, end_date) inclusive for the requested window.
Precedence: explicit start/end > days > period. Default period: this-week.
Current-period ends are capped at `today` (no empty future days).
"""
if start or end:
if not (start and end):
raise ObsidianError("--start and --end must be given together")
s, e = _parse_date(start), _parse_date(end)
if e < s:
raise ObsidianError("--end is before --start")
return s, e
if days is not None:
if days < 1:
raise ObsidianError("--days must be >= 1")
return today - timedelta(days=days - 1), today
period = period or "this-week"
if period == "today":
s, e = today, today
elif period == "this-week":
s, e = _monday(today), _monday(today) + timedelta(days=6)
elif period == "last-week":
s = _monday(today) - timedelta(days=7)
e = s + timedelta(days=6)
elif period == "this-month":
s, e = _first_of_month(today), _last_of_month(today)
elif period == "last-month":
e = _first_of_month(today) - timedelta(days=1)
s = _first_of_month(e)
elif period == "this-year":
s, e = date(today.year, 1, 1), date(today.year, 12, 31)
elif period == "last-year":
s, e = date(today.year - 1, 1, 1), date(today.year - 1, 12, 31)
else:
raise ObsidianError(f"unknown period: {period}")
if period in _CURRENT and e > today:
e = today
return s, e
def has_window(args):
"""True if any window flag was passed (so `list` should filter)."""
return any(getattr(args, k, None) is not None
for k in ("period", "days", "start", "end"))
def filter_by_window(notes, start, end, which="modified"):
"""Keep notes whose modified/created local date is within [start, end]."""
key = "mtime" if which == "modified" else "btime"
return [n for n in notes if start <= _local_date(n[key]) <= end]
# --------------------------------------------------------------------------- #
# Frontmatter (best-effort; stdlib only — no YAML dependency)
# --------------------------------------------------------------------------- #
def split_frontmatter(text):
"""Return (meta_dict, body). If there's no ``---`` block, meta is empty.
Only the small subset Obsidian writes is understood: ``key: value`` lines
and ``tags`` as an inline ``[a, b]`` list or a ``- item`` block. This is for
display only, so anything unparseable is ignored, not an error.
"""
if not text.startswith("---"):
return {}, text
lines = text.splitlines()
if not lines or lines[0].strip() != "---":
return {}, text
end = None
for i in range(1, len(lines)):
if lines[i].strip() in ("---", "..."):
end = i
break
if end is None:
return {}, text
meta = {}
pending_key = None
for raw in lines[1:end]:
if pending_key and re.match(r"\s*-\s+", raw):
meta.setdefault(pending_key, [])
if isinstance(meta[pending_key], list):
meta[pending_key].append(_unquote(raw.split("-", 1)[1].strip()))
continue
m = re.match(r"([A-Za-z0-9_-]+):\s*(.*)$", raw)
if not m:
continue
key, val = m.group(1), m.group(2).strip()
if val == "":
pending_key = key # value is a block list on following lines
continue
pending_key = None
if val.startswith("[") and val.endswith("]"):
inner = val[1:-1].strip()
meta[key] = [_unquote(x.strip()) for x in inner.split(",") if x.strip()]
else:
meta[key] = _unquote(val)
body = "\n".join(lines[end + 1:])
return meta, body
def _unquote(s):
if len(s) >= 2 and s[0] == s[-1] and s[0] in "\"'":
return s[1:-1]
return s
# --------------------------------------------------------------------------- #
# Resolving / showing a note
# --------------------------------------------------------------------------- #
def resolve_note(vault, target):
"""Resolve `target` to a single absolute note path inside the vault.
Accepts a path relative to the vault, an absolute path inside it, or a bare
note name (with or without ``.md``) matched against every note's basename.
Raises if nothing matches, or if a name is ambiguous.
"""
base = os.path.realpath(vault)
# 1) Treat as a path (relative to vault, or absolute) — try with/without .md.
cands = [target, target + ".md"] if not target.lower().endswith(".md") else [target]
for c in cands:
ap = c if os.path.isabs(c) else os.path.join(base, c)
ap = os.path.realpath(ap)
if _within(base, ap) and os.path.isfile(ap):
return ap
# 2) Treat as a bare name — match basename across the vault.
want = target[:-3] if target.lower().endswith(".md") else target
matches = [n for n in scan_notes(base) if n["name"].lower() == want.lower()]
if len(matches) == 1:
# Same containment check as the path branch: a synced/shared vault can
# carry a symlink pointing outside the vault (e.g. at a key or dotenv),
# and os.stat in scan_notes follows it.
ap = os.path.realpath(matches[0]["path"])
if not (_within(base, ap) and os.path.isfile(ap)):
raise ObsidianError(
f"{matches[0]['rel']!r} resolves outside the vault — refusing to read it")
return ap
if not matches:
raise ObsidianError(f"no note found matching {target!r}")
rels = ", ".join(sorted(m["rel"] for m in matches))
raise ObsidianError(
f"{target!r} is ambiguous — {len(matches)} notes match: {rels}. "
"Pass the relative path instead."
)
def read_note(path):
try:
with open(path, "r", encoding="utf-8") as fh:
return fh.read()
except OSError as e:
raise ObsidianError(f"could not read {path}: {e.strerror or e}")
except UnicodeDecodeError:
raise ObsidianError(f"{path} is not UTF-8 text")
# --------------------------------------------------------------------------- #
# Saving a note
# --------------------------------------------------------------------------- #
def safe_filename(title):
"""Turn a note title into a safe ``.md`` filename (spaces kept — Obsidian
allows them). Strips path separators and filesystem-illegal characters."""
name = ILLEGAL_FILENAME_RE.sub(" ", title)
name = re.sub(r"\s+", " ", name).strip(" .")
if not name:
name = "note"
if len(name) > 120:
name = name[:120].rstrip(" .")
return name + ".md"
def _within(base, candidate):
try:
return os.path.commonpath([base, candidate]) == base
except ValueError: # different drives on Windows
return False
def resolve_save_path(vault, folder, filename):
"""Absolute path for a new note, guaranteed to live inside the vault."""
base = os.path.realpath(vault)
candidate = os.path.realpath(os.path.join(base, folder or "", filename))
if not _within(base, candidate):
raise ObsidianError("refusing to write outside the vault")
return candidate
def _yaml_str(s):
"""Quote a scalar for YAML frontmatter only when it needs it."""
if s == "" or s != s.strip() or re.search(r'[:#\[\]{}",&*!|>%@`]', s):
return '"' + s.replace("\\", "\\\\").replace('"', '\\"') + '"'
return s
def build_note(content, *, title=None, created=None, tags=None, source=None):
"""Compose a note: YAML frontmatter (only the fields given) + body."""
fm = ["---"]
if title:
fm.append(f"title: {_yaml_str(title)}")
if created:
fm.append(f"created: {created}")
if tags:
fm.append("tags: [" + ", ".join(_yaml_str(t) for t in tags) + "]")
if source:
fm.append(f"source: {_yaml_str(source)}")
fm.append("---")
body = content.strip("\n")
return "\n".join(fm) + "\n\n" + body + "\n"
def save_note(vault, content, *, title, folder=None, tags=None,
source="hermes", created=None, append=False, overwrite=False):
"""Write content into the vault. Returns (path, action, bytes)."""
if not content or not content.strip():
raise ObsidianError("nothing to save — content is empty")
filename = safe_filename(title)
path = resolve_save_path(vault, folder, filename)
os.makedirs(os.path.dirname(path), exist_ok=True)
exists = os.path.exists(path)
if exists and not (append or overwrite):
raise ObsidianError(
f"{os.path.relpath(path, os.path.realpath(vault))} already exists — "
"pass --append to add to it, --overwrite to replace it, or use a "
"different --title."
)
if exists and append:
existing = read_note(path)
stamp = created or date.today().isoformat()
text = existing.rstrip("\n") + f"\n\n---\n\n## Added {stamp}\n\n" \
+ content.strip("\n") + "\n"
action = "appended"
else:
text = build_note(content, title=title,
created=created or date.today().isoformat(),
tags=tags, source=source)
action = "overwrote" if exists else "created"
try:
_atomic_write(path, text)
except OSError as e:
raise ObsidianError(f"could not write {path}: {e.strerror or e}")
return path, action, len(text.encode("utf-8"))
def _atomic_write(path, text):
"""Write `text` to `path` atomically: a temp file in the same directory is
written, flushed, and ``os.replace``d over the target, so a crash mid-write
never leaves a half-written note (and never clobbers the original)."""
os.makedirs(os.path.dirname(path), exist_ok=True)
fd, tmp = tempfile.mkstemp(dir=os.path.dirname(path), suffix=".tmp")
try:
with os.fdopen(fd, "w", encoding="utf-8") as fh:
fh.write(text)
os.replace(tmp, path)
except BaseException:
try:
os.unlink(tmp)
except OSError:
pass
raise
def read_stdin_content():
"""Read piped stdin (the agent pipes the chat here); None if it's a tty."""
if sys.stdin is None or sys.stdin.isatty():
return None
return sys.stdin.read()
# --------------------------------------------------------------------------- #
# Formatting
# --------------------------------------------------------------------------- #
def _ellipsis(s, n=60):
return s if len(s) <= n else s[: n - 1] + "…"
def fmt_size(n):
n = float(n)
for unit in ("B", "K", "M", "G"):
if n < 1024 or unit == "G":
return f"{int(n)}B" if unit == "B" else f"{n:.0f}{unit}"
n /= 1024
def _table(headers, rows):
"""Render an aligned table: first column left, rest right-justified."""
widths = [len(h) for h in headers]
for row in rows:
for i, cell in enumerate(row):
widths[i] = max(widths[i], len(cell))
def line(cells):
out = [cells[0].ljust(widths[0])]
out += [cells[i].rjust(widths[i]) for i in range(1, len(cells))]
return " ".join(out)
sep = "-" * (sum(widths) + 2 * (len(widths) - 1))
lines = [line(headers), sep]
lines += [line(r) for r in rows]
return "\n".join(lines), sep, line
def render_list(notes, *, start=None, end=None, which="modified", limit=None):
shown = notes[:limit] if limit else notes
rows = [[_ellipsis(sanitize_text(n["rel"])), n["modified"], n["created"],
fmt_size(n["size"])]
for n in shown]
body, sep, line = _table(["Note", "Modified", "Created", "Size"], rows)
if start:
head = f"Notes modified {start.isoformat()} → {end.isoformat()}" \
if which == "modified" else \
f"Notes created {start.isoformat()} → {end.isoformat()}"
else:
head = "All notes"
out = [head, ""]
if rows:
out += [body, sep, f"{len(notes)} note(s)"]
if limit and len(notes) > limit:
out.append(f"(showing first {limit} — pass --limit 0 or --json for all)")
else:
out.append("(no notes match)")
return "\n".join(out)
# --------------------------------------------------------------------------- #
# Subcommands
# --------------------------------------------------------------------------- #
def _today():
return date.today()
def _vault(args):
return resolve_vault(getattr(args, "vault", None) or os.environ.get(ENV_VAULT))
def do_check(args):
vault = _vault(args)
notes = scan_notes(vault)
total = sum(n["size"] for n in notes)
if notes:
mods = [n["modified"] for n in notes]
span = f"{min(mods)} → {max(mods)}"
else:
span = "(none)"
print("OK — loaded Obsidian vault.")
print(f" vault: {vault}")
print(f" notes: {len(notes)} markdown file(s), {fmt_size(total)} total")
print(f" modified: {span}")
return 0
def do_list(args):
vault = _vault(args)
notes = scan_notes(vault)
start = end = None
if has_window(args):
start, end = compute_range(
_today(), period=args.period, days=args.days,
start=args.start, end=args.end)
notes = filter_by_window(notes, start, end, which=args.by)
if args.folder:
fl = args.folder.lower()
notes = [n for n in notes if fl in os.path.dirname(n["rel"]).lower()]
notes = sort_notes(notes, sort=args.sort)
limit = None if (args.limit in (None, 0)) else args.limit
if args.json:
print(json.dumps({
"vault": vault,
"range": {"start": start.isoformat(), "end": end.isoformat()} if start else None,
"by": args.by if start else None,
"count": len(notes),
"notes": [{k: n[k] for k in
("rel", "name", "modified", "created", "size")}
for n in notes],
}, indent=2))
else:
print(render_list(notes, start=start, end=end, which=args.by, limit=limit))
return 0
def do_show(args):
vault = _vault(args)
path = resolve_note(vault, args.note)
text = read_note(path)
meta, body = split_frontmatter(text)
if args.json:
print(json.dumps({
"rel": os.path.relpath(path, vault),
"path": path,
"frontmatter": meta,
"body": body if args.no_frontmatter else None,
"content": text,
}, indent=2))
else:
if args.no_frontmatter:
print(sanitize_text(body.strip("\n")))
else:
print(sanitize_text(text.rstrip("\n")))
return 0
def do_save(args):
vault = _vault(args)
content = args.content
if content is None and args.content_file:
content = read_note(os.path.expanduser(args.content_file))
if content is None:
content = read_stdin_content()
if content is None:
raise ObsidianError(
"no content given — pipe it on stdin, or pass --content / "
"--content-file. (The agent pipes the chat transcript on stdin.)")
path, action, nbytes = save_note(
vault, content, title=args.title, folder=args.folder,
tags=args.tag, source=args.source, append=args.append,
overwrite=args.overwrite)
rel = os.path.relpath(path, vault)
if args.json:
print(json.dumps({"rel": rel, "path": path,
"action": action, "bytes": nbytes}, indent=2))
else:
print(f"{action} {rel} ({fmt_size(nbytes)})")
return 0
# --------------------------------------------------------------------------- #
# CLI
# --------------------------------------------------------------------------- #
def _add_vault_arg(p):
p.add_argument("--vault", help=f"vault folder path (overrides ${ENV_VAULT})")
def build_parser():
p = argparse.ArgumentParser(
prog="obsidian_notes",
description="Read and write notes in an Obsidian vault.")
sub = p.add_subparsers(dest="cmd")
_add_vault_arg(sub.add_parser("check", help="verify the vault loads + summary"))
lst = sub.add_parser("list", help="list notes (all, or modified in a window)")
_add_vault_arg(lst)
g = lst.add_mutually_exclusive_group()
g.add_argument("--period", choices=PERIODS, help="named window (e.g. this-week)")
g.add_argument("--days", type=int, help="last N days (inclusive of today)")
lst.add_argument("--start", help="explicit start date YYYY-MM-DD (with --end)")
lst.add_argument("--end", help="explicit end date YYYY-MM-DD (with --start)")
lst.add_argument("--by", choices=("modified", "created"), default="modified",
help="which timestamp the window filters on (default modified)")
lst.add_argument("--folder", help="only notes whose subfolder path matches this")
lst.add_argument("--sort", choices=("modified", "created", "name"),
default="modified", help="sort order (default modified, newest first)")
lst.add_argument("--limit", type=int, default=50,
help="max rows in text output (0 = no limit; --json is never capped)")
lst.add_argument("--json", action="store_true", help="machine-readable output")
sh = sub.add_parser("show", help="print a note's contents")
_add_vault_arg(sh)
sh.add_argument("note", help="note name, or path relative to the vault")
sh.add_argument("--no-frontmatter", action="store_true",
help="strip the YAML frontmatter, print only the body")
sh.add_argument("--json", action="store_true", help="machine-readable output")
sv = sub.add_parser("save", help="write a new note into the vault")
_add_vault_arg(sv)
sv.add_argument("--title", required=True, help="note title (becomes the filename)")
sv.add_argument("--folder", help="subfolder within the vault to write into")
sv.add_argument("--tag", action="append", help="frontmatter tag (repeatable)")
sv.add_argument("--source", default="hermes",
help="frontmatter 'source' value (default: hermes)")
sv.add_argument("--content", help="note body (else read from --content-file or stdin)")
sv.add_argument("--content-file", help="read the note body from this file")
sv.add_argument("--append", action="store_true",
help="if the note exists, append under a dated separator")
sv.add_argument("--overwrite", action="store_true",
help="if the note exists, replace it")
sv.add_argument("--json", action="store_true", help="machine-readable output")
return p
def main(argv=None):
parser = build_parser()
args = parser.parse_args(argv)
try:
if args.cmd == "check":
return do_check(args)
if args.cmd == "list":
return do_list(args)
if args.cmd == "show":
return do_show(args)
if args.cmd == "save":
return do_save(args)
parser.print_help()
return 0
except ObsidianError as e:
print(f"error: {e}", file=sys.stderr)
return 1
except KeyboardInterrupt:
return 130
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |