{"id":50225700,"url":"https://github.com/onebrain-ai/onebrain-cli","last_synced_at":"2026-06-28T12:00:39.844Z","repository":{"id":358849967,"uuid":"1243254064","full_name":"onebrain-ai/onebrain-cli","owner":"onebrain-ai","description":"Personal AI OS CLI for Obsidian — Rust rewrite of v2.3.3 (TypeScript/Bun)","archived":false,"fork":false,"pushed_at":"2026-06-26T08:59:54.000Z","size":1402,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-26T09:11:16.920Z","etag":null,"topics":["ai-agent","claude-code","cli","obsidian","onebrain","rust"],"latest_commit_sha":null,"homepage":"https://onebrain.run","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onebrain-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-19T07:15:15.000Z","updated_at":"2026-06-26T08:59:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/onebrain-ai/onebrain-cli","commit_stats":null,"previous_names":["onebrain-ai/onebrain-cli"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/onebrain-ai/onebrain-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onebrain-ai%2Fonebrain-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onebrain-ai%2Fonebrain-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onebrain-ai%2Fonebrain-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onebrain-ai%2Fonebrain-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onebrain-ai","download_url":"https://codeload.github.com/onebrain-ai/onebrain-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onebrain-ai%2Fonebrain-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34887328,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","claude-code","cli","obsidian","onebrain","rust"],"created_at":"2026-05-26T15:09:23.857Z","updated_at":"2026-06-28T12:00:39.838Z","avatar_url":"https://github.com/onebrain-ai.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- Banner pinned to a plugin-repo commit SHA (not the mutable `main` branch)\n     so a future asset restructure on onebrain-ai/onebrain can't silently\n     404 this image. Bump the SHA when refreshing the brand assets. --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/onebrain-ai/onebrain/200f113b27d3354f4a274c5d8aed1ba3b7c689cb/assets/header-dark.png\"\u003e\n    \u003cimg alt=\"OneBrain — Your AI Thinking Partner\" src=\"https://raw.githubusercontent.com/onebrain-ai/onebrain/200f113b27d3354f4a274c5d8aed1ba3b7c689cb/assets/header-light.png\" width=\"640\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cem\u003eYour AI Thinking Partner\u003c/em\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eThe local-first Rust CLI that powers the OneBrain personal AI OS for Obsidian.\u003c/strong\u003e\u003cbr\u003e\n  \u003csub\u003eVault scaffolding · plugin sync · scheduled skills · diagnostics · self-update — across Claude Code and Gemini CLI.\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/onebrain-ai/onebrain-cli/releases/latest\"\u003e\u003cimg alt=\"release\" src=\"https://img.shields.io/github/v/release/onebrain-ai/onebrain-cli?include_prereleases\u0026style=for-the-badge\u0026logo=rust\u0026color=cb3837\u0026label=release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@onebrain-ai/cli\"\u003e\u003cimg alt=\"npm\" src=\"https://img.shields.io/npm/v/@onebrain-ai/cli?style=for-the-badge\u0026logo=npm\u0026color=cb3837\u0026label=npm\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/onebrain-ai/onebrain-cli/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://img.shields.io/github/actions/workflow/status/onebrain-ai/onebrain-cli/ci.yml?branch=main\u0026style=for-the-badge\u0026logo=githubactions\u0026logoColor=white\u0026label=CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE-MIT\"\u003e\u003cimg alt=\"License: MIT OR Apache-2.0\" src=\"https://img.shields.io/badge/license-MIT_OR_Apache--2.0-7c3aed?style=for-the-badge\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://onebrain.run\"\u003e\u003cimg alt=\"Website\" src=\"https://img.shields.io/badge/onebrain.run-0a0a14?style=for-the-badge\u0026labelColor=ff2d92\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://x.com/onebrain_run\"\u003e\u003cimg alt=\"@onebrain_run on X\" src=\"https://img.shields.io/badge/follow-@onebrain__run-000000?style=for-the-badge\u0026logo=x\u0026logoColor=white\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/onebrain-ai/onebrain-cli/stargazers\"\u003e\u003cimg alt=\"GitHub stars\" src=\"https://img.shields.io/github/stars/onebrain-ai/onebrain-cli?style=for-the-badge\u0026color=00f3ff\u0026logo=github\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What is OneBrain CLI?\n\n**`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.\n\nThe 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.\n\n### Why OneBrain CLI\n\nPoint 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.**\n\n- **Same behavior on every harness \u0026 model** — Claude Code and Gemini CLI both run `onebrain \u003cnoun\u003e \u003cverb\u003e` and get identical output; switch harness without re-testing how your vault gets touched.\n- **Cross-platform, one command** — the *same* `onebrain \u003cnoun\u003e \u003cverb\u003e` runs on macOS, Linux, and Windows (Apple Silicon \u0026 Intel, x86_64 \u0026 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.\n- **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.\n- **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.\n- **Deterministic \u0026 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.\n- **Fast** — a ~5 MB binary returns in under 50 ms, skipping the latency of several tool calls for what's already one operation.\n- **Local-first** — your vault, your data, your AI memory; no cloud round-trip.\n- **Trustworthy install** — self-update verifies the binary's SHA-256 before swapping.\n\n## Status\n\n**v3.3.x — stable \u0026 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).\n\n## Quickstart\n\nFrom zero to a working OneBrain vault in three steps.\n\n```bash\n# 1. Install (macOS — Homebrew is the canonical channel)\nbrew install onebrain-ai/onebrain/onebrain\n\n# 2. Verify\nonebrain --version\n# → onebrain 3.3.12\n\n# 3. Scaffold a vault and let init pull the OneBrain plugin\nmkdir my-vault \u0026\u0026 cd my-vault\nonebrain init --yes\n```\n\nThen open the vault in your AI harness (Claude Code, Gemini CLI, …) and run `/onboarding` to finish setup.\n\n\u003e 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.\n\n## Install\n\n### Pre-built binaries\n\nPick the archive that matches your machine from the [latest release](https://github.com/onebrain-ai/onebrain-cli/releases/latest):\n\n| Platform | Architecture | File |\n|---|---|---|\n| [![macOS](https://img.shields.io/badge/macOS-000000?logo=apple\u0026logoColor=white\u0026style=flat)](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` |\n| [![macOS](https://img.shields.io/badge/macOS-000000?logo=apple\u0026logoColor=white\u0026style=flat)](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` |\n| [![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux\u0026logoColor=black\u0026style=flat)](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` |\n| [![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux\u0026logoColor=black\u0026style=flat)](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` |\n| [![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux\u0026logoColor=black\u0026style=flat)](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` |\n| [![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux\u0026logoColor=black\u0026style=flat)](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` |\n| [![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux\u0026logoColor=black\u0026style=flat)](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` |\n| [![Windows](https://img.shields.io/badge/Windows-0078D4?logo=windows\u0026logoColor=white\u0026style=flat)](https://github.com/onebrain-ai/onebrain-cli/releases/latest/download/onebrain-aarch64-pc-windows-msvc.zip) | ARM64 | `onebrain-aarch64-pc-windows-msvc.zip` |\n| [![Windows](https://img.shields.io/badge/Windows-0078D4?logo=windows\u0026logoColor=white\u0026style=flat)](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` |\n\n**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.\n\n```bash\n# Manual install (any Unix)\ncurl -L -o onebrain.tar.gz \\\n  https://github.com/onebrain-ai/onebrain-cli/releases/latest/download/onebrain-aarch64-apple-darwin.tar.gz\ntar xzf onebrain.tar.gz\nsudo install onebrain /usr/local/bin/\n```\n\n### Channels\n\n| Channel | Command | Notes |\n|---|---|---|\n| **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. |\n| **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. |\n| **Direct download** | table above | Pick your triple, drop the binary on `PATH`. |\n\nAll channels resolve to the same per-platform binary published in the matching GitHub Release.\n\n### Self-update\n\nAfter the initial install, refresh in place:\n\n```bash\nonebrain update                # prompt-and-confirm\nonebrain update --check        # dry-run (compare current vs latest)\nonebrain update --plan         # machine-readable JSON plan\n```\n\nOn 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.\n\n`onebrain update` auto-detects how the binary was installed and uses the right path so package-manager metadata never desyncs:\n\n- **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`.\n- **npm** (under `node_modules/@onebrain-ai/`) — runs `npm install -g @onebrain-ai/cli@\u003cversion\u003e` (added v3.2.17).\n- **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).\n\nAfter any path, a post-install guard runs `onebrain --version` from PATH and confirms the upgrade actually took effect.\n\n### Build from source\n\n```bash\ngit clone https://github.com/onebrain-ai/onebrain-cli\ncd onebrain-cli\ncargo build --release -p onebrain-cli\n# → target/release/onebrain\n```\n\nRequires 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.\n\n## Command surface\n\nv3.1 locks a singular-noun, two-level grammar — `onebrain \u003cnoun\u003e \u003cverb\u003e` — so every command path is predictable. Four root verbs handle the common flow; eight resource groups cluster the rest.\n\n```text\nonebrain\n├── init                       create / re-scaffold a vault (--yes · --force · --no-sync)\n├── update                     self-update the binary (--check · --plan)\n├── doctor [--fix]             9 health checks + auto-repair recipes\n├── serve                      local web UI + vault JSON API (--port · --host · --open)\n│\n├── vault       sync · current\n├── session     init\n├── checkpoint  stop · reset · orphans\n├── qmd         reindex · embed · status\n├── plugin      install · update · migrate\n├── schedule    register\n├── skill       run\n└── harness     detect\n```\n\n| Group | Verbs | Purpose |\n|---|---|---|\n| **Setup** | `init`, `plugin install`, `vault sync` | Scaffold `onebrain.yml` + PARA folders, register the plugin with the harness, overlay the latest plugin tarball. |\n| **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. |\n| **Search** | `qmd reindex · embed · status` | Rebuild the qmd index, re-embed documents, report index + embedding health. |\n| **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. |\n| **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. |\n| **Diagnostics** | `vault current`, `harness detect` | Report which mechanism resolved the active vault, and which AI harness is running. |\n\n\u003e 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.\n\n## Local web UI\n\n`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.\n\n```bash\nonebrain serve          # → http://127.0.0.1:6789/?token=\u003cTOKEN\u003e   (Ctrl-C to stop)\nonebrain serve --open   # …and open it in your browser\n```\n\nThe 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 \u003cdist\u003e` only to override the bundle (web UI development against a live daemon).\n\n- **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.\n- **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.\n- **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 \u0026 trust model](#security--trust-model).\n\n## Output modes\n\nInteractive commands default to human-readable `text`; pass a flag for structured output. Every structured payload is wrapped in the canonical `Envelope\u003cT\u003e`:\n\n```bash\nonebrain doctor                 # TTY: animated per-check report, colorized\nonebrain doctor --json          # { version, command, ok, vault, data, warnings, error }\nonebrain vault current --yaml   # same envelope, YAML\nonebrain qmd status --json | jq .data\n```\n\n- `--output {text,json,yaml,table,tsv}` — full matrix on every command; `--json` / `--yaml` are shorthands.\n- `--pretty` forces indented JSON even when stdout is piped; `--no-color` (or `NO_COLOR`) forces monochrome; `-q` drops info logs (errors still hit stderr).\n- 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.\n\n## Security \u0026 trust model\n\n`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.\n\nOn 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.\n\nEvery operation that overwrites, migrates, or removes a config file first copies it to `\u003cvault\u003e/.onebrain-backups/\u003cfile\u003e.\u003cYYYYMMDD-HHMMSS\u003e.bak` — the backup is a hard precondition, so the write is refused if the backup can't be made.\n\nReport security issues privately via the channel documented in [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n## Performance\n\nThe Rust rewrite milestone, measured against the v2.3.3 TypeScript/Bun CLI on the same hardware (Apple M1, macOS) running `onebrain doctor` warm:\n\n| Metric | v2.3.3 (Bun) | v3.0.0 (Rust) | Δ |\n|---|---|---|---|\n| Stripped binary size | 57.8 MB | 4.6 MB | **−92%** |\n| Private memory per invocation (peak) | ~21 MB | ~2 MB | **~10× less** |\n| Cold start | ~120 ms | \u003c 50 ms | **~2.5× faster** |\n| Warm `doctor` wall time | ~980 ms | ~890 ms | ~9% faster |\n| `update --check` (warm cache) | ~480 ms | ~10 ms | **~48× faster** |\n\nFigures 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\"`).\n\n## Architecture\n\nFour-crate Cargo workspace:\n\n```text\nonebrain-cli         Binary crate — clap dispatch over the v3.1 command tree\n  │\n  ├─ onebrain-fs     Vault walks · frontmatter parsing · plugin tarball overlay\n  │                  · init bootstrap · doctor checks · update install path · backups\n  │\n  ├─ onebrain-cache  Session token resolution · launchd plist generation\n  │                  · qmd status detection\n  │\n  └─ onebrain-core   Types · config parsing · path resolution (zero filesystem deps)\n```\n\nWorkspace 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.\n\nTest 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.\n\n\u003e **Design notes \u0026 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.\n\n## Roadmap\n\n\u003e 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).\n\n\u003e Major/minor only — see [CHANGELOG](CHANGELOG.md) for per-patch detail.\n\n### ✅ Shipped\n- [x] **v3.0** — Rust rewrite GA · 9-platform release pipeline · stable JSON contracts.\n- [x] **v3.1** — Consistency standard: locked `\u003cnoun\u003e \u003cverb\u003e` 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).\n\n### 🚧 Phase 1 · perceptual speed + skill alignment (v3.2–v3.7)\n- [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 \u003cm\u003e` + 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.\n- [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).\n- [ ] **v3.4** — RPC layer: stdio JSON-RPC 2.0 over a Unix socket with auto-spawn.\n- [ ] **v3.5** — Skill-speed rewrites (`/daily`, `/wrapup`) + `checkpoint recover`.\n- [ ] **v3.6** — Capture pipeline (`/capture`, `/bookmark`, `/braindump`).\n- [ ] **v3.7** — Inbox + tasks pipeline + `/consolidate`.\n\n### 📦 Phase 2 · bundles (v3.8–v3.11)\n- [ ] 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.\n\n### 🔭 Signal-driven (Tier 2/3)\n- [ ] Broader harness support — Codex, Qwen, and other agentic harnesses beyond today's Claude Code + Gemini CLI.\n- [ ] 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.\n\n### 🏁 v4.0 · breaking\n- [ ] Drop `vault.yml` dual-read (canonical `onebrain.yml` only) · retire the hidden v3.0 aliases.\n\n## Development\n\n```bash\nrustup default stable\ncargo install cargo-insta   # snapshot review\n\n# Full check (matches CI)\ncargo fmt --all -- --check\ncargo clippy --workspace --all-targets -- -D warnings\ncargo test --workspace\n\n# Snapshot workflow (insta)\ncargo test                  # tests fail on snapshot mismatch\ncargo insta review          # interactive approve/reject\n```\n\nThe 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).\n\nPR 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.\n\n## Related projects\n\n- **[onebrain-ai/onebrain](https://github.com/onebrain-ai/onebrain)** — OneBrain plugin (slash commands, skills, agents, hooks). Pairs with this CLI.\n- **[onebrain.run](https://onebrain.run)** — Marketing site, install one-liner, public roadmap.\n- **[OneBrain Cloud](https://onebrain.run) (waitlist)** — Hosted agent runtime + multi-device sync. Planning phase.\n\n## Contributing\n\nPRs 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`.\n\n## License\n\nLicensed 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).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonebrain-ai%2Fonebrain-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonebrain-ai%2Fonebrain-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonebrain-ai%2Fonebrain-cli/lists"}