beardrive/plugin/commands/install.md

description, argument-hint

description	argument-hint
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	[project-name] [--shared <dirs>]

Set up BearDrive for the current project, end to end. Work through these steps in order, telling the user what you're doing at each one.

1. Ensure the bdrive binary exists

Run command -v bdrive. If missing, install it:

• macOS/Linuxbrew: brew install runbear-io/tap/beardrive
• otherwise: go install github.com/runbear-io/beardrive/cmd/bdrive@latest If neither works, stop and tell the user how to install manually.

2. Sign in if needed

Run bdrive login --status. If there is no valid session, tell the user a browser window is coming, then sign in:

• Default: BearDrive Cloud. Run bare bdrive login — the browser opens beardrive.ai where they sign in or sign up. A brand-new account gets a free personal workspace automatically (no forms beyond signup itself); a pending team invite lands them in that team instead. No prior signup is needed — this step IS the signup.
• Self-hosted team: if the user says their team runs its own hub, ask for the URL and run bdrive login https://their-hub.

3. Initialize the project

If $ARGUMENTS gives a project name and/or --shared <dirs> (one or more, comma-separated or repeated), use them. Otherwise ask the user two questions (or infer from their request):

• Create a new project or connect an existing one? (bdrive init --name <name> creates-or-joins by name; bdrive init --project <p-id> connects by id.)
• Sync the whole folder, or only shared subfolders? Hard rule: never sync a repo root — inside a repo, knowledge always syncs as scoped subfolders via --shared. Whole-folder is only for a dedicated knowledge folder (an empty dir, a standalone vault) that is the mount itself. Don't ask open-endedly: scan the repo for existing knowledge folders (wiki/, docs/, notes/, handbook/, an Obsidian vault — markdown-heavy, not source code) and propose the candidates for confirmation, e.g. "I found ./wiki and ./docs — sync both?" (--shared wiki,docs puts them in one project — one membership, one permission set; folders needing different access go in separate projects).

One transport per folder. If the chosen folder is currently git-tracked, BearDrive and git would both write it — the silent-revert hazard. Get consent, then hand it off: git rm -r --cached <dir> and add <dir>/ to .gitignore; stage the change but let the user commit. (Full detection ladder — git, Obsidian, symlinks — in the beardrive skill's "Connecting knowledge tooling".)

Then run it non-interactively, e.g.:

bdrive init --name <project-name> --yes            # dedicated knowledge folder
bdrive init --name <project-name> --shared wiki       # in a repo: only ./wiki syncs
bdrive init --name <project-name> --shared wiki,docs  # several shared subfolders, one project

Re-running bdrive init --yes later is always safe: it resumes syncing (including after the folder was renamed or moved). To add or remove shared subfolders later, use bdrive scope add <dir> / bdrive scope rm <dir> from the mount root — never hand-edit .bdrive/config.json.

After init, tell git what's what: add .bdrive/ to .gitignore (per-machine state, never committed). .bdriveignore always syncs through BearDrive — including on --shared mounts — so the team shares rules automatically; committing it to git too is fine but optional.

4. Teach agents about the shared folder (ask first — never do this silently)

Two files with different jobs (full rationale: the beardrive skill's "Teaching agents the folder" section). Offer each as its own consent:

a. The folder's own map — <shared>/AGENTS.md (synced, team-wide). If the shared folder already has an AGENTS.md, read it and follow it — it is the team's source of truth; do not rewrite it while onboarding. If it has none and this user is creating the project, offer to draft one: explore the folder (top-level dirs, naming patterns, what's actually there) and write a short map — what each area is for, naming conventions, where agents should put their output, what not to touch. Keep it under a screen; it syncs to every member, so write it for the whole team, not this machine.

b. A root pointer in this repo (per machine, never synced). For a --shared mount inside a repo, append a short section to the repo root's AGENTS.md and/or CLAUDE.md — both if both exist; AGENTS.md is what Codex and Hermes read (Codex never discovers nested instruction files, and no platform knows the folder matters until told). Shape it like this (adapt the folder name; create the file if missing):

## Shared folder (BearDrive)

`wiki/` is the team's shared folder, synced via BearDrive — changes
propagate to everyone within seconds and every change is tracked (who,
when, which device). Read `wiki/AGENTS.md` before working there. Put
shareable artifacts — reports, notes, plans — in `wiki/` so the team
sees them, and whenever you mention a synced file's path, append its
gated link on an emoji: `` `wiki/<file>` `` [🔗](\<hub link>) —
`bdrive url wiki/<file>` prints the link (teammates sign in to view).
Never put secrets here (`bdrive share` mints fully public URLs).

Point at the synced AGENTS.md rather than duplicating its conventions — the pointer is for awareness and routing; the conventions live in the folder, stay current for everyone, and are versioned by the hub. For a standalone knowledge mount (dedicated folder, no enclosing repo) skip the pointer: AGENTS.md at the mount root is loaded natively by every platform.

5. Register agent sync hooks

Run bdrive hooks install in the project. It detects the agent platforms in use — Claude Code (.claude/), Codex (.codex/), Gemini CLI (.gemini/), Hermes (~/.hermes/) — and idempotently merges beardrive's sync hooks into each platform's own hook config, preserving any hooks already there. Project-level files (.claude/settings.json, .codex/hooks.json, .gemini/settings.json) ride the repo, so every teammate gets them — plugin or not, whatever agent they use; Hermes hooks are per-user (~/.hermes/config.yaml).

The registered hooks pull before every turn (the agent always reads the team's latest files), push right after edits (artifacts land on the server seconds after they're created — daemon or no daemon), and stamp every change with the agent session that made it (bdrive sync --note "<agent> session <id>" — visible in bdrive log and the hub's history views). A third hook (bdrive read-log) queues which files the agent read — via the native read tool, grep-style searches (the files the matches came from), or shell commands that name project files — so the hub's read heatmap can show admins what the team's agents actually consume. Reads are reported on the next sync, never from the hook itself. They are fast no-ops in folders without .bdrive/.

Tell the user which platforms got hooks (bdrive hooks shows the status table). If Codex is among them, mention they must run /hooks inside Codex once to trust the project's .codex layer. To register a platform that wasn't detected: bdrive hooks install --agent claude,codex,gemini,hermes. Heads-up before installing: Hermes hooks are PER-USER (~/.hermes/config.yaml, outside the repo) — mention that when it's among the targets, and skip it unless the user actually uses Hermes.

If the user mentions teammates on other agents (Codex, Gemini CLI, Hermes), tell them those teammates need no terminal either — they paste one prompt into their own agent (the hub's project home page shows it filled in):

Follow https://raw.githubusercontent.com/runbear-io/beardrive/main/INSTALL_FOR_AGENTS.md
to connect this folder to BearDrive project <project-id> on <hub-url>.

The fetched instructions run install, skill install (which leaves the beardrive skill in that agent's skills dir — ~/.codex/skills/beardrive/ and friends — so later sessions are conversational), device-code login, init, and hooks install. Handing teammates loose commands instead is how the hooks step gets skipped.

6. Verify and summarize

Run bdrive status and confirm the daemon is running and pending is 0. Then tell the user what was set up — and ALWAYS finish with the payoff: pick a representative file in the synced folder (the wiki's index/README, or an artifact you just generated), run bdrive url <file>, and hand the user the link with an invitation to open it — seeing their folder rendered in the browser is the moment the setup clicks. Teammate links require sign-in (safe by default); mention bdrive share <file> exists for fully public links when someone outside the hub needs it.