# hyalo
**A structured CLI for markdown knowledgebases — built for humans and AI agents.**
If you maintain an [Obsidian](https://obsidian.md/) 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](https://x.com/karpathy/status/1908527375407042770): 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
| **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 all `[[wikilinks]]` and `[markdown](links)` across the vault |
| **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.** 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](https://claude.ai/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
```sh
# 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
```sh
hyalo init --claude
```
This installs two [skills](https://docs.anthropic.com/en/docs/claude-code/skills) and a [rule](https://docs.anthropic.com/en/docs/claude-code/settings#rules) 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)
```sh
brew tap ractive/tap
brew install ractive/tap/hyalo
```
### Scoop (Windows)
```powershell
scoop bucket add hyalo https://github.com/ractive/scoop-hyalo
scoop install hyalo
```
### winget (Windows)
```powershell
winget install ractive.hyalo
```
### Cargo (from crates.io)
```sh
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](https://github.com/ractive/hyalo/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.
```toml
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:
```sh
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):
```sh
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
```sh
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](.github/workflows/release.yml) 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](AI_NOTICE) for details.
> "Hyalo" — from [hyaloclastite](https://en.wikipedia.org/wiki/Hyaloclastite) — is a volcanic glass, just like obsidian.