hyalo

A structured CLI for markdown knowledgebases — built for humans and AI agents.

If you maintain an Obsidian vault, a Zettelkasten, documentation site, or any folder of .md files with YAML frontmatter, you've probably hit the limits of grep and manual editing. Hyalo gives you a fast, structured way to search, filter, and bulk-edit your markdown files from the command line.

Hyalo does not define how you organize your notes. It works with the structure you already have — frontmatter properties, tags, [[wikilinks]], markdown links, task checkboxes — and gives you powerful tools to query and maintain it at scale.

The LLM Wiki pattern

Andrej Karpathy popularized the idea of an LLM-maintained wiki: instead of asking an LLM the same questions repeatedly, you have it build and maintain a persistent, structured knowledgebase that compounds over time. Every source ingested, every question answered adds to the wiki rather than vanishing with the conversation.

Hyalo is the tooling layer that makes this practical. An LLM agent can use hyalo find to search across thousands of notes by metadata, full-text, or regex. It can use hyalo set to bulk-update frontmatter, hyalo mv to reorganize files while reporting any ambiguous or unsupported link rewrites, and hyalo lint to enforce schema consistency — without guessing at YAML syntax.

What it does

Search	Full-text search with BM25 ranking, regex, frontmatter filters, tag/section/task queries
Mutate	Set, remove, or append to properties and tags — one file or hundreds at once
Move	Rename or reorganize files; hyalo rewrites supported links and reports ambiguous or unsupported cases
Fix links	Detect broken links and auto-repair them with fuzzy matching
Validate	Lint frontmatter against type schemas, auto-fix defaults, typos, and date formats
Overview	Property/tag distributions, task counts, orphan files, link health at a glance

Why hyalo?

• Fast. Parallel scanning, streaming I/O, optional snapshot index. Handles 10,000+ file vaults in under a second.
• Structured output. TTY-aware: compact text for terminals, json when piped — with built-in --jq support. Easy to pipe into scripts, CI, or AI agents.
• AI-agent friendly. Integrates with Claude Code, Codex, and Pi. Set up project workflows with hyalo init --claude, hyalo init --codex, or hyalo init --pi; Codex and Pi also have installable packages.
• Safe mutations. Bulk repairs, moves, generators, and link rewrites provide documented preview modes. Check hyalo <cmd> --help for the exact command contract.
• Cross-platform. Works on macOS, Linux, and Windows. No runtime dependencies.

Installation

Homebrew (macOS & Linux)

brew trust --formula ractive/tap/hyalo   # Homebrew 6+: third-party taps need one-time trust
brew install ractive/tap/hyalo

Covers macOS (Apple Silicon) and Linux (x86_64 and ARM64). The Linux binaries are statically linked against musl, so they have no glibc dependency.

Homebrew 6 introduced tap trust: formulae from third-party taps refuse to load until trusted. brew trust --formula scopes the trust to just this formula; brew trust ractive/tap trusts the whole tap instead.

apt (Debian & Ubuntu)

curl -sLf 'https://dl.cloudsmith.io/public/ractive/hyalo/cfg/setup/bash.deb.sh' | sudo bash
sudo apt install hyalo

The setup script registers the Cloudsmith-hosted apt repository; apt install then pulls hyalo and picks up future updates through apt upgrade. Shell completions are installed system-wide automatically.

dnf / yum / zypper (Fedora, RHEL & openSUSE)

curl -sLf 'https://dl.cloudsmith.io/public/ractive/hyalo/cfg/setup/bash.rpm.sh' | sudo bash
sudo dnf install hyalo    # or: yum install hyalo / zypper install hyalo

Registers the Cloudsmith-hosted rpm repository. Shell completions are installed system-wide automatically.

AUR (Arch Linux)

yay -S hyalo-bin    # or: paru -S hyalo-bin

Installs the prebuilt release binary (x86_64 and ARM64). Without an AUR helper:

git clone https://aur.archlinux.org/hyalo-bin.git
cd hyalo-bin && makepkg -si

The hyalo-bin package is updated automatically on every release.

Scoop (Windows)

scoop bucket add ractive https://github.com/ractive/scoop-bucket
scoop install hyalo

winget (Windows)

winget install ractive.hyalo

Cargo (from crates.io)

cargo install hyalo-cli    # installs the `hyalo` binary

npm

The npm distribution supports Node.js 22.14 or newer and npm 11.5.1 or newer on macOS arm64, Linux x64/arm64 with glibc or musl, and Windows x64/arm64:

npm install @ractive-ch/hyalo
npx --no-install hyalo --version

