mirror of
https://github.com/runbear-io/beardrive.git
synced 2026-08-25 08:08:08 +02:00
4e34d03e14
* feat(hooks): register agent sync hooks per machine, not per project Agent platforms read hook config only from the directory a session starts in — never a parent, never a subfolder. Project-level hooks therefore fired only for sessions that happened to start at the mount, and, living inside a synced folder, they replicated one machine's agent config to the whole team (a second writer of a file bdrive already owns). Claude Code additionally ignores project hooks until the folder is trusted, so in practice they were often inert without any visible sign. Hooks now go to each platform's user config, once per machine, covering every session in every folder; the existing shell guard keeps them a no-op outside BearDrive projects. Install migrates away blocks older versions wrote into projects, and `bdrive hooks uninstall` removes ours while leaving foreign hooks untouched. Setup is also one command now. init absorbs the skill install, prints the hub link, and takes --server, so connecting to a named hub no longer needs a separate login; the runbook forbids preflight and command chaining, since each distinct command costs the user a permission prompt. For plugin users a PreToolUse hook auto-approves bdrive's own setup subcommands — narrowly: any shell operator in the command disqualifies it. Also drops --shared in favor of `init . --only wiki,docs`, which writes a managed block of .bdriveignore rules instead of a second scope mechanism. Because those rules sync, `sync --prune` now refuses on a scoped project rather than stripping everything outside the scope from the hub for everyone. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016aYntCWwdUhpzUfEk3ddyJ * docs: fix stale claims an audit found against the new CLI An audit of every doc surface against the code turned up claims that the user-scope hook move and the one-command init made false: project-level hooks "riding the repo", the Claude trust prompt, Codex's //hooks project layer, `--no-hooks` skipping the skill (it does not), prune reconciling against a per-device scope (it now refuses on a scoped project), and `--scan-interval`/`--remote-interval` documented as init flags when they only exist on `bdrive daemon run`. Also documents the surface added today — `--server`, `bdrive hooks uninstall`, and the plugin's PreToolUse auto-approval — refreshes the two sample `init` transcripts to the real output, and corrects hook matchers that had drifted from agenthooks.go. `bdrive scope` told users to narrow an existing mount with `bdrive init . --only <dirs>`, which resume then ignored — a dead end. Init now applies --only on resume, writing the scope block, so the advice works. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016aYntCWwdUhpzUfEk3ddyJ --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
93 lines
5.0 KiB
Markdown
93 lines
5.0 KiB
Markdown
---
|
|
description: Start syncing a project in this folder — create a new BearDrive project or connect an existing one, the whole folder or only some subfolders, and start the sync daemon
|
|
argument-hint: "[folder] [--name <project> | --project <p-id>] [--only <dirs>]"
|
|
---
|
|
|
|
Start syncing a project with BearDrive. Arguments: `$ARGUMENTS` (optional
|
|
folder, optional `--name`/`--project`/`--only`).
|
|
|
|
Follow these steps:
|
|
|
|
1. **Check the bdrive CLI is installed**: run `command -v bdrive`. If
|
|
missing, offer to install it (`brew install runbear-io/tap/beardrive`,
|
|
or `go install github.com/runbear-io/beardrive/cmd/bdrive@latest`) and
|
|
wait for the user's choice before installing.
|
|
|
|
2. **Sign in if needed**: run `bdrive login --status`. With no valid
|
|
session, tell the user a browser window is coming, then run bare
|
|
`bdrive login` (BearDrive Cloud — signing up auto-creates a free
|
|
personal workspace; a pending team invite routes them into that team).
|
|
If the user says their team runs its own hub, use
|
|
`bdrive login https://their-hub` instead. Either way it completes by
|
|
itself.
|
|
|
|
3. **Detect knowledge tooling** (skip if the folder already contains
|
|
`.bdrive/` — then just run `bdrive init --yes`; it resumes syncing,
|
|
including after a rename/move). Check, in order — first match wins,
|
|
ask if two match (full playbook: the beardrive skill's "Connecting
|
|
knowledge tooling" section):
|
|
|
|
- **gbrain** (`gbrain.yml`, or a gbrain MCP server / brain-first
|
|
CLAUDE.md block) → offer to sync the brain's shared subfolder as its
|
|
own project; never a brain root, and one enrichment owner per shared
|
|
folder (everyone else indexes read-only — see the skill).
|
|
- **OKF wiki** (markdown with OKF frontmatter) → offer: connect the
|
|
wiki dir by mounting it, or keep it PR-gated and create a new shared
|
|
folder.
|
|
- **Wiki-ish folder** (`docs`/`wiki`/`notes` full of markdown) → check
|
|
`git log -- <dir>`; dormant → recommend connecting it, active PR
|
|
traffic → recommend a new shared folder. Offer an OKF upgrade
|
|
(`openknowledge from`) after connecting, as a separate consent.
|
|
- **Nothing / empty** → offer a starting point in this order:
|
|
OKF (recommended), gbrain, blank, describe-it.
|
|
|
|
4. **Initialize** — two hard rules:
|
|
|
|
- **Never sync a repo root**: inside a repo, knowledge syncs as a
|
|
mounted subfolder (`bdrive init wiki`), or as the root narrowed
|
|
with `--only` when several folders belong to one project and the
|
|
same people should see all of them (folders needing different
|
|
access go in separate projects). A
|
|
dedicated knowledge folder (empty dir, standalone vault) may be the
|
|
mount itself.
|
|
- **One transport per folder**: a git-tracked dir must leave git
|
|
tracking before it syncs (`git rm -r --cached <dir>` + gitignore;
|
|
stage it, let the user commit). Offer one-way git snapshots if they
|
|
want a git record; `bdrive log -p <path>` covers history for most.
|
|
|
|
```sh
|
|
bdrive init --name <project> --yes # dedicated knowledge folder
|
|
bdrive init wiki --name <project> --yes # ./wiki is the project
|
|
bdrive init . --name <project> --only wiki,docs --yes # narrow this folder to those subfolders
|
|
```
|
|
|
|
5. **Confirm the sync hooks**: `bdrive init` registered them for every agent
|
|
platform it detected, in that platform's **user** config
|
|
(`~/.claude/settings.json`, `~/.codex/hooks.json`, `~/.gemini/settings.json`,
|
|
`~/.hermes/config.yaml`) — once per machine, covering every session in
|
|
every folder, with nothing written inside the project. Files pull at every
|
|
turn start, push after edits, every change is stamped with the agent
|
|
session that made it, and agent file reads feed the hub's read heatmap
|
|
(queued locally by `bdrive read-log`, reported on the next sync). Read
|
|
init's output and tell the user which platforms are covered. If Codex is
|
|
among them, pass on that its hooks are experimental and off by default —
|
|
`[features] codex_hooks = true` in `~/.codex/config.toml`, then trust the
|
|
hook when Codex asks. `bdrive hooks` shows the status table;
|
|
`bdrive hooks uninstall` removes them.
|
|
|
|
6. **Verify**: run `bdrive status <folder>` and confirm the daemon is
|
|
running and pending is 0. Summarize: project name/id, what syncs, and
|
|
that edits propagate to every team member within seconds. Offer the
|
|
two-file agent orientation, each part as its own consent (full flow:
|
|
the skill's "Teaching agents the folder" section): a synced
|
|
`<shared>/AGENTS.md` mapping the folder — draft it if this user is
|
|
creating the project, read and follow it if joining — and, for
|
|
mounts inside a repo, a short pointer to it in the repo
|
|
root's `AGENTS.md`/`CLAUDE.md` (the only file Codex loads, and what
|
|
makes any agent aware the folder matters). Then tell the user how
|
|
teammates connect (invite link → `bdrive init`; the scope rides
|
|
`.bdriveignore`, so it matches automatically).
|
|
|
|
For the full team setup (the AGENTS.md orientation + the sync hooks init
|
|
registers in `~/.claude/settings.json`), suggest `/beardrive:install` instead.
|