hephaestus/heph.nvim

heph.nvim

The primary surface for hephaestus — an obsidian.nvim replacement that is a thin client of the local hephd daemon over its unix-socket JSON-RPC (tech-spec §8). Notes, journals, and tasks are edited as ordinary Neovim buffers; saving routes through the daemon.

Status: built in checkpointed slices. 11a (this slice) delivers the RPC client, buffer-backed editing, [[wiki-link]] following, and the daily journal. Task/agenda views (:Heph next/list/capture), the per-task log, and promotion arrive in 11b/11c. See tech-spec §14.

How it works

• Buffer-backed nodes. A node is edited in a buffer named heph://node/<id>. Opening it loads the markdown body via node.get; :w saves the whole buffer back via node.update (the backend diffs it into a text CRDT, so sending the full buffer is correct). buftype=acwrite.
• Links. Press <CR> on a [[wiki-link]] to jump to its node (resolved exactly via node.resolve). Unresolved links are allowed — they just notify.
• Journal. :Heph today (or :Heph journal YYYY-MM-DD) opens a dated journal note; the id is deterministic so reopening is idempotent.

Setup

Requires Neovim ≥ 0.10 and hephd on PATH (e.g. cargo installed). By default the plugin is plug-and-play — it starts and manages its own hephd:

require("heph").setup({})   -- spawns a local hephd against the default XDG paths

• autostart = true (default): if nothing is serving the socket, the plugin spawns a local hephd, kills only what it spawned on exit, and self-heals (respawns + reconnects if the daemon dies mid-session).
• Running your own daemon (a server/client architecture, or a launchd service)? Set autostart = false and point at its socket — the plugin then connects only, never spawning over your daemon, and warns if it's unreachable. A daemon already serving the socket is always respected, even with autostart = true (the plugin only spawns when nothing is there).

require("heph").setup({
  -- socket = "...",        -- default: $HEPH_SOCKET, else hephd's XDG path
  -- db     = "...",        -- DB for an autostarted daemon ($HEPH_DB, else default)
  -- autostart = true,      -- false = connect-only (you run hephd yourself)
  -- bin = "hephd",         -- daemon binary for autostart
  -- keymaps = true,        -- <leader>h* maps
})

Dev isolation: set $HEPH_SOCKET / $HEPH_DB (or run mise run dev) so a development Neovim drives a separate daemon + DB and never touches real data.

Commands

Command	Action
:Heph today	Open today's journal
:Heph journal <YYYY-MM-DD>	Open a dated journal
:Heph follow	Follow the [[link]] under the cursor (also <CR>)
:Heph open <id>	Open a node buffer by id

Tests

The e2e suite drives the plugin in headless Neovim against a real daemon:

mise run test-nvim   # builds hephd, runs the headless e2e suite

The suite uses a small self-contained busted-style runner (tests/e2e/runner.lua) — no external plugins and no network, so it is deterministic. Dev runs use system-installed Neovim (≥ 0.10) + rustc; CI runs the same suite inside a Dagger container that provides them (slice 11c).