Version 0.23.0 adds a typed TypeScript API with ESM and CommonJS entrypoints alongside the CLI. Import find, read, summary, and config directly from @ractive-ch/hyalo; see the API documentation. npm selects exactly one native platform dependency at the same version. The npm-only 0.22.0 release (no GitHub release) shipped the CLI launcher only.

Manual download

Every GitHub Release publishes:

• Archives named hyalo-v<version>-<target>.{tar.gz,zip} for Linux (x86_64/ARM64, glibc and musl), macOS (Apple Silicon), and Windows (x86_64/ARM64). Each archive contains the binary, LICENSE, README.md, and a completions/ directory with bash/zsh/fish scripts.

• Standalone .deb and .rpm packages for users who prefer to install a single downloaded file directly (they install completions system-wide, same as the apt/dnf repos above).

• CycloneDX SBOMs (*.cdx.json) and GitHub build-provenance attestations for the native builds. Verify an artifact with:

  gh attestation verify hyalo-v0.20.0-aarch64-apple-darwin.tar.gz --owner ractive
  

A SHA256SUMS file with checksums for every asset is attached to each release.

Intel Mac users: Homebrew and the prebuilt macOS archive target Apple Silicon only. Use cargo install hyalo-cli above.

Shell completions

The system packages (apt/dnf and the standalone .deb/.rpm) install completions automatically. For the Homebrew, Scoop, cargo, or tarball routes, either copy the scripts from the archive's completions/ directory or generate them on the fly:

hyalo completions bash > ~/.local/share/bash-completion/completions/hyalo
hyalo completions zsh  > ~/.local/share/zsh/site-functions/_hyalo
hyalo completions fish > ~/.config/fish/completions/hyalo.fish

hyalo completions --help lists every supported shell (also elvish and powershell).

Quick start

# Point hyalo at the folder that contains your .md files
# (omit --dir if the project root itself is the knowledgebase)
hyalo init --dir docs

# Bird's-eye view: file count, tags, properties, link health
hyalo summary

# Full-text search (BM25 ranked, boolean operators) and frontmatter filters
hyalo find "retry OR timeout -deprecated"
hyalo find --property status=draft --tag research
# Nested properties filter by dot-path: [email protected] traverses
# `contact: {email: ...}`; a literal dotted key in a flat map wins first
hyalo find --property [email protected]
# Lists of maps are descended too: any element matching wins, and a numeric
# segment pins one element (`contacts.0.email`)
hyalo find --property [email protected]
# Compact filename-only projection for agents / shell pipelines
hyalo find --property status=planned --filenames-only | sort
# Sequence-keyed documents: glob by number (recursively reaches archived files)
hyalo find --glob '**/iteration-206-*.md' --filenames-only

# Bulk-update metadata (drop --dry-run to write)
hyalo set --property status=reviewed --where-tag research --dry-run

# Move or rename — every [[wikilink]] and [markdown](link) across the vault is rewritten
hyalo mv old/path.md archive/path.md --dry-run

# Detect and repair broken links (preview; add --apply to write)
hyalo links fix --dry-run

# Convert unlinked mentions of known page titles into [[wikilinks]] (preview; add --apply to write)
hyalo links auto --dry-run

# Validate frontmatter against your schema and the markdown body against bundled lint rules
hyalo lint
# Preview autofixes; drop --dry-run to apply them
hyalo lint --fix --dry-run

# Scaffold a new file from a type schema (preview; drop --dry-run to write)
hyalo new --type iteration --file iterations/iter-99-example.md --dry-run

Commands that expose --dry-run preview their documented changes before applying them. Other mutations, including task toggles, report their exact behavior in hyalo <cmd> --help.

Markdown file links resolve from the containing note's folder first, then from the scanned directory's root. This supports Obsidian's "Absolute path in vault" format for notes and other linked files, without requiring a particular folder name. Explicit . or .. path components keep a link source-relative; leading / paths follow --site-prefix. Balanced parentheses in destinations such as ![image](images/photo%20(1).png) are preserved. Moving notes keeps these links pointing to the same files. Older indexes fall back to a disk scan; rebuild them with hyalo create-index to use indexed reads with the corrected parser.

Agent loop: new → edit → lint

hyalo new creates a skeleton file with TBD placeholders that are intentionally invalid — they will fail hyalo lint. This is by design. The loop is:

1. hyalo new --type <name> --file <path> — scaffold the skeleton
2. Edit the file to fill in the real values
3. hyalo lint --file <path> — see which placeholders still violate the schema

The lint output tells you exactly what to fix, field by field.

