Arrowhead CLI

Arrowhead (on GitHub) helps AI agents and command-line tools make sense of my Obsidian vault. It keeps Markdown notes indexed around the clock, combining fast full-text search, semantic vectors, graph analytics, time-based context, and metric queries under one CLI and MCP surface. Arrowhead is part of Plaintext Commons—my broader effort to build file-native thinking systems—with a public site forthcoming at plaintextcommons.org.

I built Arrowhead after years of bouncing between note-taking apps that locked away structure, links, and history. Plain text stayed the only constant, so the tool had to respect the folder as the source of truth. Arrowhead rewrites my earlier Synapse/Soma tools in Rust, trading a single-purpose search utility for a platform that feels at home on the command line, runs an always-on daemon, and speaks to AI agents like Claude, Codex, and OpenClaw.

How Arrowhead works

The CLI is the control surface, but the daemon does the real work. Indexing, search, and graph features depend on the daemon staying alive, so the typical flow is to initialize once and let the service run in the background.

• arrowhead (CLI) bootstraps Obsidian vaults or generic Markdown workspaces, manages the daemon (arrowhead index start/status/autostart), and provides search, workspace, context, metric, graph, and CRUD commands.
• arrowheadd (daemon) watches the vault, streams changes into the SQLite + FTS5 + vector indexes, and writes status/log files agents can inspect while it starts.
• MCP transports (stdio + authenticated HTTP) read from the same live index, with bearer or link-token auth, CIDR allowlists, and /health readiness checks for remote clients.
• Context commands surface day, week, month, changed-note, note, metric, and source views with evidence tiers and suggested pivots instead of only raw search hits.
• Hybrid ranking combines boolean operators, field filters, date filters, semantic similarity, and per-result explanations to show why a note surfaced.

The stack is intentionally pragmatic: Rust for speed and safety, SQLite for portability, fastembed embeddings stored with the index. arrowhead init seeds configuration, starts the daemon, and can register launchd/systemd autostart so indexing stays on even after reboot. Obsidian settings remain the preferred source of vault conventions, but non-Obsidian Markdown folders can use .arrowhead/workspace.toml for attachments, ignored folders, daily-note formats, and link style. Embeddings can also be disabled with --fts-only when a lighter full-text-only setup makes more sense.

Why it exists

Plaintext Commons treats files—not apps—as the durable layer for long-term knowledge work. Arrowhead is the search, discovery, and automation engine for that vision. It gives me confidence that vaults stay queryable, linkable, and agent-friendly without handing control to a silo. Whether I am debugging code, revisiting research threads, checking metric trends, or asking an agent to draft a change, Arrowhead keeps the raw materials close while letting assistants do meaningful work.

Arrowhead also absorbs the ingest and transcription ambitions that started with Soma. Analog note capture will migrate here—paired with a dedicated helper tool once the ergonomics are nailed—so a single system handles vault search and the bridges back to paper.

Get Arrowhead

Install it via my Homebrew tap:

brew tap totocaster/tap
brew install totocaster/tap/arrowhead

The source and release notes live on GitHub: totocaster/arrowhead.

My setup

As of November 2025, below is the setup I use for my digital note-taking.

• Claude Code (with Pro Plan) serves as my AI assistant and primary access point to the corpus. It uses the following tools:
  • Arrowhead CLI for search and discovery
  • Stamp CLI for standardized file names, following the Obsidian plugin conventions listed below
  • MarkEdit for editing and viewing text, since copying from Terminal apps can mess with formatting
  • Things URL Schema for creating (no read available) todos in my todo app
  • things-cli for traversing my todos
  • iMCP for access to my location and calendar (I seldom use this)
• Obsidian (with Sync) is my main human access point to the corpus. I use the following plugins:
  • Backlinks
  • Unique note creator for fleeting notes
  • File Cleaner
  • Linter
  • Local images
  • Media Extended for lectures and video transcripts
  • Metrics for nutrition, WHOOP data, medications, and other structured records
  • Natural Language Dates
  • Paste URL into selection
  • Quick Switcher++ as my human-accessible FTS

I prefer Claude Code over Codex when working with my notes (although the reverse is true for programming). I sometimes use Claude.app with Arrowhead MCP as well, but I find it a bit slower for tool calls (MCP tool calls vs. direct CLI usage). CLI agents are also better at picking up conventions since they don’t need to call the vault_conventions MCP tool every time; everything is laid out in AGENTS.md or CLAUDE.md at startup. You can see my CLAUDE.md here.