Your AI Thinking Partner

The local-first Rust CLI that powers the OneBrain personal AI OS.
_{Vault scaffolding · plugin sync · scheduled skills · diagnostics · self-update — across Claude Code and Gemini CLI.}

onebrain is the local-first Rust binary at the heart of OneBrain — a personal AI operating system that lives in your local knowledge vault (plain Markdown files on your machine). It scaffolds new vaults, syncs the OneBrain plugin from GitHub, wires AI-harness hooks, runs scheduled skills through the OS scheduler, diagnoses vault health, and updates itself.

The CLI is cross-harness: paired with the OneBrain plugin (slash commands, skills, agents), it runs under Claude Code and Gemini CLI against the same vault contract.

Point an AI agent at a vault and it improvises — a different pile of grep / find / sed each time, re-derived every session. OneBrain CLI replaces that improvisation with one deterministic binary: same command, same typed result, on every harness and every OS, in under 50 ms. Full rationale: Why OneBrain CLI.

Status: v3.4.x — stable & production-ready, in active maintenance. GA since v3.0.0 (2026-05-22), shipping ~weekly themed minors. Direction in the Roadmap; per-release detail in CHANGELOG.md.

brew install onebrain-ai/onebrain/onebrain    # macOS — Homebrew is the canonical channel

On Linux/Windows: npm install -g @onebrain-ai/cli, or grab a pre-built binary for any of 9 targets (macOS · Linux incl. Raspberry Pi · Windows) from the latest release. After installing once, onebrain update refreshes in place, SHA-256-verified.

→ Full install guide — platform binary table, channels, self-update behavior, build from source, and the security & trust model.

From zero to a working OneBrain vault in three steps:

# 1. Verify the install
onebrain --version
# → onebrain 3.4.6

# 2. Scaffold a vault and let init pull the OneBrain plugin
mkdir my-vault && cd my-vault
onebrain init --yes

# 3. Open the vault in your AI harness (Claude Code, Gemini CLI, …)
#    and run /onboarding to finish setup.

init runs an embedded vault sync step that downloads the plugin tarball; if the network step fails, the scaffold (onebrain.yml, PARA folders, Stop hook, schedule preset) stays intact and the binary prints an onebrain vault sync retry hint. Pass --no-sync for offline / CI scaffolding.

• 🔍 Built-in native search — hybrid keyword + semantic search over your vault's Markdown, multilingual (Thai/CJK-aware keyword bigrams + ~100-language embeddings), zero external dependencies: no Node, no Python, no separate search binary to install. Semantic availability per platform: support matrix.
• 🔌 Built-in MCP server — onebrain mcp plugs OneBrain into Claude Code, Cursor, or any MCP client as a vault search engine — works standalone on any Markdown folder too. See docs/reference/mcp.md.
• Single static binary — one self-contained file, no runtime to install, cross-platform down to a Raspberry Pi Zero.
• Embedded web UI — onebrain serve hosts a local, token-gated file explorer + reading view + search panel + agent chat, with nothing extra to install. See docs/serve.md.
• Interactive model picker — a TUI over 6 embedding models (see Choosing an embedding model) to trade off speed, accuracy, and Thai support.
• Vault doctor + config migration — eleven health checks with --fix recipes, plus automatic onebrain.yml schema migration.
• Local scheduler — cron-style recurring skills (daily briefing, weekly review, reindex) via the OS scheduler, no cloud runner needed.

Five root verbs cover the common flow; eleven <noun> <verb> groups cluster the rest:

onebrain init | update | doctor | serve | mcp                # root verbs
onebrain <noun> <verb>                                       # vault · session · checkpoint · search
                                                             # · note · task · plugin · schedule
                                                             # · skill · harness

Interactive commands print human-readable text; every command also speaks structured --json / --yaml wrapped in the canonical Envelope.

→ Full command reference — the complete tree, every verb group, and the output-mode matrix.

Directional — themes are committed, timing flexes with the weekly-minor cadence (≈ one themed minor per week). The live public roadmap is at onebrain.run.

Major/minor only — see CHANGELOG for per-patch detail.

• v3.0 — Rust rewrite GA · 9-platform release pipeline · stable JSON contracts.
• v3.1 — Consistency standard: locked <noun> <verb> command tree · canonical Envelope output · vault.yml → onebrain.yml.
• v3.2 — note resource group · grouped doctor UX · skill run/harness run for headless skills.
• v3.3 — Daemon foundation: onebrain serve — embedded web UI over a token-gated vault JSON API.
• v3.4 — Native Search + Warm Daemon (in progress — completes the foundation): native Rust search replaces qmd (native engine + onebrain search verbs · native MCP server · 0 node/python deps, v3.4.5), plus a minimal warm daemon that owns the engine for mcp + search so the CLI works during a live session and multiple sessions coexist (v3.4.6), plus a Tier-2 cross-encoder reranker (onebrain-rerank-v1) for calibrated result relevance (v3.4.7) (milestone).

• v3.5 — "Desktop + Deeplinks": onebrain desktop native app + deeplinks + standalone webui file access (link/token/desktop verbs, vault_id, tickets) — the agent hands you a clickable, section-precise webui URL for any vault file; completely replaces Obsidian.
• v3.6 — Terminal sessions (mini-epic): run onebrain/claude/codex from a persistent term-server (survives daemon restart · reachable over Tailscale) — in both the WebUI and the v3.5 desktop shell. Builds on v3.5 desktop.

• v3.7 — Bootstrap + native verbs + skill optimization: startup / wrapup / daily / tasks → 1 call per ceremony; native settings-merge + vault migrations in plugin update; skill-body optimization pass (import content-verbs anchored ~v3.7.x).
• v3.8 (may not ship) — remaining cleanup: full daemon refactor of surfaces beyond mcp + search + daily-brief precompute — only if not already absorbed by v3.4 + v3.7.

• Bundle CLI (onebrain bundle install/list/info/lint/…) · four first-party bundles (dashboard · synthesis · research · scheduler) · core skills slimmed 32 → 18 · onebrain.run/bundles portal.

• Broader harness support — Codex, Qwen, and other agentic harnesses beyond today's Claude Code + Gemini CLI.
• Tiered memory + behavior tracking · proactive surfacing · daemon background synthesis · Avatar Mesh (one agent identity across machines) · Telegram / MCP gateway · OneBrain Studio · OneBrain Sync (cross-machine continuity for vault + memory + live session — harness-independent, end-to-end encrypted; sync + storage only, no hosted agent runtime).

• Drop vault.yml dual-read (canonical onebrain.yml only) · retire the hidden v3.0 aliases.

• onebrain-ai/onebrain — OneBrain plugin (slash commands, skills, agents, hooks). Pairs with this CLI.
• onebrain.run — Marketing site, install one-liner, public roadmap.
• OneBrain Sync (planned) — Cross-machine continuity for your vault, memory, and live session — harness-independent, end-to-end encrypted. Sync + storage only, no hosted agent runtime. Idea stage (replaces the dropped OneBrain Cloud).

PRs welcome — see CONTRIBUTING.md for dev setup, build + test commands, PR conventions, and the security-issue reporting channel. New contributors are encouraged to start with issues tagged good-first-issue; design notes and Rust patterns for orientation live in docs/.

Licensed under either of MIT or Apache-2.0 at your option — the permissive dual license used across OneBrain. Use it in open or closed source. Questions: [email protected].