https://github.com/onebrain-ai/onebrain-cli
Personal AI OS CLI for Obsidian — Rust rewrite of v2.3.3 (TypeScript/Bun)
https://github.com/onebrain-ai/onebrain-cli
ai-agent claude-code cli obsidian onebrain rust
Last synced: 1 day ago
JSON representation
Personal AI OS CLI for Obsidian — Rust rewrite of v2.3.3 (TypeScript/Bun)
- Host: GitHub
- URL: https://github.com/onebrain-ai/onebrain-cli
- Owner: onebrain-ai
- License: apache-2.0
- Created: 2026-05-19T07:15:15.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-26T08:59:54.000Z (4 days ago)
- Last Synced: 2026-06-26T09:11:16.920Z (4 days ago)
- Topics: ai-agent, claude-code, cli, obsidian, onebrain, rust
- Language: Rust
- Homepage: https://onebrain.run
- Size: 1.34 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
Your AI Thinking Partner
The local-first Rust CLI that powers the OneBrain personal AI OS for Obsidian.
Vault scaffolding · plugin sync · scheduled skills · diagnostics · self-update — across Claude Code and Gemini CLI.
---
## What is OneBrain CLI?
**`onebrain`** is the local-first Rust binary at the heart of [OneBrain](https://onebrain.run) — a personal AI operating system that lives in your Obsidian vault. 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](https://github.com/onebrain-ai/onebrain) (slash commands, skills, agents), it runs under Claude Code and Gemini CLI against the same vault contract.
### Why OneBrain CLI
Point an AI agent at a vault and it improvises — a different pile of `grep` / `ls` / `find` / `sed` each time, behaving differently on each harness and re-derived every session: slow, token-hungry, non-portable, sometimes wrong. **OneBrain CLI replaces that improvisation with one deterministic binary.**
- **Same behavior on every harness & model** — Claude Code and Gemini CLI both run `onebrain ` and get identical output; switch harness without re-testing how your vault gets touched.
- **Cross-platform, one command** — the *same* `onebrain ` runs on macOS, Linux, and Windows (Apple Silicon & Intel, x86_64 & ARM down to a Pi Zero) and returns the *same* typed result on every OS. Write a hook or script once; it behaves identically everywhere — no per-platform shell quirks (`sed`/`find`/path-separator differences) to work around.
- **Yours to extend, no waiting** — add a capability the harness/LLM doesn't have yet and every agent can use it immediately; they only learn the command, not implement the feature.
- **No re-deriving solved workflows** — search, capture, consolidate, checkpoint live in the binary, so the agent calls one command instead of re-reasoning the recipe each session. Fewer tokens, no drift.
- **Deterministic & safe** — a typed command with a frozen `Envelope` can't half-finish or quietly differ like an ad-hoc `rm` / `sed` pipeline. Same input → same output, scriptable by hooks.
- **Fast** — a ~5 MB binary returns in under 50 ms, skipping the latency of several tool calls for what's already one operation.
- **Local-first** — your vault, your data, your AI memory; no cloud round-trip.
- **Trustworthy install** — self-update verifies the binary's SHA-256 before swapping.
## Status
**v3.3.x — stable & production-ready, in active maintenance.** GA since v3.0.0 (2026-05-22), shipping ~weekly themed minors. The v3.3 line landed the daemon foundation — `onebrain serve` hosts a local web UI (embedded in the binary) over a token-gated vault JSON API. Version history + direction in the [Roadmap](#roadmap); full detail in [CHANGELOG.md](CHANGELOG.md).
## Quickstart
From zero to a working OneBrain vault in three steps.
```bash
# 1. Install (macOS — Homebrew is the canonical channel)
brew install onebrain-ai/onebrain/onebrain
# 2. Verify
onebrain --version
# → onebrain 3.3.12
# 3. Scaffold a vault and let init pull the OneBrain plugin
mkdir my-vault && cd my-vault
onebrain init --yes
```
Then open the vault in your AI harness (Claude Code, Gemini CLI, …) and run `/onboarding` to finish setup.
> On Linux/Windows, grab the matching binary from the [latest release](https://github.com/onebrain-ai/onebrain-cli/releases/latest) (table below) or `npm install -g @onebrain-ai/cli`. `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.
## Install
### Pre-built binaries
Pick the archive that matches your machine from the [latest release](https://github.com/onebrain-ai/onebrain-cli/releases/latest):
| Platform | Architecture | File |
|---|---|---|
| [](https://github.com/onebrain-ai/onebrain-cli/releases/latest/download/onebrain-aarch64-apple-darwin.tar.gz) | Apple Silicon (M1–M5) | `onebrain-aarch64-apple-darwin.tar.gz` |
| [](https://github.com/onebrain-ai/onebrain-cli/releases/latest/download/onebrain-x86_64-apple-darwin.tar.gz) | Intel | `onebrain-x86_64-apple-darwin.tar.gz` |
| [](https://github.com/onebrain-ai/onebrain-cli/releases/latest/download/onebrain-aarch64-unknown-linux-gnu.tar.gz) | ARM64 (glibc · Pi 3/4/5 64-bit OS · Pi Zero 2 W) | `onebrain-aarch64-unknown-linux-gnu.tar.gz` |
| [](https://github.com/onebrain-ai/onebrain-cli/releases/latest/download/onebrain-armv7-unknown-linux-gnueabihf.tar.gz) | ARMv7 32-bit (Pi 2 v1.1+ · Pi 3/4/5 32-bit OS) | `onebrain-armv7-unknown-linux-gnueabihf.tar.gz` |
| [](https://github.com/onebrain-ai/onebrain-cli/releases/latest/download/onebrain-arm-unknown-linux-gnueabihf.tar.gz) | ARMv6 32-bit (Pi 1 · Pi Zero · Pi Zero W) | `onebrain-arm-unknown-linux-gnueabihf.tar.gz` |
| [](https://github.com/onebrain-ai/onebrain-cli/releases/latest/download/onebrain-x86_64-unknown-linux-gnu.tar.gz) | x86_64 (glibc) | `onebrain-x86_64-unknown-linux-gnu.tar.gz` |
| [](https://github.com/onebrain-ai/onebrain-cli/releases/latest/download/onebrain-x86_64-unknown-linux-musl.tar.gz) | x86_64 (musl / Alpine / static) | `onebrain-x86_64-unknown-linux-musl.tar.gz` |
| [](https://github.com/onebrain-ai/onebrain-cli/releases/latest/download/onebrain-aarch64-pc-windows-msvc.zip) | ARM64 | `onebrain-aarch64-pc-windows-msvc.zip` |
| [](https://github.com/onebrain-ai/onebrain-cli/releases/latest/download/onebrain-x86_64-pc-windows-msvc.zip) | x86_64 | `onebrain-x86_64-pc-windows-msvc.zip` |
**Click a platform badge to download that file from the latest release.** Each archive ships with a matching `.sha256` for manual verification. Filenames use canonical Rust target triples, so installer scripts can parse them unmodified.
```bash
# Manual install (any Unix)
curl -L -o onebrain.tar.gz \
https://github.com/onebrain-ai/onebrain-cli/releases/latest/download/onebrain-aarch64-apple-darwin.tar.gz
tar xzf onebrain.tar.gz
sudo install onebrain /usr/local/bin/
```
### Channels
| Channel | Command | Notes |
|---|---|---|
| **Homebrew** (macOS, canonical) | `brew install onebrain-ai/onebrain/onebrain` | Formula at [`onebrain-ai/homebrew-onebrain`](https://github.com/onebrain-ai/homebrew-onebrain), bumped on every tag. |
| **npm wrapper** | `npm install -g @onebrain-ai/cli` | Source at [`npm-wrapper/`](npm-wrapper/); CI publishes on every stable tag via npm Trusted Publishers + `--provenance`. Verifies the release SHA-256 before extracting. |
| **Direct download** | table above | Pick your triple, drop the binary on `PATH`. |
All channels resolve to the same per-platform binary published in the matching GitHub Release.
### Self-update
After the initial install, refresh in place:
```bash
onebrain update # prompt-and-confirm
onebrain update --check # dry-run (compare current vs latest)
onebrain update --plan # machine-readable JSON plan
```
On an interactive terminal, `update` shows a framed `🧠 OneBrain Update` header and a braille spinner while it checks for (and downloads) a new version; piped / `--json` / `--plan` runs stay plain.
`onebrain update` auto-detects how the binary was installed and uses the right path so package-manager metadata never desyncs:
- **Homebrew** (binary under the Cellar) — refreshes the `onebrain-ai/onebrain` tap, then runs `brew upgrade onebrain`. The tap refresh (added v3.2.17) means a freshly-released version applies in one `onebrain update` with no manual `brew update`.
- **npm** (under `node_modules/@onebrain-ai/`) — runs `npm install -g @onebrain-ai/cli@` (added v3.2.17).
- **Direct download** (a plain file we own) — resolves the current target triple, downloads the matching GitHub Release tarball over HTTPS (rustls TLS), verifies its SHA-256, and atomically swaps the running binary (Unix single-rename; Windows rustup-style two-step with rollback on failure).
After any path, a post-install guard runs `onebrain --version` from PATH and confirms the upgrade actually took effect.
### Build from source
```bash
git clone https://github.com/onebrain-ai/onebrain-cli
cd onebrain-cli
cargo build --release -p onebrain-cli
# → target/release/onebrain
```
Requires a recent stable Rust toolchain (`rustup default stable`). The only `unsafe` in OneBrain crates is a single `libc::getuid()` call (the launchd plist UID); the workspace otherwise builds cleanly on Linux, macOS, and Windows.
## Command surface
v3.1 locks a singular-noun, two-level grammar — `onebrain ` — so every command path is predictable. Four root verbs handle the common flow; eight resource groups cluster the rest.
```text
onebrain
├── init create / re-scaffold a vault (--yes · --force · --no-sync)
├── update self-update the binary (--check · --plan)
├── doctor [--fix] 9 health checks + auto-repair recipes
├── serve local web UI + vault JSON API (--port · --host · --open)
│
├── vault sync · current
├── session init
├── checkpoint stop · reset · orphans
├── qmd reindex · embed · status
├── plugin install · update · migrate
├── schedule register
├── skill run
└── harness detect
```
| Group | Verbs | Purpose |
|---|---|---|
| **Setup** | `init`, `plugin install`, `vault sync` | Scaffold `onebrain.yml` + PARA folders, register the plugin with the harness, overlay the latest plugin tarball. |
| **Runtime** (hook protocol) | `session init`, `checkpoint stop · reset · orphans`, `qmd reindex` | Called by the harness `SessionStart` / `Stop` / `PostToolUse` hooks. Emit hard-wired JSON; banner suppressed for clean machine stdio. |
| **Search** | `qmd reindex · embed · status` | Rebuild the qmd index, re-embed documents, report index + embedding health. |
| **Web UI** | `serve` | Host the binary-embedded web UI + token-gated vault JSON API on `127.0.0.1:6789` — file explorer, reading view, qmd search, agent chat; `--open` launches the browser. |
| **Maintenance** | `doctor [--fix]`, `plugin update · migrate`, `schedule register` | Nine read-only checks + `--fix` recipes, self-update the binary + rewrite hooks + rebind launchd plists, compile the `onebrain.yml schedule:` block into OS scheduler artifacts. |
| **Diagnostics** | `vault current`, `harness detect` | Report which mechanism resolved the active vault, and which AI harness is running. |
> The tree shape is **locked for v3.2+** — 200+ verbs beyond the working set above are stubbed with a stable `E_NOT_IMPLEMENTED` (exit 72) so the grammar can't drift while features land. Hidden v3.0 flat aliases (`session-init`, `qmd-reindex`, `register-hooks`, …) still dispatch, printing a one-time migration notice (silence with `ONEBRAIN_QUIET_MIGRATION=1`); they're removed no earlier than v4.
## Local web UI
`onebrain serve` starts a local, token-gated HTTP server that hosts the **OneBrain web UI** — a file explorer, a reading view (markdown, code, PDF, Office docs, images, audio/video, Jupyter notebooks), a qmd-backed search panel, and an agent chat — over a small vault JSON API.
```bash
onebrain serve # → http://127.0.0.1:6789/?token= (Ctrl-C to stop)
onebrain serve --open # …and open it in your browser
```
The web UI is **embedded in the binary** — a release `onebrain` ships the latest build and `serve` mounts it at `/`, so there's nothing extra to install. Pass `--dir ` only to override the bundle (web UI development against a live daemon).
- **Token-gated** — every request (and the SPA shell itself) needs the per-session token printed in the URL, sent as the `X-OneBrain-Token` header, a `?token=` query param, or an `HttpOnly` cookie.
- **Loopback by default** (`127.0.0.1:6789`). `--host 0.0.0.0` self-hosts remotely but serves plain HTTP — put a TLS tunnel/proxy (Cloudflare Tunnel, Tailscale Serve, Caddy) in front; `serve` warns loudly when you bind beyond loopback.
- **Hardened surface** — confined to the vault (tooling dirs like `.git`/`.claude` are refused), script-carrying files forced to download, a strict CSP, and the agent subprocess never inherits the daemon token. See [Security & trust model](#security--trust-model).
## Output modes
Interactive commands default to human-readable `text`; pass a flag for structured output. Every structured payload is wrapped in the canonical `Envelope`:
```bash
onebrain doctor # TTY: animated per-check report, colorized
onebrain doctor --json # { version, command, ok, vault, data, warnings, error }
onebrain vault current --yaml # same envelope, YAML
onebrain qmd status --json | jq .data
```
- `--output {text,json,yaml,table,tsv}` — full matrix on every command; `--json` / `--yaml` are shorthands.
- `--pretty` forces indented JSON even when stdout is piped; `--no-color` (or `NO_COLOR`) forces monochrome; `-q` drops info logs (errors still hit stderr).
- Output auto-adapts: piped/CI invocations drop color and the startup banner, so machine consumers get clean bytes with no flags. Closed-pipe writes (`onebrain qmd reindex | head`) exit `0`, not a panic.
## Security & trust model
`onebrain update` authenticates downloaded binaries two ways: **GitHub's TLS chain** (rustls validation, no opt-out) secures the transport, and since v3.1.4 a **SHA-256 check** verifies the archive against its published `.sha256` *before* the swap — an unverifiable or mismatched asset is refused and the live binary is left untouched. The npm wrapper runs the same SHA-256 check before extracting. What's *not* yet done is cosign/signature verification: the checksum is an integrity check, not an authenticity one (an attacker who controls the serving origin could serve a matching archive + `.sha256` pair), so signing is tracked as a follow-up.
On networks running a corporate MITM proxy, the trust boundary becomes whatever certificate the proxy presents. If that matters to your threat model, verify the published `.sha256` files manually after each update.
Every operation that overwrites, migrates, or removes a config file first copies it to `/.onebrain-backups/..bak` — the backup is a hard precondition, so the write is refused if the backup can't be made.
Report security issues privately via the channel documented in [`CONTRIBUTING.md`](CONTRIBUTING.md).
## Performance
The Rust rewrite milestone, measured against the v2.3.3 TypeScript/Bun CLI on the same hardware (Apple M1, macOS) running `onebrain doctor` warm:
| Metric | v2.3.3 (Bun) | v3.0.0 (Rust) | Δ |
|---|---|---|---|
| Stripped binary size | 57.8 MB | 4.6 MB | **−92%** |
| Private memory per invocation (peak) | ~21 MB | ~2 MB | **~10× less** |
| Cold start | ~120 ms | < 50 ms | **~2.5× faster** |
| Warm `doctor` wall time | ~980 ms | ~890 ms | ~9% faster |
| `update --check` (warm cache) | ~480 ms | ~10 ms | **~48× faster** |
Figures from the v3.0.0 rewrite-milestone dogfood; the binary has since grown to ~5 MB as v3.1 added the branded banner and `qmd status`/`embed`. Reproduce the size with the release profile (`lto = "thin"`, `strip = "symbols"`, `codegen-units = 1`, `panic = "abort"`).
## Architecture
Four-crate Cargo workspace:
```text
onebrain-cli Binary crate — clap dispatch over the v3.1 command tree
│
├─ onebrain-fs Vault walks · frontmatter parsing · plugin tarball overlay
│ · init bootstrap · doctor checks · update install path · backups
│
├─ onebrain-cache Session token resolution · launchd plist generation
│ · qmd status detection
│
└─ onebrain-core Types · config parsing · path resolution (zero filesystem deps)
```
Workspace inheritance keeps `[workspace.package]` fields (`version`, `edition`, `license`, `repository`) in one place. The root sets `publish = false`; all four crates inherit it via `publish.workspace = true` — only the compiled binary ships.
Test pyramid (3 layers since v3.1.0): inline unit + `assert_cmd` integration + `insta` snapshots, 900+ tests passing. CI gates on `fmt` + `clippy -D warnings` + a 3-platform matrix (Ubuntu, macOS, Windows). The v2.x Bun golden-master parity layer was retired in v3.1.0; the v3.1 `Envelope` shape and the output-format matrix now own the canonical-contract role.
> **Design notes & Rust patterns** → [`docs/`](docs/): an architecture deep-dive, decision records (ADRs), and a guided tour of the idiomatic Rust this codebase uses — written for contributors, people studying the source, and Rust learners.
## Roadmap
> Directional — themes are committed, timing flexes with the weekly-minor cadence (≈ one themed minor per week). The live public roadmap is at [onebrain.run](https://onebrain.run).
> Major/minor only — see [CHANGELOG](CHANGELOG.md) for per-patch detail.
### ✅ Shipped
- [x] **v3.0** — Rust rewrite GA · 9-platform release pipeline · stable JSON contracts.
- [x] **v3.1** — Consistency standard: locked ` ` command tree · canonical `Envelope` output · branded banner · `vault.yml → onebrain.yml` · `qmd embed` · `schedule register` `onebrain.yml` support · self-update hardening (SHA-256 verify + Homebrew-aware).
### 🚧 Phase 1 · perceptual speed + skill alignment (v3.2–v3.7)
- [x] **v3.2** — `note` resource group (11 verbs) · grouped `doctor` UX with braille spinner + one-pass `--fix` · animated `onebrain update` · `skill run --harness {claude,gemini}` + `--model ` + headless startup-skip handshake + in-place spinner · `harness run [PROMPT] --mode {with-context,ad-hoc}` for ad-hoc prompts through claude / gemini (reads stdin when omitted) · auto-checkpoint hook fix (`CLAUDE_CODE_SESSION_ID` top-priority token + anchored `last_ts` so the time threshold actually fires) · `--vault` accepted everywhere.
- [x] **v3.3** — Daemon foundation: `onebrain serve` — a local **web UI embedded in the binary** over a token-gated vault JSON API (file explorer · reading view · qmd-backed search · agent chat), on a security-hardened surface (whole-surface token gate · vault path confinement · CSP + forced-attachment · agent env isolation).
- [ ] **v3.4** — RPC layer: stdio JSON-RPC 2.0 over a Unix socket with auto-spawn.
- [ ] **v3.5** — Skill-speed rewrites (`/daily`, `/wrapup`) + `checkpoint recover`.
- [ ] **v3.6** — Capture pipeline (`/capture`, `/bookmark`, `/braindump`).
- [ ] **v3.7** — Inbox + tasks pipeline + `/consolidate`.
### 📦 Phase 2 · bundles (v3.8–v3.11)
- [ ] 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.
### 🔭 Signal-driven (Tier 2/3)
- [ ] 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 Cloud](https://onebrain.run) federation.
### 🏁 v4.0 · breaking
- [ ] Drop `vault.yml` dual-read (canonical `onebrain.yml` only) · retire the hidden v3.0 aliases.
## Development
```bash
rustup default stable
cargo install cargo-insta # snapshot review
# Full check (matches CI)
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
# Snapshot workflow (insta)
cargo test # tests fail on snapshot mismatch
cargo insta review # interactive approve/reject
```
The output contract is pinned by `crates/onebrain-cli/tests/v31_envelope_snapshots.rs` (Envelope shape · insta), `tests/output_format_matrix.rs` (default / `--json` / `--json --pretty` / `--yaml`), `tests/user_flows.rs` (new-user / hook-consumer / error-recovery), and `tests/v31_integration.rs` (v3.0 alias migration).
PR conventions: feature branch → git worktree → 3-round parallel review (correctness / behavior / security) → squash-merge with `--delete-branch`. English-only repo. One version bump per PR. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full workflow.
## Related projects
- **[onebrain-ai/onebrain](https://github.com/onebrain-ai/onebrain)** — OneBrain plugin (slash commands, skills, agents, hooks). Pairs with this CLI.
- **[onebrain.run](https://onebrain.run)** — Marketing site, install one-liner, public roadmap.
- **[OneBrain Cloud](https://onebrain.run) (waitlist)** — Hosted agent runtime + multi-device sync. Planning phase.
## Contributing
PRs welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup, build + test commands, PR conventions, and the security-issue reporting channel. New contributors are encouraged to start with issues tagged `good-first-issue`.
## License
Licensed under either of [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE) at your option — the permissive dual license used across OneBrain. Use it in open or closed source. Questions: [hello@onebrain.run](mailto:hello@onebrain.run).