feat: bdrive skill install + one-paste Codex/Hermes setup guide

The hub's install guide told Codex and Hermes users to run four CLI
commands by hand, and the one people skipped — `bdrive hooks install` —
is exactly the one that makes files sync at turn boundaries. Hand the
setup to the agent instead, the way the Claude tab hands it to the
plugin.

- `bdrive skill install` (internal/agentskills, plugin/embed.go): the
  binary now carries the beardrive skill and writes it to any agent that
  reads SKILL.md — ~/.{claude,codex,gemini,hermes}/skills/beardrive/.
  User-level on purpose: the skill is about the CLI, not one folder, and
  a synced project folder should never carry it. Idempotent; refreshes a
  stale copy after a CLI upgrade. Bare `bdrive skill` prints the table,
  mirroring `bdrive hooks`.
- Guide's Codex/Hermes tabs are now a single paste, no terminal: the
  prompt has the agent install the CLI, keep the skill, sign in, init,
  and register hooks. The commands ride inside the prompt because these
  agents ship no BearDrive knowledge (Claude's tab is terse only because
  the plugin carries it). `login --device` there — a browser-callback
  sign-in is invisible to an agent mid-turn, while the device flow gives
  it a code and URL to relay. Plain commands live on in an "or run it
  yourself" fallback.
