Skip to content

gerodp/hermes-productivity-skills / notes/obsidian-notes

obsidian-notes

Verified

Read 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.

FileKindSize
SKILL.mdskill md11.4 KB
scripts/obsidian_notes.pyscript24.3 KB
scripts/test_obsidian_notes.pyscript11.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())
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall