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: reorganize around the agent path, CLI becomes optional

Browse Source 
The sidebar and the homepage disagreed. index.md's "Where to start"
already led with connecting an agent, but the left rail read Install
(brew) -> Quickstart (bdrive login, bdrive init) -> ... -> Connect an
agent, three groups down. Anyone following the rail met the CLI first and
the skill last — the opposite of how the product is meant to be adopted.
The agent page was also filed under guides/, which this repo defines as
agent-workflow docs rather than setup.

Sidebar order is now the recommended path, and that path is agent-first:

  Start here          what it is -> set up with your agent -> your first hour
  Working with agents shared memory, artifacts, read heat, scoping
  Manual setup (opt)  install the CLI, set up by hand, skills and hooks
  Self-hosting / Reference / Concepts   unchanged

- start/setup (was guides/connect-an-agent): rewritten as the front door.
  Claude Code's plugin, then the one-paste for Codex/Gemini/Hermes, then
  what the agent just installed and how to check it.
- start/first-hour (new): the page that was missing — ask for a doc, get
  a link back, share it, a teammate's agent picks it up. What success
  looks like without a command you have to type.
- manual/skills-and-hooks (new): the mechanics lifted out of the old
  onboarding page — per-platform paths, hook events, idempotency,
  project-level vs per-user — so the Start page can stay conversational.