- Docs realigned: README, SKILL.md, /beardrive:install, self-hosting.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Snow Lee
2026-07-19 14:30:06 -07:00
co-authored by Claude Opus 4.8
parent 9c7fc34ac8
commit 5c6099177b
17 changed files with 562 additions and 71 deletions
+123
View File
@@ -0,0 +1,123 @@
// Package agentskills installs the `beardrive` skill into the agent
// platforms a user works with, so their agent knows how to drive the CLI —
// including running `bdrive init` and `bdrive hooks install` itself, which is
// how hooks end up registered correctly without the user hand-copying
// commands.
//
// SKILL.md is a cross-agent standard: every supported platform discovers
// skills the same way — a directory per skill under the platform's config
// dir, holding a SKILL.md with `name` + `description` frontmatter:
//
// claude ~/.claude/skills/beardrive/SKILL.md
// codex ~/.codex/skills/beardrive/SKILL.md
// gemini ~/.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 skill
// is the binary's own copy (embedded at build time), so upgrading bdrive and
// re-running install refreshes it — writes are idempotent and report whether
// anything changed.
package agentskills
import (
"fmt"
"os"
"path/filepath"
"strings"
"github.com/runbear-io/beardrive/internal/store"
"github.com/runbear-io/beardrive/plugin"
)
// Agents is the supported platforms, in the order they are reported.
var Agents = []string{"claude", "codex", "gemini", "hermes"}
// Result reports what Install did for one agent platform.
type Result struct {
Agent string
Path string // SKILL.md written (or already current)
Changed bool // false = the installed copy already matched
}
// Path returns where an agent reads (or would read) the beardrive skill.
// Empty if the agent is unknown or the home directory is undiscoverable.
func Path(agent string) string {
if !supported(agent) {
return ""
}
home, err := os.UserHomeDir()
if err != nil || home == "" {
return ""
}
return filepath.Join(home, "."+agent, "skills", "beardrive", "SKILL.md")
}
// Detect reports which agent platforms are in use, judged — like
// agenthooks.Detect — by their config dirs existing in the project or the
// home directory.
func Detect(folder string) []string {
home, _ := os.UserHomeDir()
var found []string
for _, a := range Agents {
dir := "." + a
if dirExists(filepath.Join(folder, dir)) || (home != "" && dirExists(filepath.Join(home, dir))) {
found = append(found, a)
}
}
return found
}
// Installed reports whether an agent already has the current skill.
func Installed(agent string) bool {
path := Path(agent)
if path == "" {
return false
}
data, err := os.ReadFile(path)
return err == nil && string(data) == plugin.SkillMD
}
// Install writes the skill for the given agents ("auto"/empty = every
// detected platform). An outdated copy is overwritten — the file is ours.
func Install(folder string, agents []string) ([]Result, error) {
if len(agents) == 0 || (len(agents) == 1 && agents[0] == "auto") {
agents = Detect(folder)
}
var out []Result
for _, a := range agents {
if !supported(a) {
return out, fmt.Errorf("unknown agent %q (supported: %s)", a, strings.Join(Agents, ", "))
}
path := Path(a)
if path == "" {
return out, fmt.Errorf("%s: cannot locate home directory", a)
}
if Installed(a) {
out = append(out, Result{Agent: a, Path: path})
continue
}
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
return out, fmt.Errorf("%s: %w", a, err)
}
if err := store.WriteFileAtomic(path, []byte(plugin.SkillMD), 0o644); err != nil {
return out, fmt.Errorf("%s: %w", a, err)
}
out = append(out, Result{Agent: a, Path: path, Changed: true})
}
return out, nil
}
func supported(agent string) bool {
for _, a := range Agents {
if a == agent {
return true
}
}
return false
}
func dirExists(p string) bool {
fi, err := os.Stat(p)
return err == nil && fi.IsDir()
}
+100
View File
@@ -0,0 +1,100 @@
package agentskills
import (
"os"
"path/filepath"
"strings"
"testing"
"github.com/runbear-io/beardrive/plugin"
)
func TestDetect(t *testing.T) {
home := t.TempDir()
t.Setenv("HOME", home)
folder := t.TempDir()
if got := Detect(folder); len(got) != 0 {
t.Fatalf("nothing configured, detected %v", got)
}
os.MkdirAll(filepath.Join(folder, ".codex"), 0o755) // project-level
os.MkdirAll(filepath.Join(home, ".hermes"), 0o755) // user-level
if got := strings.Join(Detect(folder), ","); got != "codex,hermes" {
t.Fatalf("detected %q, want codex,hermes", got)
}
}
func TestInstallWritesSkillPerAgent(t *testing.T) {
home := t.TempDir()
t.Setenv("HOME", home)
results, err := Install(t.TempDir(), []string{"codex", "hermes"})
if err != nil {
t.Fatal(err)
}
if len(results) != 2 {
t.Fatalf("got %d results, want 2", len(results))
}
for _, r := range results {
if !r.Changed {
t.Fatalf("%s: fresh install reported unchanged", r.Agent)
}
data, err := os.ReadFile(r.Path)
if err != nil {
t.Fatalf("%s: %v", r.Agent, err)
}
if string(data) != plugin.SkillMD {
t.Fatalf("%s: written skill differs from the embedded one", r.Agent)
}
// Frontmatter is what makes a SKILL.md discoverable on every platform.
if !strings.HasPrefix(string(data), "---\nname: beardrive\n") {
t.Fatalf("%s: skill lacks name frontmatter", r.Agent)
}
}
if got := results[0].Path; got != filepath.Join(home, ".codex", "skills", "beardrive", "SKILL.md") {
t.Fatalf("codex path = %s", got)
}
// Re-running is idempotent...
results, err = Install(t.TempDir(), []string{"codex"})
if err != nil {
t.Fatal(err)
}
if results[0].Changed {
t.Fatal("second install reported a change")
}
if !Installed("codex") {
t.Fatal("Installed() false right after installing")
}
// ...but a stale copy is refreshed to the binary's own.
os.WriteFile(results[0].Path, []byte("--- old skill ---\n"), 0o644)
if Installed("codex") {
t.Fatal("Installed() true for a stale copy")
}
results, _ = Install(t.TempDir(), []string{"codex"})
if !results[0].Changed {
t.Fatal("stale copy was not refreshed")
}
}
func TestInstallAutoDetects(t *testing.T) {
home := t.TempDir()
t.Setenv("HOME", home)
os.MkdirAll(filepath.Join(home, ".claude"), 0o755)
results, err := Install(t.TempDir(), nil)
if err != nil {
t.Fatal(err)
}
if len(results) != 1 || results[0].Agent != "claude" {
t.Fatalf("auto-detect installed %v", results)
}
}
func TestInstallUnknownAgent(t *testing.T) {
t.Setenv("HOME", t.TempDir())
if _, err := Install(t.TempDir(), []string{"cursor"}); err == nil {
t.Fatal("unknown agent accepted")
}
}
+16 -6
View File
@@ -36,15 +36,25 @@ test("claude tab: plugin flow with real hub origin and project id, no raw CLI",
await expect(page.locator(".gd-body")).toContainText("Cowork");
});
test("codex tab keeps the full CLI flow", async ({ page }) => {
test("codex tab is one paste that hands the whole setup to the agent", async ({ page }) => {
await login(page);
const pid = await wikiId(page);
await page.click('.gd-tab[data-key="codex"]');
const codes = await page.$$eval(".gd-code code", (els) => els.map((e) => e.textContent).join("\n"));
expect(codes).toContain("brew install runbear-io/tap/beardrive");
expect(codes).toContain("bdrive login http://localhost:8993");
expect(codes).toContain(`bdrive init --project ${pid}`);
expect(codes).toContain("bdrive hooks install --agent codex");
await expect(page.locator(".gd-step")).toHaveCount(1);
const prompt = await page.$$eval(".gd-step .gd-code code", (els) =>
els.map((e) => e.textContent).join("\n"),
);
// Everything the agent needs rides inside the pasted prompt.
expect(prompt).toContain("brew install runbear-io/tap/beardrive");
expect(prompt).toContain("bdrive skill install --agent codex");
expect(prompt).toContain("bdrive login --device http://localhost:8993");
expect(prompt).toContain(`bdrive init --project ${pid}`);
expect(prompt).toContain("bdrive hooks install");
const manual = await page.$$eval(".gd-manual .gd-code code", (els) =>
els.map((e) => e.textContent).join("\n"),
);
expect(manual).toContain("bdrive login http://localhost:8993");
expect(manual).toContain("bdrive hooks install --agent codex");
await page.click('.gd-tab[data-key="claude"]');
});
@@ -10,9 +10,9 @@ import { copyText } from "../util";
interface GuideAgent {
key: string;
label: string;
hook?: string;
note?: string;
extra?: string;
agent?: string; // --agent value for `bdrive skill install`
skillDir?: string; // where that agent reads the skill from
extra?: string; // platform-specific caveat after the last step
}
const GUIDE_AGENTS: GuideAgent[] = [
@@ -20,19 +20,17 @@ const GUIDE_AGENTS: GuideAgent[] = [
{
key: "hermes",
label: "Hermes",
hook: "hermes",
note:
"Registers BearDrive's hooks in Hermes's config: pull before every turn, push after edits " +
"with a session note, and report file reads to Insights.",
agent: "hermes",
skillDir: "~/.hermes/skills/beardrive/",
},
{
key: "codex",
label: "Codex",
hook: "codex",
note: "Registers hooks in .codex/hooks.json.",
agent: "codex",
skillDir: "~/.codex/skills/beardrive/",
extra:
"Run /hooks inside Codex once to trust the project's .codex layer — after that every turn " +
"pulls, edits push automatically, and reads are reported to Insights.",
"Codex asks once to trust the project's .codex hooks layer — answer yes (or run /hooks) and " +
"from then on every turn pulls, edits push automatically, and reads are reported to Insights.",
},
];
@@ -71,35 +69,69 @@ function guideSteps(agent: GuideAgent, project: Project): Step[] {
];
}
const slug =
(project.name || "project").toLowerCase().replace(/[^a-z0-9._-]+/g, "-") || "project";
// Every other agent: one paste, no terminal — the same shape as the Claude
// tab. The commands ride INSIDE the prompt because these agents ship no
// BearDrive knowledge (Claude's tab can be terse only because the plugin
// carries it); the user still copies one thing, and the agent handles every
// deviation — already installed, no Homebrew, sign-in, wrong folder. Step 2
// of the prompt installs the skill, so every later session is conversational.
return [
{
title: "Install the BearDrive CLI",
desc: "One static binary. Homebrew on macOS and Linux; releases and `go install` also work.",
code: "brew install runbear-io/tap/beardrive",
},
{
title: "Sign in to this hub",
title: "Paste this into " + agent.label,
desc:
"Opens the browser once and stores a device token on this machine — the synced folder itself never holds credentials.",
code: "bdrive login " + origin,
},
{
title: "Mount the project into a local folder",
desc:
"Run it where you want the files. An existing folder works too — contents merge, and re-running init later (or after moving the folder) just resumes.",
code: "mkdir -p ~/" + slug + " && cd ~/" + slug + "\nbdrive init --project " + pid,
},
{
title: "Connect " + agent.label,
desc: agent.note,
code: "bdrive hooks install --agent " + agent.hook,
extra: agent.extra,
"Start " +
agent.label +
" in the folder where you want the files (an existing folder works too — contents merge), " +
"then paste:",
code: setupPrompt(agent, project),
extra:
"Approve the shell commands when it asks. It installs the CLI, signs this machine in (it " +
"hands you a code and a URL — the folder itself never holds credentials), mounts the " +
"project, and registers the sync hooks: pull before every turn, push after edits stamped " +
"with the session that made them, file reads into Insights. It also keeps the beardrive " +
"skill in " +
agent.skillDir +
", so from here on you can just ask." + (agent.extra ? " " + agent.extra : ""),
},
];
}
// The prompt the user pastes. Numbered, exact commands: an agent with no
// BearDrive knowledge follows this reliably, and knows what to do when a step
// is already done. `login --device` on purpose — a browser-callback sign-in is
// invisible to an agent mid-turn, while the device flow gives it a code and a
// URL it can hand back in chat.
function setupPrompt(agent: GuideAgent, project: Project): string {
return [
"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 --agent " + agent.agent + " # so you know the CLI next time",
"3. bdrive login --device " + window.location.origin + " # 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.",
].join("\n");
}
// For anyone who would rather not hand the setup to an agent. Skipping
// `hooks install` is the one thing that silently costs you turn-boundary
// syncing, so it is spelled out here.
function manualCommands(agent: GuideAgent, project: Project): string {
return (
"brew install runbear-io/tap/beardrive" +
"\nbdrive skill install --agent " +
agent.agent +
"\nbdrive login " +
window.location.origin +
"\nbdrive init --project " +
project.id +
"\nbdrive hooks install --agent " +
agent.agent
);
}
function savedAgent(): string {
try {
return localStorage.getItem("bdrive-guide-agent") || "claude";
@@ -113,6 +145,7 @@ export function ConnectGuide({ project }: { project: Project }) {
// A stale saved key (e.g. a tab that no longer exists) falls back to the
// first tab rather than rendering nothing.
const agent = GUIDE_AGENTS.find((a) => a.key === agentKey) || GUIDE_AGENTS[0];
const steps = guideSteps(agent, project);
return (
<div className="guide">
@@ -142,10 +175,11 @@ export function ConnectGuide({ project }: { project: Project }) {
))}
</div>
<div className="gd-body">
{guideSteps(agent, project).map((s, i) => (
<div className="gd-step" key={i}>
{steps.map((s, i) => (
<div className={"gd-step" + (steps.length > 1 ? "" : " gd-solo")} key={i}>
<div className="gd-step-head">
<span className="gd-num">{i + 1}</span>
{/* A lone step is not a sequence — no "1." badge for it. */}
{steps.length > 1 && <span className="gd-num">{i + 1}</span>}
<span className="gd-step-title">{s.title}</span>
</div>
{s.desc && <p className="gd-desc">{s.desc}</p>}
@@ -153,6 +187,16 @@ export function ConnectGuide({ project }: { project: Project }) {
{s.extra && <p className="gd-desc gd-extra">{s.extra}</p>}
</div>
))}
{agent.agent && (
<details className="gd-manual">
<summary>Or run it yourself</summary>
<p className="gd-desc">
Same result, in the folder you want the files. Don't skip the last line — the hooks
are what keep every turn starting from the latest state.
</p>
<GuideCode code={manualCommands(agent, project)} />
</details>
)}
<p className="gd-done">
That's it — the folder now syncs on its own. Every agent turn starts from the latest
state, edits appear here (and on every teammate's mount) within seconds, and what your
+6
View File
@@ -366,6 +366,12 @@ button, input, a.btn { font-family: inherit; }
.gd-code { position: relative; margin: 6px 0 6px 32px; padding: 10px 72px 10px 12px; background: var(--bg-raise); border: 1px solid var(--border); border-radius: var(--r-card); font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 12.5px; line-height: 1.6; color: var(--text); overflow-x: auto; white-space: pre; }
.gd-copy { position: absolute; top: 7px; right: 7px; font: inherit; font-family: inherit; font-size: 11px; font-weight: 600; padding: 3px 9px; border-radius: 6px; border: 1px solid var(--border-2); background: var(--bg-raise); color: var(--text-faint); cursor: pointer; box-shadow: -14px 0 12px -6px var(--bg-raise); }
.gd-copy:hover { color: var(--accent-bright); border-color: var(--accent-dim); }
/* A single unnumbered step has no badge to indent under. */
.gd-solo .gd-desc, .gd-solo .gd-code { margin-left: 0; }
.gd-manual { margin: 10px 0 0; }
.gd-manual > summary { display: inline-block; font-size: 12.5px; font-weight: 600; color: var(--text-faint); cursor: pointer; padding: 4px 0; }
.gd-manual > summary:hover { color: var(--text); }
.gd-manual .gd-desc, .gd-manual .gd-code { margin-left: 0; }
.gd-done { margin: 22px 0 8px; padding: 12px 14px; border: 1px solid var(--border); border-radius: var(--r-card); background: var(--bg-side); color: var(--text-faint); font-size: 13px; line-height: 1.5; }
.home-insights { margin-top: 30px; padding-top: 22px; border-top: 1px solid var(--border); }
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
+2 -2
View File
@@ -5,8 +5,8 @@
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>BearDrive</title>
<link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>&#128059;</text></svg>">
<script type="module" crossorigin src="/assets/index-QXAy2YSg.js"></script>
<link rel="stylesheet" crossorigin href="/assets/index-9WanC3kA.css">
<script type="module" crossorigin src="/assets/index-BaEUl3mb.js"></script>
<link rel="stylesheet" crossorigin href="/assets/index-BZPW21Cg.css">
</head>
<body>
<div id="root"></div>