eblume/hephaestus
1
0
Fork 0
generated from eblume/project-template
Code Issues Pull requests Projects Releases 10 Packages Wiki Activity Actions
hephaestus/docs/how-to/install-heph.md
Erich Blume 6514296b87 docs: reframe tech-spec as historical; heph self-hosts its roadmap 
v1 reached Todoist feature-parity, so remaining/future work is now tracked
in heph itself — tasks in the Hephaestus project (heph view ondeck) — not in
a doc. Renamed docs/reference/tech-spec.md -> v1-prototype-tech-spec.md and
rewrote all 27 [[tech-spec]] wiki-links + README/changelog path refs (docs
checks green). Retitled + bannered the spec as a historical v1 build record
and froze its §14 tracker. AGENTS.md gains a "Planning future work" section
(capture via `heph task --project Hephaestus`, triage in heph-tui On Deck);
README status reflects parity + the three daily-driver surfaces. The design
doc remains the living rationale.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-03 20:19:35 -07:00

2.8 KiB
Raw Blame History

title modified tags
Install heph (and isolate dev) 2026-06-02
how-to

Install heph (and isolate dev)

How to install heph/hephd from the forge and run the heph.nvim plugin, isolated from in-repo development so the two never share data. No prebuilt binaries yet — everything builds from source (works on macOS/arm64, linux/arm64, linux/amd64).

1. Install the binaries from the forge

Build and install heph + hephd to ~/.cargo/bin (on PATH) from a forge ref. Until v1 is tagged, install from the branch:

cargo install --locked \
  --git ssh://forgejo@forge.ops.eblu.me:2222/eblume/hephaestus.git \
  --branch feature/v1-prototype \
  heph hephd

Re-run with --tag vX.Y.Z once a release is cut. This needs forge SSH access (an unlocked 1Password / ssh-agent key).

The installed daemon owns the default paths — socket $XDG_RUNTIME_DIR/heph/hephd.sock, DB $XDG_DATA_HOME/heph/heph.db — i.e. your real data.

2. The Neovim plugin

heph.nvim lives in a subdirectory of the monorepo, and lazy.nvim can't load a subdir plugin from a bare git URL (it puts the clone root on runtimepath). For now, point lazy at a dedicated checkout via dir:

git clone --branch feature/v1-prototype \
  ssh://forgejo@forge.ops.eblu.me:2222/eblume/hephaestus.git \
  ~/.local/share/heph/checkout

-- lazy.nvim spec
{
  dir = vim.fn.expand("~/.local/share/heph/checkout/heph.nvim"),
  config = function()
    require("heph").setup({}) -- connect-only: talks to the daemon you started
  end,
}

The plugin is connect-only — it talks to a hephd you run as a service, it does not start one itself. Start the daemon once:

heph daemon start    # launchd agent (macOS) / systemd user service (Linux)

See run-the-daemon for start/stop/restart/status. Update the plugin by git pulling the checkout (and after a cargo install upgrade, heph daemon restart to pick up the new hephd). (A future split of heph.nvim into its own forge repo will make this a normal { "eblume/heph.nvim" } spec.)

3. Isolate development

In-repo development must not touch the installed store. Run the dev daemon on separate paths and point a dev Neovim at it:

mise run dev   # runs the working-tree hephd on .dev/hephd.sock + .dev/heph.db

# dev Neovim — the plugin reads these envs and targets the dev daemon
HEPH_SOCKET="$PWD/.dev/hephd.sock" HEPH_DB="$PWD/.dev/heph.db" nvim

The installed plugin (no envs) talks to the installed daemon; the dev Neovim talks to the dev daemon. They never share a socket or DB. .dev/ is gitignored.

Related