- manual/install and manual/setup-by-hand (were start/*): both now open
  by saying you probably don't need them, and link back to the agent path.
- index.md leads with "You don't install it — you ask your agent to";
  the CLI and hub sentence moves below it.

No `brew install` appears anywhere in Start here. Reference -> CLI stays
exactly where it was: the people most likely to self-host are CLI-first,
and burying it would read as condescending.

Three public URLs moved, so astro.config.mjs declares redirects. Static
builds emit meta-refresh only, so README carries copy-paste 301 rules for
the host — Firebase Hosting and a Cloud Storage + load balancer URL map.

Verified: 18 pages build, zero broken internal links across the built
output, all three redirects resolve. CLAUDE.md and the docs README record
the rule so this doesn't quietly revert.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Snow Lee
2026-07-19 20:52:20 -07:00
co-authored by Claude Opus 4.8
parent 25f890c03f
commit 8f239dfae4
13 changed files with 391 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files
web/docs/src/content/docs/guides/agent-artifacts.md
+1 -1
View File
@@ -32,7 +32,7 @@ With no argument, `bdrive url` gives the project home.
The sync hook installed by `bdrive hooks install` injects the project's
gated-link formula into the agent's context, so a connected agent appends
`path` [🔗](link) to every synced path it mentions — without being asked. See
[Connect an agent](/guides/connect-an-agent/).
[Set up with your agent](/start/setup/).
:::
## Public links, for everyone else
web/docs/src/content/docs/guides/connect-an-agent.md
-111
View File
@@ -1,111 +0,0 @@
---
title: Connect an agent
description: Wire Claude Code, Codex, Gemini CLI, or Hermes into a BearDrive folder so it reads fresh team files every turn and pushes its own artifacts automatically.
---
An agent connected to BearDrive pulls the team's latest files at the start of
every turn and pushes whatever it writes the moment it writes it. Your teammate's
agent sees it seconds later.
## The two pieces
Whatever agent you use, setup is the same two things.
**The skill** teaches the agent the `bdrive` CLI, so "share this file" or "what
changed?" just works without you explaining anything.
```sh
bdrive skill install
```
It writes `SKILL.md` — a cross-agent format — into every detected platform's
user-level skills directory: `~/.claude/skills/beardrive/`, `~/.codex/…`,
`~/.gemini/…`, `~/.hermes/…`.
**The hooks** are what make syncing automatic: a blocking pull when you send a
message, so the agent always reads fresh files, and an async push when the turn
ends.
```sh
bdrive hooks install
```
Both commands are idempotent and both detect the platform (override with
`--agent`). The hook no-ops instantly in folders without a `.bdrive/` project,
so registering it globally is safe.
:::caution[Don't skip the hooks]
This is the step people skip when they copy commands by hand, and it's the one
that makes the whole thing automatic. Without it you're back to running
`bdrive sync` yourself and the agent will read stale files.
:::
## Claude Code
Install the plugin:
```
/plugin marketplace add runbear-io/beardrive
/plugin install beardrive@beardrive
```
Then run **`/beardrive:install`**. It sets the project up conversationally:
installs the CLI, signs in, creates or connects a project (whole folder or a
subfolder like `wiki/`), offers to write the
[agent orientation files](/guides/shared-agent-memory/), and registers
project-level hooks in `.claude/settings.json`.
Those project-level hooks are the part that matters for teams: they're committed
with the repository, so **teammates sync whether or not they installed the
plugin**.
Also available:
- **`/beardrive:init [folder]`** — just start syncing. Takes `--name`,
`--project`, `--shared`.
- **`/beardrive:status`** — diagnose sync problems.
## Codex, Gemini CLI, Hermes
These agents ship no BearDrive knowledge, so setup is one paste. Start the agent
in the folder you want the files and give it:
```
Set up BearDrive in this folder.
1. If `bdrive` is missing, install it: brew install runbear-io/tap/beardrive
(no Homebrew? grab the release binary for this OS/arch from
https://github.com/runbear-io/beardrive/releases)
2. bdrive skill install # so you know the CLI next time
3. bdrive login --device https://your-hub # show me the code and the URL
4. bdrive init --project <project-id>
5. bdrive hooks install # don't skip this - it's what syncs every turn
Then tell me what got set up.
```
You copy one thing; the agent handles every deviation — already installed, no
Homebrew, sign-in, wrong folder.
Step 2 is the durable part. Once the skill is installed, the agent knows the CLI
from then on without being told.
:::tip
A project's home page in the web UI shows this same paste with your hub URL and
project id already filled in, plus a plain-terminal version. Send teammates
there rather than retyping it.
:::
## Check what's wired up
```sh
bdrive skill # what's installed on this machine
bdrive hooks # what's registered for this project
bdrive status # projects, daemon state, pending changes
```
Re-run `bdrive hooks install` once per project and `bdrive skill install` once
per machine after a CLI upgrade.
## Next
[Shared agent memory](/guides/shared-agent-memory/) — a freshly connected folder
is hundreds of opaque files to an agent. This is how you fix that.
web/docs/src/content/docs/guides/what-agents-read.md
+1 -1
View File
@@ -20,7 +20,7 @@ Hubs track it.
Sync replication never counts as a read, and neither does viewing a blob in
history. Only genuine consumption.
Agent reads require the hooks from [Connect an agent](/guides/connect-an-agent/).
Agent reads require the hooks from [Set up with your agent](/start/setup/).
Without them you'll see human traffic only.
## In the file browser
web/docs/src/content/docs/index.md
+15 -7
View File
@@ -7,8 +7,15 @@ BearDrive mounts any folder as a synced volume. Its contents stay synchronized
across all your devices and teammates through a BearDrive **hub**, every change
is tracked (who, when, on which device), and everything keeps working offline.
The CLI is `bdrive`. A hub is a `bdrive web` server you (or we) run on an object
store — clients sync through it over HTTPS and never touch the storage directly.
**You don't install it — you ask your agent to.** One command in Claude Code, or
one paste in Codex, Gemini CLI, or Hermes, and the folder is connected: your
agent reads the team's current files before it answers and pushes whatever it
writes when the turn ends.
Underneath there is a CLI called `bdrive` and a **hub** — a `bdrive web` server
you (or we) run on an object store, which clients sync through over HTTPS and
never touch the storage directly. You can drive all of it by hand, and most
people never do.
## What it's for
@@ -29,12 +36,13 @@ page.
## Where to start
- **[Connect an agent](/guides/connect-an-agent/)** — the point of the product.
Claude Code, Codex, Gemini CLI, or Hermes, reading and writing the shared
folder every turn.
- **[Quickstart](/start/quickstart/)** — sign in and start syncing a folder, if
you'd rather see the mechanics first.
- **[Set up with your agent](/start/setup/)** — the way in. One command in Claude
Code, one paste anywhere else, and the folder syncs from then on.
- **[Your first hour](/start/first-hour/)** — what a connected folder feels like:
ask for a doc, get a link back, teammates' agents pick it up.
- **[Run a hub](/self-hosting/run-a-hub/)** — self-host in about ten minutes.
- **[Manual setup](/manual/install/)** — the same result command by command, if
you'd rather see the moving parts.
## What you get
web/docs/src/content/docs/start/install.md → web/docs/src/content/docs/manual/install.md
+10 -3
View File
@@ -1,8 +1,14 @@
---
title: Install
description: Install the bdrive CLI with Homebrew, go install, or a release binary.
title: Install the CLI
description: Install the bdrive binary with Homebrew, go install, or a release tarball — for setting a folder up by hand, or for running a hub.
---
Most people never run this. [Setting up through your agent](/start/setup/)
installs the binary as its first step.
Install it yourself when you would rather drive the setup by hand, when you are
[running a hub](/self-hosting/run-a-hub/), or when a machine has no agent on it.
BearDrive ships one binary, `bdrive`. It is the CLI, the sync daemon, and the
web server. macOS and Linux.
@@ -49,4 +55,5 @@ agent skill.
## Next
[Quickstart](/start/quickstart/) — sign in and start syncing a folder.
[Set up by hand](/manual/setup-by-hand/) — sign in and start syncing a folder,
command by command.
web/docs/src/content/docs/start/quickstart.md → web/docs/src/content/docs/manual/setup-by-hand.md
+11 -5
View File
@@ -1,9 +1,15 @@
---
title: Quickstart
description: Sign a device in, start syncing a folder, and connect a second machine — the whole loop in a few minutes.
title: Set up by hand
description: The same setup an agent performs, run yourself — sign a device in, start syncing a folder, and connect a second machine.
---
Three steps: sign the device in, start syncing a folder, work normally.
This is [what your agent does for you](/start/setup/), one command at a time.
Useful on a machine with no agent, when scripting a fleet, or when you simply
want to see the moving parts.
Three steps: sign the device in, start syncing a folder, work normally. Then
[register the hooks](/manual/skills-and-hooks/) — that last step is what keeps
an agent's files fresh, and it is the one hand-setups forget.
## 1. Sign this device in
@@ -87,8 +93,8 @@ changes.
## Next
- [Connect an agent](/guides/connect-an-agent/) — wire Claude Code, Codex,
Gemini CLI, or Hermes into this folder. This is what BearDrive is for.
- [Skills and hooks in detail](/manual/skills-and-hooks/) — the two commands
that make an agent read fresh files every turn. Don't stop before this one.
- [Shared agent memory](/guides/shared-agent-memory/) — orient agents in the
folder so they know where to read and write.
- [Artifacts and links](/guides/agent-artifacts/) — internal links for
web/docs/src/content/docs/manual/skills-and-hooks.md
+87
View File
@@ -0,0 +1,87 @@
---
title: Skills and hooks in detail
description: What bdrive skill install and bdrive hooks install actually write — per-platform paths, hook events, idempotency, and when to re-run them.
---
Setting up through your agent runs these two commands for you. This is what
they do, for when you want to run them yourself, review what changed, or debug a
folder that isn't syncing.
## The skill
```sh
bdrive skill install # every detected platform
bdrive skill install --agent codex,hermes
bdrive skill # status table
```
It writes one `SKILL.md` — the cross-agent format — into each platform's
user-level skills directory:
| Platform | Path |
|---|---|
| Claude Code | `~/.claude/skills/beardrive/SKILL.md` |
| Codex | `~/.codex/skills/beardrive/SKILL.md` |
| Gemini CLI | `~/.gemini/skills/beardrive/SKILL.md` |
| Hermes | `~/.hermes/skills/beardrive/SKILL.md` |
Installs are user-level on purpose: the skill is about the CLI, not about one
folder, and a synced project folder should never carry it. The file is the
binary's own copy, so re-running after a CLI upgrade refreshes a stale one.
The Claude Code plugin ships the same skill, so `/plugin install
beardrive@beardrive` covers Claude without this command.
## The hooks
```sh
bdrive hooks install # every detected platform, this project
bdrive hooks install --agent claude,codex,gemini,hermes
bdrive hooks # status table
```
Each platform gets the same three hooks written into its own config format:
| Platform | Config it writes | Pull / push / read events |
|---|---|---|
| Claude Code | `<project>/.claude/settings.json` | `UserPromptSubmit` / `PostToolUse` (Write\|Edit) / `PostToolUse` (Read\|Grep\|Bash) |
| Codex | `<project>/.codex/hooks.json` | `UserPromptSubmit` / `PostToolUse` (apply_patch) / `PostToolUse` (read_file\|shell) |
| Gemini CLI | `<project>/.gemini/settings.json` | `BeforeAgent` / `AfterTool` (write_file\|replace) / `AfterTool` (read tools) |
| Hermes | `~/.hermes/config.yaml` (per user) | `pre_llm_call` / `post_tool_call` (write_file\|patch) / `post_tool_call` (read_file\|grep\|bash) |
Three hooks, three jobs:
- **Pull**, before the agent answers, so it never reads a stale file. This one
blocks — it is the only place BearDrive makes you wait, and it is why the
whole thing works.
- **Push**, after an edit, so teammates see the change within seconds rather
than whenever a daemon tick lands.
- **Read tracking**, on the agent's read-shaped tools, queued locally and sent
on the next sync. This is what fills [Insights](/guides/what-agents-read/).
Listing tools are deliberately excluded: seeing a filename is not reading it.
Every platform pipes hook JSON with a session id, so one hook command serves all
four, and changes are stamped with `<agent> session <id>` — visible in
`bdrive log` and the hub's history.
Codex asks once to trust the project's `.codex` layer. Answer yes, or run
`/hooks` inside Codex.
## Both are safe to re-run
Merging is idempotent and preserves hooks you already have. Each hook carries
its own marker, so a config written before a hook existed gains just the missing
one, and a registered hook's matcher is upgraded in place when coverage grows.
Re-run after a CLI upgrade: `bdrive hooks install` once per project, `bdrive
skill install` once per machine.
## Where they live matters
Claude Code, Codex, and Gemini CLI hooks are **project-level** — they ride the
repository, so a teammate who clones it syncs whether or not they installed
anything. Hermes hooks are **per-user** (`~/.hermes/config.yaml`), outside the
repo, so each person registers their own.
The hook is a fast no-op in any folder without a `.bdrive/` directory, which is
what makes registering it globally safe.
web/docs/src/content/docs/self-hosting/run-a-hub.md
+1 -1
View File
@@ -81,7 +81,7 @@ container platform works the same way.
link both creates their account and adds them to your org.
4. Connect agents: the project's home page shows one-paste setup for Claude
Code, Hermes, and Codex, with the hub URL and project id already filled in.
See [Connect an agent](/guides/connect-an-agent/).
See [Set up with your agent](/start/setup/).
## How the hub is organized
web/docs/src/content/docs/start/first-hour.md
+74
View File
@@ -0,0 +1,74 @@
---
title: Your first hour
description: What a connected folder feels like — ask an agent to write something, get a link back, share it outside the team, and watch a teammate's agent pick it up.
---
Setup is done and nothing looks different: the folder is still a folder, the
files are still files. The change shows up in what you stop doing.
## Ask for something to be written
Work normally. When the agent produces something worth keeping — a plan, a
findings doc, a runbook — ask it to put that in the shared folder:
> Write up what we decided in `wiki/decisions/pricing.md`.
The turn ends, the hook pushes, and the file is on the hub seconds later.
Nobody uploaded anything.
## The link you get back
A connected agent hands you a link to what it just wrote:
```
Saved to wiki/decisions/pricing.md 🔗
```
That is an **internal link** — it opens the file in the hub for anyone signed in
and in the project, and 404s for everyone else. Paste it in Slack without
thinking about it. You can also mint one yourself with `bdrive url <file>`.
For people outside the team, ask for a public one:
> Share that pricing doc with the customer.
The agent runs `bdrive share`, and you get a URL that renders the markdown as a
page — no account needed, revocable, and optionally self-destructing
(`--expires 24h`). [Artifacts and links](/guides/agent-artifacts/) covers both
kinds in depth.
## What a teammate sees
They set their own machine up the same way, in a folder of their choosing. From
then on, their agent starts every turn by pulling — so the pricing doc is simply
*there* the next time they ask about pricing. No one sends anyone a file.
That's the whole thesis: your agent knows what their agent knows.
## Now look at the hub
Open the project in a browser. Three things are worth a minute:
- **History** — every change, with the account, the time, the device, and the
agent session that made it. Any past version is one click away, and nothing is
ever deleted.
- **The file browser** — folders show read counts, so you can see which
documents your team's agents actually consume.
- **Insights** (hub admins and org owners) — reads against staleness. The
hot-but-stale quadrant is the knowledge everyone relies on and nobody
maintains. See [What agents read](/guides/what-agents-read/).
## From here on
Every turn, in every connected folder: pull before the agent answers, push after
it edits, stamped with the session that did it. You don't run a command and you
don't think about sync.
Two things repay the ten minutes they cost:
- **[Shared agent memory](/guides/shared-agent-memory/)** — a fresh folder is
hundreds of opaque files to an agent. A short `AGENTS.md` map fixes that, and
it syncs with everything else.
- **[Scoping the folder](/guides/scoping/)** — decide what agents can see. Sync
one subfolder rather than a whole repository, and opt files out with
`.bdriveignore`.
web/docs/src/content/docs/start/setup.md
+104
View File
@@ -0,0 +1,104 @@
---
title: Set up with your agent
description: You don't install BearDrive — you ask your agent to. One command in Claude Code, or one paste in Codex, Gemini CLI, or Hermes, and the folder syncs from then on.
---
You don't set BearDrive up. Your agent does.
Give it one instruction and it installs the CLI, signs this machine in, connects
the folder to a project, and registers the hooks that keep everything in sync —
then tells you what it did. You never open a config file.
## Claude Code and Cowork
Install the plugin once, in any session:
```
/plugin marketplace add runbear-io/beardrive
/plugin install beardrive@beardrive
```
Then, in the folder you want synced:
```
/beardrive:install
```
It walks you through it: creates or connects a project, asks whether to sync the
whole folder or a subfolder like `wiki/`, offers to write the
[agent orientation files](/guides/shared-agent-memory/), and registers the sync
hooks. It asks before anything it changes.
Cowork shares Claude Code's plugins, so installing it once covers both.
Two more commands come with the plugin: **`/beardrive:init`** to start syncing
without the full setup conversation, and **`/beardrive:status`** to diagnose a
sync problem.
:::tip[Project-level hooks reach the whole team]
`/beardrive:install` writes hooks into `.claude/settings.json`, which is
committed with the repository — so **teammates sync whether or not they
installed the plugin**.
:::
## Codex, Gemini CLI, and Hermes
These agents ship no BearDrive knowledge yet, so the instructions travel in the
message. Start the agent in the folder you want synced and paste:
```
Set up BearDrive in this folder.
1. If `bdrive` is missing, install it: brew install runbear-io/tap/beardrive
(no Homebrew? grab the release binary for this OS/arch from
https://github.com/runbear-io/beardrive/releases)
2. bdrive skill install # so you know the CLI next time
3. bdrive login --device https://your-hub # show me the code and the URL
4. bdrive init --project <project-id>
5. bdrive hooks install # don't skip this - it's what syncs every turn
Then tell me what got set up.
```
You copy one thing; the agent handles every deviation — already installed, no
Homebrew, browser sign-in, wrong folder.
Step 2 is the durable part. Once the skill is installed the agent knows the CLI
from then on, so "share this file" or "what changed?" work without you
explaining anything again.
:::tip[Don't retype this for teammates]
A project's home page in the hub shows this same paste with your hub URL and
project id already filled in. Send people there.
:::
## What your agent just set up
Two things, worth knowing by name:
- **The skill** — a `SKILL.md` in the agent's own skills directory, teaching it
the `bdrive` CLI. It is a cross-agent format, so one file works in Claude Code,
Codex, Gemini CLI, and Hermes.
- **The hooks** — a blocking pull when you send a message, so the agent always
reads the team's current files, and an async push when the turn ends, so what
it writes reaches everyone else within seconds.
The hooks are what make syncing automatic, and they are the step people skip
when they set up by hand. [Skills and hooks in detail](/manual/skills-and-hooks/)
covers what gets written where.
## Check it worked
Ask the agent — "is BearDrive set up in this folder?" — or look yourself:
```sh
bdrive status # projects, daemon state, pending changes
bdrive skill # which agents know the CLI on this machine
bdrive hooks # which agents sync this project automatically
```
## Next
[Your first hour](/start/first-hour/) — what the loop feels like once an agent is
connected.
Would rather drive it yourself? [Manual setup](/manual/install/) reaches the same
place, command by command.