English | Español

headless-vault-kit

Puts Obsidian's own functionality back on a vault that lives on a headless server, where the app never opens: a SQLite index, backlinks, Bases queries, and agent-driven automation running 24/7. The CLI installs as hvk.

The problem

Move an Obsidian vault to a headless server — a machine with no screen, so an agent and its automations can work on the notes around the clock — and the files arrive fine: Obsidian Headless keeps them in sync. What never happens is Obsidian itself opening, and with it you lose everything the app computes at startup: backlinks, Dataview queries, Bases, the CLI, plugins. The result: synced notes, and nothing that can answer a question about them.

What it does

Don't emulate Obsidian — replicate its data. Everything the app derives at startup is state that can be rebuilt from the files themselves. This project rebuilds it on the server:

• Indexer: parses the vault into SQLite the same way the app's metadata cache does (frontmatter, tags, links, backlinks, tasks, headings, full text), with incremental updates as sync delivers changes.
• hvk CLI: search, backlinks, tasks and properties in milliseconds, so agents can query the vault without burning tokens reading files one by one.
• Queries without the app: Bases (.base) executed against the index, plus materialized views rendered into your notes as Markdown — visible from any device.
• The vault as a job queue: order-notes with their state in frontmatter; a runner executes them with Claude Code and the results sync back to all your devices.
• Harness: permissions, hooks and auditing via Claude Code's native features + git.
• MCP server: hvk mcp serves the vault to any MCP client over stdio — read-only by default, and able to write only when the instance was started with --write.

The scope is governed by a three-tier model: the app's native behavior is replicated exactly; Obsidian's official formats (Bases, Canvas, templates) get full support; and the most popular community plugins are included only when their state lives in parseable files — everything else goes through an extensible parser interface so anyone can contribute an adapter. Obsidian Kanban boards are read through that interface as the worked example. Plugin code is never executed and the UI is never reproduced.

Requirements

There are two different things you might want, and they ask for very different amounts.

To use the hvk command — index a vault, ask it questions, materialise views, run jobs:

To run the whole 24/7 system on a server — sync, an agent on Telegram, scheduled jobs — you also need Linux with systemd, Node.js 22+, Bun, tmux, git and an Obsidian Sync subscription. That has its own runbook and its own preflight check — do not start there.

Install

Not on PyPI yet, so both routes install from this repository. Pick one.

A. As a command, with uv — recommended if you just want to use it. hvk lands on your PATH in its own isolated environment:

uv tool install --from git+https://github.com/angelsaez/headless-vault-kit headless-vault-kit

uv tool upgrade headless-vault-kit updates it later; uv tool uninstall headless-vault-kit removes it completely.

B. From a checkout — if you want to read the code, change it, or run the tests:

git clone https://github.com/angelsaez/headless-vault-kit
cd headless-vault-kit
python -m venv .venv

Then, on Linux or macOS:

.venv/bin/pip install -e ".[dev]"
.venv/bin/hvk --version

On Windows (PowerShell):

.venv\Scripts\pip install -e ".[dev]"
.venv\Scripts\hvk --version

In Git Bash use forward slashes instead: .venv/Scripts/pip, .venv/Scripts/hvk.

The [dev] part adds pytest and nothing else. Leave it out if you are not running tests.

Check it worked

Point it at a vault — a real one is fine, hvk only reads, and its index is written outside the vault (ADR-0002):

hvk --vault /path/to/vault scan
hvk --vault /path/to/vault info
hvk --vault /path/to/vault backlinks "Some Note"

scan prints how many files it indexed and how long it took; on a few hundred notes that is well under a second. If backlinks names the notes you expected, everything below this line works too.

Two things worth knowing straight away:

• Run it inside a vault and --vault can be dropped. hvk walks up from the working directory until it finds a .obsidian/ folder.
• hvk rebuild is always safe. The index is derived from your files and nothing else, so deleting it costs time and nothing more. Nothing in scan, search, backlinks, links, tags, tasks, props, orphans, base or info ever writes to your vault; only views --apply and jobs --run do, and both say so in their names.

Every command takes --json for machine-readable output; hvk watch emits JSON Lines, one object per batch, so it can be piped into a log.

To keep the index current, run hvk watch as a service and re-hash nightly from cron:

17 4 * * *   hvk --vault /path/to/vault verify
*/30 * * * *  hvk --vault /path/to/vault views --apply

The second line is what keeps materialised views current. It is safe to run as often as you like: it writes only what actually changed, and nothing at all when nothing did. Both lines, the order-note runner and a nightly backup are installed for you by deploy/install.sh.

A systemd unit for the watcher, and everything else needed to run this on a server, is in deploy/.

Once this is on PyPI, installing it will be uv tool install headless-vault-kit and nothing else. The command stays hvk: what a package is called and what it puts on your PATH are two different names, and the long one is the descriptive one.

The complete guide

Every command, what each part is for, the worked cases, and the two-language vocabulary: docs/GUIDE.md — in Spanish, docs/GUIDE.es.md.

Repository layout

src/hvk/      The package: indexer, parsers, the write layer, the MCP server and the CLI
tests/        pytest, run against the synthetic vaults below
test-vaults/  Synthetic vaults, including the awkward cases: Unicode, odd YAML,
              duplicate headings, ambiguous and broken links
deploy/       systemd user units, cron and the runbook for putting it on a server
tools/        Development utilities, not part of the product (vault mirror, testbed)
skills/       Claude Code skills, so an agent knows which command to reach for
docs/adr/     Architecture decision records — the "why" behind every design choice
docs/         CHANGELOG.md, the repository journal

Written in Python 3.11+ (ADR-0001), with ruamel.yaml and watchdog as its only runtime dependencies.

Contributing

Pull requests are welcome, and so are bug reports and questions. CONTRIBUTING.md has the whole of it: how to run the suite, the rules that are not negotiable, the one-ADR-per-decision working rule, and how to write a parser adapter for a format this does not read yet.

Contributions are licensed under this project's own MIT, and there is no CLA.

If you are reading the code, the tests are the map:

.venv/bin/pytest              # the suite, a few seconds
.venv/bin/pytest -m slow      # performance, against a generated 10,000-note vault

Every push and pull request runs the suite on Python 3.11 and 3.13, installs the built package both with pip and with uv tool install and checks each answers against a vault it has never seen, and parses every shell script (the workflow). Linux only: Linux is where this is meant to run.

The deployment is not exercised in CI — it needs a systemd user instance and a machine to throw away. It lives in tools/testbed/, a disposable Debian container, and that is where to run deploy/selftest.sh before trusting a change to deploy/.

Name and command

The repository and tool are headless-vault-kit (descriptive, self-explanatory); the CLI binary is hvk (hvk search, hvk backlinks, hvk base "...") — long clear repo name, short comfortable command.

Releasing

How a version reaches PyPI, and why there is no API token in this repository: docs/RELEASING.md.

How far along this is

What is built, what is postponed and how mature it is: docs/ROADMAP.md.

License

MIT. Do what you like with it, including commercially; keep the copyright notice, and there is no warranty. The full text is in LICENSE.

Both runtime dependencies are permissive too — ruamel.yaml is MIT and watchdog is Apache-2.0 — so nothing here constrains what you build on top.