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 keeping all links intact, and hyalo lint to enforce schema consistency — all without ever touching raw files or guessing at YAML syntax.

What it does

Why hyalo?

• Fast. Parallel scanning, streaming I/O, optional snapshot index. Handles 10,000+ file vaults in under a second.
• Structured output. JSON by default with built-in --jq support. Easy to pipe into scripts, CI, or AI agents.
• AI-agent friendly. Designed as a tool for Claude Code and other LLM coding agents. One command sets up the integration: hyalo init --claude.
• Safe mutations. Dry-run mode on all write operations. Preview before committing changes.
• Cross-platform. Works on macOS, Linux, and Windows. No runtime dependencies.

Quick start

# Initialize: point hyalo at the folder that contains your .md files with the --dir flag.
# This is typically a subfolder like docs/, wiki/, or knowledgebase/.
# Omit --dir if the project root itself is the knowledgebase.
hyalo init --dir docs

# Get a bird's-eye view
hyalo summary --format text

# Full-text search (BM25 ranked, with boolean operators)
hyalo find "retry backoff"
hyalo find "retry OR timeout -deprecated"

# Filter by frontmatter
hyalo find --property status=draft --tag research

# Bulk-update metadata
hyalo set --property status=reviewed --where-tag research

# Move a file — all links across the vault are updated
hyalo mv --file old/path.md --to archive/path.md

# Detect and fix broken links
hyalo links fix --apply

# Auto-link: scan body text for unlinked mentions of known page titles
# and convert them to [[wikilinks]]. Detects titles from filenames,
# frontmatter `title`, and `aliases`. Skips code blocks, existing links,
# headings, and comment fences.
hyalo links auto                     # dry-run preview
hyalo links auto --apply             # write changes
hyalo links auto --first-only --apply  # only first mention per target
hyalo links auto --exclude-title API --exclude-target-glob 'templates/*' --apply
hyalo links auto --file notes/todo.md --apply   # single-file mode

# Lint against your schema
hyalo lint --fix

Every write command supports --dry-run to preview changes before applying them.

Run hyalo --help or hyalo <command> --help for the full reference.

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.

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.

Installation

Homebrew (macOS & Linux)

brew tap ractive/tap
brew install ractive/tap/hyalo

Scoop (Windows)

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

winget (Windows)

winget install ractive.hyalo

Cargo (from crates.io)

cargo install hyalo-cli

Manual download

Pre-built binaries for Linux (x86_64, ARM64, glibc and musl), macOS (Apple Silicon), and Windows (x86_64, ARM64) are available on the GitHub Releases page.

Intel Mac users: Homebrew bottles are only provided for Apple Silicon. Use cargo install above.

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: ".")
format = "text"           # output format: "json" (default) or "text"
hints = false             # drill-down command hints (default: true)
default_limit = 100       # max results for list commands (default: 50; 0 = unlimited)

[links]
frontmatter_properties = ["related", "depends-on"]   # list properties that contribute to the link graph
case_insensitive = "auto"                             # "auto", "true", or "false"

[schema.default]
required = ["title"]

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

[schema.types.iteration.properties.status]
type = "enum"
values = ["planned", "in-progress", "completed", "superseded"]

See hyalo types --help for managing schemas from the CLI, and hyalo lint to validate your vault against them.

Saved views

Name a filter set once, recall it everywhere:

hyalo views set drafts --property status=draft
hyalo find --view drafts                          # recall
hyalo find --view drafts --tag rust               # extend with additional filters

Snapshot index

For workflows that run many queries in a short window (CI, automation, LLM tool loops):

hyalo create-index          # one scan → .hyalo-index
hyalo find --index ...      # instant queries, no disk scan
hyalo drop-index            # clean up

Mutations with --index patch the index in-place, keeping it current for subsequent queries.

Building from source

cargo build --release

Releasing

1. Bump the version in Cargo.toml
2. Commit: git commit -am "Bump version to X.Y.Z"
3. Create a GitHub release with tag vX.Y.Z

The release workflow handles cross-platform binaries, Homebrew, Scoop, and winget automatically.

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.