Claude Code integration

hyalo init --claude

This installs two skills and a rule that teach Claude Code to use hyalo instead of raw Read/Edit/Grep/Glob when working with your vault:

hyalo skill — Auto-triggered whenever Claude touches markdown files in your vault. It uses hyalo find, hyalo set, hyalo mv, etc. for structured access to frontmatter, tags, links, and tasks.

hyalo-tidy skill (/hyalo-tidy) — A five-phase knowledgebase consolidation. Think of it as a librarian doing a periodic shelf-read: it orients with hyalo summary, gathers recent signal from git history, detects structural issues (broken links, orphan files, stale statuses, missing metadata), applies conservative fixes, and reports a health dashboard. Run it periodically to keep your vault clean.

You can explicitly ask tidy to use Jev for selected documents and fields, for example: “Use Jev to suggest missing types and existing folders for these five inbox notes; audit only.” This optional path needs Bun or Node.js and a TYPESAFE_API_KEY. It sends selected document evidence and approved classification rubrics to Typesafe; the helper returns suggestions, and the agent reviews them against local schemas before proposing changes. Ordinary tidy does not call Jev and requires no JavaScript runtime or API key. See the Jev workflow for scope, setup, and preview requirements.

knowledgebase rule — Scoped to <your-vault>/**. Reminds Claude to prefer hyalo CLI commands over built-in file tools whenever it touches vault files.

All artifacts are idempotent — re-running hyalo init --claude updates to the latest versions. hyalo deinit removes everything cleanly.

Install the Codex integration

For project-local skills and knowledgebase guidance:

hyalo init --codex
hyalo init --codex --profile okf

This installs skills under .agents/skills/ and a managed section in AGENTS.md. Existing configuration selects the vault; --dir explicitly selects another one. The flags compose with --claude and --pi. Re-run after upgrading Hyalo to refresh generated skills. hyalo deinit removes managed project artifacts while preserving unrelated skills and instruction text.

For use across projects, this repository also ships a skills-only Codex plugin:

# From a checkout containing the Codex integration:
codex plugin marketplace add .
codex plugin add hyalo@hyalo
hyalo init --codex --codex-plugin

Plugin mode configures the project and removes managed project skill copies to avoid duplicate discovery. It does not install the plugin or modify global Codex settings. Keep --codex-plugin on subsequent init runs. Start a new Codex session after setup. The plugin requires hyalo on PATH; post-edit lint is skill guidance, not an automatic hook. Project skills also serve clients without plugin support.

See Codex integration for update, removal, profiles, and maintainer verification instructions.

Install the pi integration

For the pi coding agent, the integration ships as an installable pi package:

pi install git:github.com/ractive/hyalo

From hyalo ≥ 0.21 on, pin the release tag matching your binary instead (recommended — the extension's expected output shapes track the binary, so a matched tag avoids extension/binary drift; the tag form needs ≥ v0.21.0, earlier tags predate the root package manifest):

# replace X.Y.Z with the version `hyalo --version` prints
pi install git:github.com/ractive/[email protected]

This registers the hyalo extension (generic + typed tools: hyalo_find, hyalo_read, hyalo_set, and hyalo_task) plus the hyalo and hyalo-tidy skills. The extension runs a post-write lint guardrail for typed hyalo_set/hyalo_task effects and Pi host write/edit events; generic mutation calls retain their normal CLI result and diagnostics. A main-HEAD install updates independently of hyalo releases via pi update --extensions; a pinned-tag install moves only on an explicit re-pin (pi install git:…@vX.Y.Z).

A hyalo binary on PATH is required (any recent release; typed tools need ≥ 0.21). See pi-package/README.md for details.

Vendored fallback — if you prefer no git dependency, hyalo init --pi writes the same extension, generated API runtime, declarations, and skills into your vault's .pi/ directory. The runtime is self-contained and calls the hyalo binary on PATH without installing the npm package. The vendored copy only changes when you upgrade hyalo and re-run the command, so the package install above is the recommended path.

Profiles

Profiles are pre-packaged schema and lint configurations for popular markdown conventions. hyalo init --profile <name> merges a declarative fragment into .hyalo.toml; add --claude to also install a bundled Claude Code skill for the convention. Profiles are composable and idempotent: multiple --profile runs deep-merge without clobbering each other or your hand-written config, and hyalo lint --profile <name> works as an ephemeral overlay on any checkout (CI, a freshly cloned third-party bundle) with no config file at all.

hyalo init --profile okf         # Open Knowledge Format bundles
hyalo init --profile madr        # MADR architecture decision records
hyalo init --profile skills      # Agent Skills SKILL.md validation
hyalo init --profile changelog   # Keep a Changelog

Profile	Scope	Binds	Key rules
okf	Whole bundle	type-required concepts; index.md/log.md reserved	Permissive (warn-only): citations, reserved-file structure, augmentation guard
madr	docs/decisions/**	adr schema, status lifecycle, NNNN-slug.md	MADR-SUPERSEDE-RESOLVE, MADR-DUPLICATE-NUMBER (warn)
skills	**/SKILL.md	skill schema (name/description bounds)	SKILL-RESERVED-NAME (error), name↔dir + line-budget (warn)
changelog	CHANGELOG.md	frontmatter-less changelog type	CHANGELOG-* grammar (mostly error), empty-section + link-ref (warn)

