External/beardrive
1
0
Fork 0
mirror of https://github.com/runbear-io/beardrive.git synced 2026-08-25 08:08:08 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: fix stale claims an audit found against the new CLI

Browse Source 
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
This commit is contained in:
Snow Lee
2026-07-28 18:06:05 -07:00
co-authored by Claude Opus 5
parent 62c241d3d6
commit 974d8aba2f
12 changed files with 69 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+1 -1
View File
File diff suppressed because one or more lines are too long
INSTALL_FOR_AGENTS.md
+1 -1
View File
@@ -192,7 +192,7 @@ claude plugin update beardrive@beardrive
```
Tell the user the plugin loads on their next session (current session keeps
working via the hooks from step 5). Other platforms: step 2 already covered
working via the hooks from step 4). Other platforms: init already covered
you — skip this.
## 6. Verify, then show the payoff
README.md
+20 -12
View File
@@ -28,7 +28,10 @@ agents actually read (and which hot-but-stale docs nobody maintains).
$ bdrive login https://your-hub # once per device — self-host a hub in ~10 min (docs/self-hosting.md)
$ cd ~/workspace && bdrive init
initialized /Users/snow/workspace
server: https://your-hub
project: workspace (p-7f3a2c91)
skill: installed for claude, codex
claude hooks registered → /Users/snow/.claude/settings.json
daemon: running (pid 55434, scan 3s, remote sync 10s)
```
@@ -138,7 +141,7 @@ hub's own storage, never something a syncing client points at directly:
|---|---|
| `bdrive login [server-url]` | Sign this device in (browser flow; `--device` forces the code flow, and shells without a TTY fall back to it automatically; default server beardrive.ai — the managed cloud, free personal workspace on signup; pass your hub URL to self-host). Switch hubs with `bdrive login <new-url>` |
| `bdrive logout` | Sign this device out — clear the saved token/account (`--forget` also drops the remembered server) |
| `bdrive init [folder]` | Create/connect a project and start syncing — the mount is always exactly the folder named. Interactive on a TTY, flags (`--name/--project/--only/--yes`) for scripts; registers agent sync hooks for detected platforms (`--no-hooks` skips); re-run to resume |
| `bdrive init [folder]` | Create/connect a project and start syncing — the mount is always exactly the folder named. Interactive on a TTY, flags (`--name/--project/--server/--only/--yes`) for scripts; installs the agent skill, registers agent sync hooks in each platform's user config (`--no-hooks` skips the hooks), prints the project link; re-run to resume |
| `bdrive stop [folder]` | Stop syncing, including agent sync hooks (files stay; `bdrive init` resumes) |
| `bdrive scope [add\|rm <dirs...>]` | Show or change which subfolders sync — edits the managed block of `.bdriveignore` rules that `init --only` writes, so no one hand-writes negation syntax. The daemon picks changes up in seconds; `rm` deletes nothing, locally or on the hub |
| `bdrive forget <path>...` | Stop syncing a path *and* remove it from the hub — adds the rule to `.bdriveignore` (which syncs) and prunes in one step. Local files are never touched, here or on teammates' devices |
@@ -162,7 +165,8 @@ Each mounted folder carries its own settings, so configuration travels with
the project:
- **`.bdrive/`** — the folder's settings directory: `config.json` holds the
**stable mount id** plus project/remote/include settings. Written by
**stable mount id** plus the project and remote (and, on older mounts, a
legacy `include` list — still honored, never written now). Written by
`bdrive init`, safe to hand-edit (a running daemon picks changes up
automatically). Never synced, and it holds no credentials (the session
token stays in `~/.bdrive`). Because everything is keyed by the mount id,
@@ -176,7 +180,7 @@ the project:
```jsonc
// .bdrive/config.json
{ "id": "m-5a10b713", "volume": "notes",
"remote": "https://drive.example.com/p/p-7f3a2c91", "include": ["/shared/"] }
"remote": "https://drive.example.com/p/p-7f3a2c91" }
```
Opting out is non-destructive: when a pattern starts matching an
@@ -376,8 +380,8 @@ makes agents fluent in all of this, and **`/beardrive:install`** sets a
project up conversationally: installs the CLI, signs in, creates or
connects a project (whole folder or a shared subfolder like `wiki/`),
offers to document the shared folder in CLAUDE.md so agents proactively
put shareable artifacts there, and registers project-level hooks in
`.claude/settings.json` — a blocking pull when you submit a prompt (Claude
put shareable artifacts there, and registers hooks in your user config
(`~/.claude/settings.json`, once per machine) — a blocking pull when you submit a prompt (Claude
reads fresh team files) and an async push after every file edit (artifacts
are on the server seconds after Claude writes them), for every teammate
whether or not they installed the plugin. The payoff: "write a report and
@@ -462,8 +466,8 @@ The plugin sets up everything at once:
- **`/beardrive:install`** — the full team setup, conversationally: CLI,
sign-in, project init (whole folder or a shared subfolder like `wiki/`),
a consent-gated agent orientation — a synced `AGENTS.md` mapping the
shared folder plus a repo-root pointer to it — and project-level sync
hooks registered in your user config.
shared folder plus a repo-root pointer to it — and sync hooks registered in
your user config, once per machine.
- **`/beardrive:init [folder] [--name/--project/--only]`** — just start
syncing a project; `/beardrive:status` diagnoses problems.
- **Turn-boundary sync hooks**, registered automatically in your user config
@@ -471,6 +475,10 @@ The plugin sets up everything at once:
pull when you send a message (Claude always reads fresh files) and an async
push when the turn ends. The hook no-ops instantly outside BearDrive
projects, which is what makes a machine-wide registration safe.
- **No permission gauntlet** — the plugin auto-approves beardrive's own setup
commands (`init`, `login`, `hooks`, `status`, `sync`, `url`) through a
`PreToolUse` hook, and only as bare invocations: anything with a shell
operator falls through to the normal prompt.
- **The `beardrive` skill** ([plugin/skills/beardrive](plugin/skills/beardrive/SKILL.md)),
covering init/stop/sync, sharing by URL, backends and credentials,
selective sync, and troubleshooting. Working in a clone of this repo
@@ -487,9 +495,9 @@ to set up BearDrive project <project-id> on <hub-url>. Ask me which folder to sy
```
The agent fetches [INSTALL_FOR_AGENTS.md](INSTALL_FOR_AGENTS.md) and follows
it: install the CLI, `bdrive skill install`, device-code sign-in, and
`bdrive init` — which also registers the sync hooks for every detected
agent platform. The instructions live at that URL rather than
it: install the CLI, then one `bdrive init` — which signs in (device code
when there is no browser), installs the skill, registers the sync hooks and
prints the project link. The instructions live at that URL rather than
inside the prompt so they never go stale in someone's copy — and the agent
handles every deviation (already installed, no Homebrew, sign-in, wrong
folder). The skill step is the durable part: `SKILL.md` is a cross-agent
@@ -529,8 +537,8 @@ working folder ←materialize/scan→ local volume store ←push/pull→ obj
as a conflict-copy file by the device that detects the overlap.
- A per-mount **daemon** scans the folder every few seconds (cheap
size+mtime check) and exchanges with the remote every ~10s — or
immediately after local edits. Tune with --scan-interval and
--remote-interval on `bdrive init`.
immediately after local edits. Tunable with --scan-interval and
--remote-interval on the daemon (defaults 3s / 10s).
### What beardrive does not sync
cmd/bdrive/init.go
+20 -1
View File
@@ -97,8 +97,27 @@ the folder was renamed or moved.`,
return err
} else if ok && proj.Remote != "" {
fmt.Printf("resuming %s (project %s)\n", folder, proj.Volume)
// --only on an existing mount narrows it in place: the scope is
// just .bdriveignore rules, so re-running init is a legitimate
// way to set them (and is what `bdrive scope` points at).
if cmd.Flags().Changed("only") {
fmt.Println("note: --only is ignored on resume — change what syncs with `bdrive scope add`/`rm`")
scope, err := cleanScopeDirs(only)
if err != nil {
return err
}
for _, dir := range scope {
if err := os.MkdirAll(filepath.Join(folder, filepath.FromSlash(dir)), 0o755); err != nil {
return err
}
}
if err := writeScopeDirs(folder, scope); err != nil {
return err
}
if len(scope) == 0 {
fmt.Println(" syncing: the whole folder (scope rules removed)")
} else {
fmt.Printf(" syncing: ./%s only (rules written to .bdriveignore)\n", strings.Join(scope, ", ./"))
}
}
installSkill(folder)
if !noHooks {
plugin/commands/init.md
+2 -2
View File
@@ -88,5 +88,5 @@ Follow these steps:
teammates connect (invite link → `bdrive init`; the scope rides
`.bdriveignore`, so it matches automatically).
For the full team setup (the AGENTS.md orientation + per-project sync
hooks in `.claude/settings.json`), suggest `/beardrive:install` instead.
For the full team setup (the AGENTS.md orientation + the sync hooks init
registers in `~/.claude/settings.json`), suggest `/beardrive:install` instead.
plugin/commands/install.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
description: Set up BearDrive for this project — install the CLI, sign in, create/connect a project, optionally document the shared folder in CLAUDE.md, and register project-level sync hooks so every teammate's files stay fresh during Claude sessions
description: Set up BearDrive for this project — install the CLI, sign in, create/connect a project, optionally document the shared folder in CLAUDE.md, and register machine-wide sync hooks in your agent's user config so files stay fresh in every session
argument-hint: "[project-name] [--only <dirs>]"
---
plugin/skills/beardrive/SKILL.md
+9 -8
View File
@@ -13,14 +13,15 @@ Use this skill whenever the user is working with the `bdrive` CLI: initializing
| Action | Command |
|---|---|
| Start syncing a project (create/connect; the front door) | `bdrive init [<folder>]` — interactive on a TTY; flags `--name <x>` / `--project <id>` / `--only <dirs>` (comma-separated) / `--yes` for scripts and agents. **The mount is always exactly the folder named** — `bdrive init wiki` makes ./wiki the project, whose contents are the project's contents (NEVER prompts without a TTY). Re-run to resume, including after the folder was renamed/moved. Runs the login flow first (against your hub URL) if the device has no session, and registers agent sync hooks for detected platforms (`--no-hooks` skips). |
| Start syncing a project (create/connect; the front door) | `bdrive init [<folder>]` — interactive on a TTY; flags `--name <x>` / `--project <id>` / `--server <hub-url>` (sign in there if this device has no session) / `--only <dirs>` (comma-separated) / `--yes` for scripts and agents. **The mount is always exactly the folder named** — `bdrive init wiki` makes ./wiki the project, whose contents are the project's contents (NEVER prompts without a TTY). Re-run to resume, including after the folder was renamed/moved. Runs the login flow first if the device has no session, installs the beardrive skill, registers agent sync hooks in each platform's USER config (`--no-hooks` skips the hooks only), and prints the project's hub link — one command, so setup costs one permission prompt. |
| Run the daemon in the foreground | `bdrive init -f` |
| Stop syncing | `bdrive stop [<folder>]` — pauses daemon *and* agent hooks; `bdrive init` resumes (`--forget` also unregisters) |
| Show/change which subfolders sync | `bdrive scope` / `bdrive scope add <dirs...>` / `bdrive scope rm <dirs...>` — edits the managed block of `.bdriveignore` rules that `init --only` writes (run from the mount root; never hand-write the negation syntax). The daemon applies it within seconds. `rm` stops syncing a folder but deletes nothing, locally or on the hub; removing the last entry is refused (that would flip to whole-folder sync — use `bdrive stop` instead) |
| One sync cycle now | `bdrive sync [<folder>]` — `--note <text>` stamps session context; `--prune` also removes from the hub whatever `.bdriveignore` now excludes (see below); `--hook <label>` is the Claude turn-start hook's plumbing (event JSON in, sync + note, gated-link formula out) |
| One sync cycle now | `bdrive sync [<folder>]` — `--note <text>` stamps session context; `--prune` also removes from the hub whatever `.bdriveignore` now excludes (refuses when `.bdriveignore` narrows the scope with `!` rules — see below); `--hook <label>` is the Claude turn-start hook's plumbing (event JSON in, sync + note, gated-link formula out) |
| Stop syncing a path **and** take it off the hub | `bdrive forget <path>...` — appends the rule to `.bdriveignore` (trailing `/` for a directory) and prunes in the same run. **Deletes nothing on disk**, here or on teammates' devices: they receive the rule with the removal and just stop tracking the path. Idempotent; a path outside the project errors and writes nothing. This is the ONLY way to clean up something that synced before you excluded it — plain `.bdriveignore` edits and `bdrive scope rm` leave the hub's copy in place |
| Register agent sync hooks (Claude Code, Codex, Gemini CLI, Hermes) | `bdrive hooks install` — merges pull/push/session-note/read-tracking hooks into each platform's USER config (`~/.claude/settings.json` and friends), once per machine, idempotently. `bdrive init` runs it automatically, so this is mainly for retries or `--agent`-targeting an undetected platform; bare `bdrive hooks` shows the status table; `bdrive hooks uninstall` removes only our entries |
| Install this skill on another agent (Codex, Gemini CLI, Hermes, Claude Code) | `bdrive skill install [<folder>]` — writes the binary's own copy of this skill to each detected platform's user-level skills dir (`~/.codex/skills/beardrive/SKILL.md` and friends), idempotently; bare `bdrive skill` shows the status table. Then the user asks that agent to set the folder up and it runs `init` + `hooks install` itself |
| Auto-approve setup commands (hook plumbing) | `bdrive hook-approve` — the beardrive plugin's `PreToolUse` hook calls it so `bdrive init/login/hooks/status/sync/url` need no permission prompt. Narrow by design: a shell operator anywhere in the command disqualifies it |
| Record agent file reads (hook plumbing) | `bdrive read-log [<folder>]` — parses a hook event JSON from stdin and queues in-project reads locally (native reads, grep matches, and files named in shell commands); drained to the hub on the next sync as agent traffic in the read heatmap. Registered automatically by `bdrive hooks install`; rarely run by hand |
| Mounts + daemon + pending state | `bdrive status [<folder>]` |
| Change history | `bdrive log [<folder>] [-p path] [-n N]` |
@@ -30,7 +31,7 @@ Use this skill whenever the user is working with the `bdrive` CLI: initializing
| Sign this device out | `bdrive logout` — clears the saved token + account (folders untouched); `--forget` also drops the remembered server. The token is only cleared locally: the hub still accepts it and there is no revoke yet. |
| Link a synced file for teammates | `bdrive url <file>` — prints the file's hub viewer URL (sign-in + project membership required; always the latest content). Computed locally, no network; `--sync` pushes first so a just-created file's link resolves immediately; no arg = the project home page. **After creating a shareable artifact (.md/.html/.csv/report/plan) in the shared folder, include this link in your reply** so teammates can open it. |
| Share a synced file publicly by URL | `bdrive share <file>` — prints a link anyone can open (HTML renders as a page, markdown rendered, PDFs inline; sandboxed; always the latest content; no account needed). `--expires 24h` for self-destructing links; `--list` / `--revoke <token-or-url>` to manage. Put generated reports in the shared folder, sync, then share. |
| Set up a project for a Claude Code team | `/beardrive:install` — installs the CLI, signs in, runs init (whole/shared folder), offers the two-file agent orientation (synced `<shared>/AGENTS.md` map + repo-root pointer), and registers agent sync hooks via `bdrive hooks install` (pull at turn start, push after edits, session-note stamping — for every detected platform, not just Claude) |
| Set up a project for a Claude Code team | `/beardrive:install` — installs the CLI, signs in, runs init (whole/shared folder), offers the two-file agent orientation (synced `<shared>/AGENTS.md` map + repo-root pointer), and registers agent sync hooks as part of `bdrive init` (pull at turn start, push after edits, session-note stamping — for every detected platform, not just Claude) |
| Per-file / folder change history in the web UI | History button (file versions or project feed) and per-folder ⌚ — each entry: account, time, device (name/OS/IP), view/download of that exact version. API: `GET /api/p/<id>/history?path=\|prefix=`, `GET /api/p/<id>/blob?sha=` |
| Web server: viewer + multi-project sync hub (read-only unless `--upload`) | `bdrive web [<folder> \| <storage-root-url>]` (serves cwd by default, `--addr :4173`; `-c config.json` reads remote/addr/upload/projects_db/database/auth settings from a file, explicit flags win; a storage root URL makes it a hub hosting many projects at `<root>/<project-id>/`, registry in `--projects-db` file, default `$BDRIVE_HOME/projects.json`; `--upload` lets browsers add files, client devices push, and projects be created — direct to storage via expiring presigned URLs on S3/GCS, relayed through the server for `file://`; `--upload-ttl 15m`; clients never see the remote URL or credentials; hub projects are walled by org membership — invite teammates from the web UI; the viewer has a ⌘K palette for fuzzy file search, project switching, and quick actions) |
@@ -68,7 +69,7 @@ Selective-sync semantics — important when advising users:
- Adding a pattern for an already-synced file makes this device **stop tracking it without deleting it anywhere** — the file stays on disk locally and on every other device. Deleting it locally after that does not propagate either.
- Because `.bdriveignore` syncs, adding a rule on one device applies it everywhere on the next cycle.
- Stopping tracking is not cleanup: **the hub keeps everything that synced before the rule existed**. `bdrive forget <path>` (or `bdrive sync --prune`) removes it from the hub while leaving every device's disk untouched. Reach for it whenever a user says a file "should not be up there".
- Prune reconciles against `.bdriveignore` **only**, never against this device's `include` scope — ignore rules are shared, the scope is per-device, and a narrow scope means "not on my disk", not "not on the hub". To clean up something the scope excludes (or a leak into it), `bdrive forget` it, which writes the exclusion into the shared rules first.
- Prune reconciles against `.bdriveignore`, which is **shared** — so it REFUSES outright when those rules narrow the scope with `!` (the managed `# bdrive scope` block that `init --only` / `bdrive scope` write): pruning there would delete everything outside the scope from the hub, for the whole team. Use `bdrive forget <path>` for a specific path — it writes the exclusion into the shared rules first. A *legacy* `include` list in `.bdrive/config.json` is the one per-device case, and prune never reconciles against it ("not on my disk", not "not on the hub").
- Nothing is destroyed by a prune: it is an ordinary journaled delete, so it shows in `bdrive log` and every past version stays in the hub's history. If a teammate edits the file in the window before they sync, their version wins and the path returns — run `--prune` again once they have synced.
---
@@ -155,9 +156,9 @@ project. Sync still happens without hooks: the daemon's loop is independent.
| Platform | Config it writes | Pull / push / read events |
|---|---|---|
| Claude Code (& Cowork) | `~/.claude/settings.json` | `UserPromptSubmit` (pull + injects the gated-link formula) / `PostToolUse` (Write\|Edit) / `PostToolUse` (Read\|Grep\|Bash) |
| Claude Code (& Cowork) | `~/.claude/settings.json` | `UserPromptSubmit` (pull + injects the gated-link formula) / `PostToolUse` (Write\|Edit\|MultiEdit) / `PostToolUse` (Read\|Grep\|Bash) |
| Codex (ChatGPT) | `~/.codex/hooks.json` | `UserPromptSubmit` / `PostToolUse` (apply_patch) / `PostToolUse` (read_file\|shell, best-effort); experimental and off by default (`[features] codex_hooks = true` in `~/.codex/config.toml`), and Codex asks once to trust the hook |
| Gemini CLI | `~/.gemini/settings.json` | `BeforeAgent` / `AfterTool` (write_file\|replace) / `AfterTool` (read_file\|read_many_files\|search\|shell) |
| Gemini CLI | `~/.gemini/settings.json` | `BeforeAgent` / `AfterTool` (write_file\|replace\|edit) / `AfterTool` (read_file\|read_many_files\|search_file_content\|run_shell_command) |
| Hermes | `~/.hermes/config.yaml` (per-user) | `pre_llm_call` / `post_tool_call` (write_file\|patch) / `post_tool_call` (read_file\|grep\|bash) |
Every platform pipes hook JSON with a `session_id`, so one hook command
@@ -202,8 +203,8 @@ Follow https://raw.githubusercontent.com/runbear-io/beardrive/main/INSTALL_FOR_A
to set up BearDrive project <project-id> on <hub-url>. Ask me which folder to sync.
```
The fetched instructions cover install, `bdrive skill install`, sign-in,
and `bdrive init --project` (which also registers the sync hooks). They use `login
The fetched instructions cover install and one `bdrive init --project
--server`, which signs in, installs the skill and registers the hooks. Sign-in uses `login
--device` because an agent is driving: a browser-callback sign-in is
invisible to it mid-turn, while the device flow yields a code and URL it can
hand back in chat. The hub's project home page renders this prompt with the
web/docs/src/content/docs/concepts/how-it-works.md
+2 -1
View File
@@ -54,7 +54,8 @@ overlap. Nothing is silently dropped.
A per-mount daemon scans the folder every few seconds and exchanges with the
remote every ~10s — or immediately after local edits. Tune with
`--scan-interval` and `--remote-interval` on `bdrive init`.
`--scan-interval` and `--remote-interval` on `bdrive daemon run` (init always
uses the defaults).
It re-reads `.bdrive/config.json` each tick. If that file vanishes because the
folder was moved, renamed, or deleted, the daemon **exits cleanly without
web/docs/src/content/docs/manual/install.md
+1 -1
View File
@@ -52,7 +52,7 @@ protocol is append-only journals plus blobs, which old clients read forward.
After upgrading a client, re-run `bdrive hooks install` to pick up hook
improvements and `bdrive skill install` to refresh the agent skill — both once
per machine, since both write to your user config. (Re-running `bdrive init` in a
synced folder refreshes the hooks, but not the skill.)
synced folder refreshes both.)
## Next
web/docs/src/content/docs/manual/setup-by-hand.md
+5 -1
View File
@@ -42,7 +42,10 @@ Once per project.
```console
$ cd ~/workspace && bdrive init
initialized /Users/snow/workspace
server: https://your-hub
project: workspace (p-7f3a2c91)
skill: installed for claude, codex
claude hooks registered → /Users/snow/.claude/settings.json
daemon: running (pid 55434, scan 3s, remote sync 10s)
```
@@ -58,7 +61,8 @@ Init writes `.bdrive/config.json`, seeds a starter `.bdriveignore`
(node_modules, build dirs, caches, `.env*`), starts the daemon, and prints the
project's hub link. It also installs the `beardrive` skill and registers the sync
hooks for any agent platform it detects — in that platform's **user** config, once
per machine, so nothing lands inside the project. `--no-hooks` skips both. Not
per machine, so nothing lands inside the project. `--no-hooks` skips the hooks
(the skill is installed either way). Not
signed in yet? It runs the login flow first.
:::tip[Working inside a repository]
web/docs/src/content/docs/reference/cli.md
+5 -4
View File
@@ -11,7 +11,7 @@ One binary, `bdrive` — the CLI, the sync daemon, and the web server.
|---|---|
| `bdrive login [server-url]` | Sign this device in. Browser flow; `--device` forces the code flow, and shells without a TTY (agents, CI, SSH) fall back to it automatically. Default server is beardrive.ai — the managed cloud, free personal workspace on signup; pass your hub URL to self-host. Switch hubs with `bdrive login <new-url>`. `--status` shows the current server and account |
| `bdrive logout` | Sign this device out — clear the saved token and account. `--forget` also drops the remembered server |
| `bdrive init [folder]` | Create or connect a project and start syncing — the mount is always exactly the folder named. Interactive on a TTY; flags (`--name`, `--project`, `--only`, `--yes`) for scripts. Also installs the agent skill, registers agent sync hooks for detected platforms (`--no-hooks` skips both), and prints the project's hub link. Re-run to resume |
| `bdrive init [folder]` | Create or connect a project and start syncing — the mount is always exactly the folder named. Interactive on a TTY; flags (`--name`, `--project`, `--server`, `--only`, `--yes`) for scripts. Also installs the agent skill, registers agent sync hooks for detected platforms (`--no-hooks` skips the hooks only), and prints the project's hub link. Re-run to resume |
| `bdrive stop [folder]` | Stop syncing — daemon and agent sync hooks both pause. Files stay on disk; `bdrive init` resumes |
| `bdrive scope [add\|rm <dirs...>]` | Show or change which subfolders sync — edits the managed block of `.bdriveignore` rules that `init --only` writes. Run from the mount root; the daemon picks changes up in seconds. `rm` stops syncing a folder but deletes nothing, locally or on the hub |
| `bdrive forget <path>...` | Stop syncing a path and remove it from the hub. Adds the rule to `.bdriveignore` (which syncs) and prunes in one step. Local files are never touched, here or on teammates' devices |
@@ -20,6 +20,7 @@ One binary, `bdrive` — the CLI, the sync daemon, and the web server.
| `bdrive sync [folder]` | Run one sync cycle now. Refuses folders this device never `init`ed and folders paused by `bdrive stop`. `--note <text>` stamps session context onto changes; `--note-ttl` (default 30m) bounds it. `--prune` also removes from the hub what `.bdriveignore` now excludes (files stay on disk everywhere). `--hook <label>` is agent-hook plumbing |
| `bdrive hooks [install\|uninstall]` | Register turn-boundary sync hooks in each detected agent platform's user config — once per machine, covering every folder. Run automatically by `bdrive init`; idempotent; `--agent` overrides detection. `uninstall` removes only BearDrive's own hook entries |
| `bdrive skill [install]` | Install the `beardrive` skill into detected agent platforms so the agent can do setup itself. Run automatically by `bdrive init`; idempotent; `--agent` overrides detection |
| `bdrive hook-approve` | Hook plumbing: answers the beardrive plugin's `PreToolUse` hook, auto-approving bare `bdrive init\|login\|hooks\|status\|sync\|url` so setup costs no permission prompts. Anything with a shell operator is left to the normal prompt |
| `bdrive read-log [folder]` | Hook plumbing: queue agent file reads for the hub's read heatmap. Registered by `bdrive hooks install` |
| `bdrive status [folder]` | Projects, daemon state, pending changes |
| `bdrive log [folder] [-p path] [-n N]` | Change history: account, device, time, file |
@@ -48,7 +49,7 @@ it never prompts without a TTY.
It runs the login flow first when there is no session, writes
`.bdrive/config.json`, seeds `.bdriveignore`, installs the `beardrive` skill and
registers agent sync hooks for every detected platform (Claude Code, Codex,
Gemini CLI, Hermes — `--no-hooks` skips both), starts sync, and prints the
Gemini CLI, Hermes — `--no-hooks` skips the hooks; the skill is installed either way), starts sync, and prints the
project's hub link. That is deliberate: one command means one permission prompt
for an agent, instead of four. Re-running it resumes — including after a folder
move.
@@ -58,8 +59,8 @@ friends), once per machine, so they cover every session in every folder; nothing
is written inside the project. See
[Skills and hooks in detail](/manual/skills-and-hooks/).
Daemon intervals are tunable here: `--scan-interval` (default 3s) and
`--remote-interval` (default 10s).
The daemon scans every 3s and talks to the hub every 10s; those intervals are
tunable on `bdrive daemon run`, not on init.
### `bdrive sync --note`
web/docs/src/content/docs/reference/project-files.md
+2 -1
View File
@@ -9,7 +9,8 @@ project.
## `.bdrive/`
The folder's settings directory. `config.json` holds the **stable mount id**
plus project, remote, and include settings.
plus the project and remote (older mounts may also carry a legacy `include`
list — still honored, never written now).
```jsonc
// .bdrive/config.json