okf — Open Knowledge Format. Vendor-neutral "knowledge bundles": a directory of Markdown concept files whose frontmatter requires exactly one field (type), with reserved frontmatter-free index.md/log.md files. The profile sets up the schema, reserved-file exemptions, and bundle-absolute links; hyalo lint --profile okf validates a bundle in the spec's permissive-consumption spirit — errors only where the spec demands them, warnings for everything else (broken cross-links, reserved-file drift, citations). The hyalo okf index and hyalo okf log generators maintain the reserved files deterministically: they rebuild each directory's index.md link list and prepend dated log.md entries inside managed marker regions, preserving hand-written prose around them — a file with malformed markers is never rewritten, so a generator can never delete your prose. Generators are dry-run by default and report drift in their payload (results.changed), so a CI freshness check reads that rather than the exit code.

madr — MADR architecture decision records. One decision per file under docs/decisions/, named NNNN-slug.md, with a status lifecycle. The profile binds an adr schema to that subtree (no type: frontmatter needed), hyalo new --type adr scaffolds a decision with the MADR-4 sections, and hyalo madr toc maintains a table-of-contents dashboard in docs/decisions/README.md. Advisory rules catch dangling superseded by references and duplicate ADR numbers.

skills — Agent Skills SKILL.md validation. The spec's frontmatter is unusually strict (slug-pattern name, length-bounded description), which makes hyalo a fast, CI-friendly validator for a whole skill collection: hyalo lint --profile skills. hyalo new --type skill scaffolds a compliant SKILL.md, and the profile re-admits the hidden .claude/skills/** directory so the canonical Claude Code skill location is reachable in place.

changelog — Keep a Changelog. Enforces the full CHANGELOG.md grammar (version and date ordering, the six change categories, footer link references) as CHANGELOG-* lint rules, and maintains the file deterministically: hyalo changelog add appends an entry under [Unreleased], and hyalo changelog release X.Y.Z rotates it into a dated version section — hyalo's own releases are cut this way. Works with a repo-root CHANGELOG.md even when your vault lives in a subdirectory.

Each profile's full behaviour — schemas, generator edge cases, individual rules — is documented in its bundled skill (hyalo init --profile <name> --claude), in hyalo lint-rules list, and in hyalo <cmd> --help.

Lint your vault in CI (GitHub Actions)

Gate every change on a clean vault — the setup-hyalo action installs the prebuilt binary in seconds, so a full-vault gate is two steps:

# .github/workflows/lint-kb.yml
name: Lint knowledgebase
on: [push, pull_request]
jobs:
  lint-kb:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: ractive/setup-hyalo@v1   # installs hyalo, adds it to PATH
      - run: hyalo lint --strict --format github

Findings render as inline annotations on the PR diff, and --strict makes broken links fail the job. The diff-aware pull-request variant, the OKF drift check, and an @claude review setup (claude-code-action with the full hyalo toolbox) are covered in docs/ci.md.

Configuration

hyalo init creates a .hyalo.toml in your project root. All fields are optional — CLI flags always take precedence:

dir = "./my-vault"        # vault directory (default: ".")

[schema.types.iteration]
required = ["title", "date", "status", "tags"]
filename-template = "iterations/iteration-{n}-{slug}.md"

Schemas can type and require frontmatter properties, bind types to path patterns, and drive hyalo new scaffolding and hyalo lint validation. The full reference — config keys, saved views, CWD-aware behaviour, the snapshot index — lives in docs/configuration.md.

Building from source

cargo build --release

Maintainer docs — the release process and package-repository hosting — live in docs/releasing.md.

License

MIT — this repository contains code generated in whole or in part by AI systems under human supervision. See AI_NOTICE for details.

"Hyalo" — from hyaloclastite — is a volcanic glass, just like obsidian.