@byterover/claude-plugin 1.0.0

package/LICENSE

@@ -0,0 +1,44 @@
+Elastic License 2.0 (ELv2)
+
+Acceptance
+By using the software, you agree to all of the terms and conditions below.
+
+Copyright License
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject to the limitations and conditions below.
+
+Limitations
+You may not provide the software to third parties as a hosted or managed service, where the service provides users with access to any substantial set of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality in the software, and you may not remove or obscure any functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software. Any use of the licensor's trademarks is subject to applicable law.
+
+Patents
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case subject to the limitations and conditions in this license. This license does not cover any patent claims that you cause to be infringed by modifications or additions to the software. If you or your company make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+Notices
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the software prominent notices stating that you have modified the software.
+
+No Other Rights
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+Termination
+If you use the software in violation of these terms, such use is not licensed, and your licenses will automatically terminate. If the licensor provides you with a notice of your violation, and you cease all violation of this license no later than 30 days after you receive that notice, your licenses will be reinstated retroactively. However, if you violate these terms after such reinstatement, any additional violation of these terms will cause your licenses to terminate automatically and permanently.
+
+No Liability
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.
+
+Definitions
+The _licensor_ is the entity offering these terms, and the _software_ is the software the licensor makes available under these terms, including any portion of it.
+
+_you_ refers to the individual or entity agreeing to these terms.
+
+_your company_ is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. _control_ means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+_your licenses_ are all the licenses granted to you for the software under these terms.
+
+_use_ means anything you do with the software requiring one of your licenses.
+
+_trademark_ means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,304 @@
+# @byterover/claude-bridge
+
+Native bridge between [ByteRover](https://www.byterover.dev) and [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Enriches Claude's auto-memory with ByteRover's full multi-tier retrieval — BM25 search, importance scoring, performance correlation, and LLM synthesis — giving Claude persistent, cross-referenced context that improves over time.
+
+## Table of contents
+
+- [What it does](#what-it-does)
+- [Prerequisites](#prerequisites)
+- [Quick start](#quick-start)
+- [Commands](#commands)
+- [How it works](#how-it-works)
+- [Development](#development)
+- [Project structure](#project-structure)
+- [License](#license)
+
+## What it does
+
+Claude Code has a built-in auto-memory system — it saves observations across sessions as flat markdown files. ByteRover has a richer context tree with multi-tier retrieval: BM25 text search, importance/recency scoring, maturity tier boosting, performance-memory correlation, and LLM-powered synthesis. This bridge connects the two:
+
+1. **Ingesting memories** — when Claude's extraction agent writes a memory file, a hook fires and sends the content to `brv curate`, which enriches it with tags, keywords, scoring metadata, and stores it in the context tree
+2. **Syncing context** — after each turn, a hook queries ByteRover for ranked knowledge and writes a cross-reference file that Claude's recall system can pick up
+3. **Zero workflow change** — you use `claude` exactly as before. The bridge runs in the background via Claude Code's hook system
+
+The result: Claude's memories are indexed, scored, and searchable alongside the rest of your project knowledge in ByteRover.
+
+## Prerequisites
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
+- Node.js 20+
+- [brv CLI](https://docs.byterover.dev/quickstart) installed and available on your `PATH`
+
+## Quick start
+
+### 1. Install the bridge
+
+```bash
+npm install -g @byterover/claude-bridge
+```
+
+### 2. Install hooks
+
+```bash
+brv-claude-plugin install
+```
+
+This adds four hooks to `~/.claude/settings.json`:
+
+- **PostToolUse(Write)** — triggers `brv-claude-plugin ingest` when Claude writes a memory file
+- **PostToolUse(Edit)** — triggers `brv-claude-plugin ingest` when Claude edits a memory file
+- **Stop** — triggers `brv-claude-plugin sync` after each turn to refresh cross-references
+- **UserPromptSubmit** — triggers `brv-claude-plugin recall` to query ByteRover with the user's prompt and inject relevant context before the model call
+
+Your existing settings and hooks are preserved. A backup is saved to `settings.json.brv-backup`.
+
+### 3. Verify
+
+```bash
+brv-claude-plugin doctor
+```
+
+You should see all checks passing:
+
+```
+brv-claude-plugin doctor
+
+  ✓ brv CLI — byterover-cli/2.5.0
+  ✓ Context tree — /path/to/project/.brv/context-tree
+  ✓ Claude settings — ~/.claude/settings.json
+  ✓ Bridge hooks — PostToolUse + Stop + UserPromptSubmit hooks found
+  ✓ Bridge executable — /usr/local/bin/brv-claude-plugin
+  ✓ Memory directory — ~/.claude/projects/-path-to-project/memory/
+
+All checks passed.
+```
+
+### 4. Use Claude normally
+
+```bash
+claude "fix the auth bug"
+```
+
+Memories are ingested into `.brv/context-tree/_cc/` automatically. No changes to your workflow.
+
+### 5. Uninstall (if needed)
+
+```bash
+brv-claude-plugin uninstall
+```
+
+Removes only bridge hooks. Your other hooks and settings are untouched.
+
+## Commands
+
+### `brv-claude-plugin install`
+
+Installs hooks into Claude Code's `~/.claude/settings.json`.
+
+| Option              | Description                                |
+| ------------------- | ------------------------------------------ |
+| `--dry-run`         | Show what would be written without saving  |
+| `--settings-path`   | Override path to Claude Code settings.json |
+
+Idempotent — safe to run multiple times. Deduplicates by checking for the `#brv-claude-plugin` marker in existing hooks.
+
+### `brv-claude-plugin uninstall`
+
+Removes bridge hooks from settings. Per-hook removal — if a matcher entry contains both a bridge hook and your own hook, only the bridge hook is deleted.
+
+| Option              | Description                                |
+| ------------------- | ------------------------------------------ |
+| `--settings-path`   | Override path to Claude Code settings.json |
+
+### `brv-claude-plugin ingest`
+
+Called by the PostToolUse hook. Reads hook JSON from stdin, parses the memory file, and sends it to `brv curate --detach`.
+
+- **Write tool**: reads content from `tool_input.content`
+- **Edit tool**: reads the file from disk (Edit only carries `old_string`/`new_string`)
+- Skips non-memory files, `MEMORY.md`, and `_brv_context.md`
+- Always exits 0 — never blocks Claude
+
+| Option    | Description              |
+| --------- | ------------------------ |
+| `--json`  | Output result as JSON    |
+
+### `brv-claude-plugin sync`
+
+Called by the Stop hook. Copies the context tree index from `.brv/context-tree/_index.md` into `_brv_context.md` in Claude's memory directory with a single pointer in `MEMORY.md`.
+
+- On success: writes context tree index with a guide note pointing to the full tree
+- If `_index.md` unavailable but `_brv_context.md` exists: preserves existing content
+- If `_index.md` unavailable and no existing file: writes a stub with "(sync pending)"
+- Runs async in the background — never blocks Claude
+
+| Option           | Description                              |
+| ---------------- | ---------------------------------------- |
+| `--json`         | Output result as JSON                    |
+| `--memory-dir`   | Override path to Claude memory directory |
+
+### `brv-claude-plugin recall`
+
+Called by the UserPromptSubmit hook. Reads the user's prompt from stdin, queries ByteRover with it, and returns targeted context as `additionalContext` that Claude sees before generating a response.
+
+- Runs **synchronously** — delays the model call until ByteRover responds (6s internal timeout, 8s hook timeout)
+- Skips trivially short prompts (< 5 chars)
+- If ByteRover query fails or times out, exits silently — prompt proceeds without context
+- Wraps results in `<byterover-context>` tags
+
+### `brv-claude-plugin doctor`
+
+Runs 6 diagnostic checks: brv CLI, context tree, settings file, installed hooks, bridge executable, and memory directory resolution.
+
+## How it works
+
+The bridge uses Claude Code's [hook system](https://docs.anthropic.com/en/docs/claude-code/hooks) to intercept memory operations without modifying Claude Code's source.
+
+### Recall flow (UserPromptSubmit hook)
+
+```
+User types: "fix the combo scoring bug"
+  │
+  ▼ UserPromptSubmit hook fires (before model call)
+brv-claude-plugin recall
+  │ brv query "fix the combo scoring bug" → targeted results
+  ▼
+Claude sees <byterover-context> as system reminder
+  (live, relevant to this specific prompt)
+```
+
+### Ingest flow (PostToolUse hook)
+
+```
+Claude writes ~/.claude/projects/.../memory/feedback_testing.md
+  │
+  ▼ PostToolUse hook fires, pipes JSON to stdin
+brv-claude-plugin ingest
+  │ Parse cc-ts frontmatter (name, description, type)
+  │ Map type → domain (_cc/user, _cc/feedback, _cc/project, _cc/reference)
+  ▼
+brv curate --detach --format json -- "context string"
+  │ Daemon queues curation (async, non-blocking)
+  ▼
+.brv/context-tree/_cc/feedback/testing.md
+  (enriched with tags, keywords, importance scoring)
+```
+
+### Sync flow (Stop hook)
+
+```
+Turn ends
+  │
+  ▼ Stop hook fires
+brv-claude-plugin sync
+  │ read .brv/context-tree/_index.md → copy to memory dir
+  ▼
+~/.claude/projects/.../memory/_brv_context.md
+  (context tree index + guide to full tree)
+```
+
+### Memory path resolution
+
+The bridge resolves Claude's memory directory using the same logic as Claude Code:
+
+1. `CLAUDE_COWORK_MEMORY_PATH_OVERRIDE` env var (full override)
+2. `autoMemoryDirectory` from settings (local → user, excluding project settings for security)
+3. `~/.claude/projects/<sanitized-canonical-git-root>/memory/`
+
+Git worktrees are resolved to their canonical root so all worktrees share one memory directory.
+
+### Multi-project support
+
+The bridge naturally supports multiple projects. Claude Code scopes memory per git repository, and ByteRover scopes its context tree per `.brv/` directory. Both use the same `cwd` from the hook input as their anchor:
+
+```
+/Users/x/project-a/        ← claude session here
+├── .git/                   ← Claude memory: ~/.claude/projects/-Users-x-project-a/memory/
+├── .brv/                   ← ByteRover tree: project-a/.brv/context-tree/
+└── src/
+
+/Users/x/project-b/        ← separate claude session here
+├── .git/                   ← Claude memory: ~/.claude/projects/-Users-x-project-b/memory/
+├── .brv/                   ← ByteRover tree: project-b/.brv/context-tree/
+└── src/
+```
+
+Each project's memories are ingested into its own context tree and synced back to its own memory directory. No cross-project leakage.
+
+**Important: initialize `.brv/` at the git root.** Claude Code resolves memory directories from the canonical git root. ByteRover walks up from `cwd` to find `.brv/`. When both are at the same level, everything maps correctly.
+
+If you initialize `.brv/` in a subdirectory instead of the git root, the bridge will encounter mismatches:
+
+```
+/monorepo/                  ← git root (Claude memory lives here)
+├── .git/
+├── frontend/
+│   └── .brv/               ← brv initialized here, not at git root
+└── backend/                ← sessions from here won't find .brv/
+```
+
+In this layout, Claude sessions from `/monorepo/backend/` would fail to reach the `.brv/` in `frontend/`. To fix this, initialize ByteRover at the git root:
+
+```bash
+cd /monorepo
+brv init                    # .brv/ at git root — matches Claude's project boundary
+```
+
+If you need separate context trees for subdirectories in a monorepo, initialize `.brv/` in each subdirectory and run `claude` from within that subdirectory (not from the monorepo root).
+
+### Hook identification
+
+Every stored hook command includes a `#brv-claude-plugin` shell comment marker. This marker — not the path text — is used by `install` (dedupe), `uninstall` (removal), and `doctor` (detection). A clone in any directory will work correctly.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Type check
+npm run typecheck
+
+# Build
+npm run build
+
+# Run in dev mode
+npm run dev -- doctor
+
+# Run built CLI
+node dist/cli.js doctor
+```
+
+### Testing locally
+
+1. Initialize a brv project: `cd /your/project && brv init`
+2. Build the bridge: `npm run build`
+3. Install hooks (dev mode): `node dist/cli.js install`
+4. Start a Claude session and make a few changes
+5. Check `.brv/context-tree/_cc/` for ingested memories
+6. Check `~/.claude/projects/.../memory/_brv_context.md` for synced context
+
+## Project structure
+
+```
+src/
+  cli.ts                      # Commander.js entry point
+  cc-frontmatter.ts           # Claude Code memory YAML frontmatter parser
+  memory-path.ts              # Full cc-ts memory path resolution (git root, worktrees, env vars)
+  stdin.ts                    # Read + validate JSON from stdin
+  bridge-command.ts           # Executable resolution + #brv-claude-plugin marker
+  schemas/
+    cc-hook-input.ts          # Zod schemas for PostToolUse and Stop hook input
+    cc-settings.ts            # Raw JSON read/write for settings.json (lossless)
+  commands/
+    install.ts                # Install hooks into settings.json (per-hook dedupe, backup)
+    uninstall.ts              # Remove bridge hooks (per-hook removal)
+    ingest.ts                 # PostToolUse handler — Write/Edit split, brv curate
+    sync.ts                   # Stop handler — _index.md copy, _brv_context.md, MEMORY.md pointer
+    recall.ts                 # UserPromptSubmit handler — live brv query with user prompt
+    doctor.ts                 # 6 diagnostic checks
+```
+
+## License
+
+[Elastic License 2.0 (ELv2)](./LICENSE)

package/dist/bridge-command.d.ts

@@ -0,0 +1,23 @@
+export declare const BRIDGE_HOOK_MARKER = "#brv-claude-plugin";
+/**
+ * Resolve the executable prefix for hook commands.
+ * Returns ONLY the executable part — callers append subcommand via buildHookCommand().
+ *
+ *   Production: "/usr/local/bin/brv-claude-plugin"
+ *   Dev:        "node /abs/path/to/dist/cli.js"
+ */
+export declare function resolveBridgeExecutable(): string;
+/**
+ * Build the full hook command string for a subcommand.
+ * Appends the marker as a trailing shell comment so isBridgeHook() works
+ * regardless of install path or directory name.
+ *
+ *   "/usr/local/bin/brv-claude-plugin ingest #brv-claude-plugin"
+ *   "node /tmp/bridge/dist/cli.js sync #brv-claude-plugin"
+ */
+export declare function buildHookCommand(subcommand: string): string;
+/**
+ * Check if a hook object was installed by this bridge.
+ * Matches on BRIDGE_HOOK_MARKER, not path text.
+ */
+export declare function isBridgeHook(hook: Record<string, unknown>): boolean;

package/dist/bridge-command.js

@@ -0,0 +1,103 @@
+import { accessSync, constants, existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+// ---------------------------------------------------------------------------
+// Marker — explicit shell comment suffix for hook identification.
+// Not derived from path text. Injected deliberately into every stored command.
+// ---------------------------------------------------------------------------
+export const BRIDGE_HOOK_MARKER = "#brv-claude-plugin";
+// ---------------------------------------------------------------------------
+// Executable resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the executable prefix for hook commands.
+ * Returns ONLY the executable part — callers append subcommand via buildHookCommand().
+ *
+ *   Production: "/usr/local/bin/brv-claude-plugin"
+ *   Dev:        "node /abs/path/to/dist/cli.js"
+ */
+export function resolveBridgeExecutable() {
+    const pkgRoot = findPackageRoot();
+    // Try production bin first
+    const pkgJson = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf-8"));
+    const bin = pkgJson.bin;
+    const binEntry = typeof bin === "string"
+        ? bin
+        : typeof bin === "object" && bin !== null
+            ? bin["brv-claude-plugin"]
+            : undefined;
+    if (binEntry) {
+        const resolved = resolve(pkgRoot, binEntry);
+        if (existsSync(resolved)) {
+            assertNoSpaces(resolved);
+            // Only return the bare path if it's actually executable (e.g. npm
+            // global install creates a proper shim with +x). tsc output and
+            // local dev builds are 0644, so we must prefix with node.
+            if (isExecutable(resolved)) {
+                return resolved;
+            }
+            return `node ${resolved}`;
+        }
+    }
+    // Dev fallback: dist/cli.js (never executable — always prefix with node)
+    const distCli = join(pkgRoot, "dist", "cli.js");
+    if (existsSync(distCli)) {
+        assertNoSpaces(distCli);
+        return `node ${distCli}`;
+    }
+    throw new Error(`Cannot resolve bridge executable. Run 'pnpm build' first, ` +
+        `or install the package globally.`);
+}
+/**
+ * Build the full hook command string for a subcommand.
+ * Appends the marker as a trailing shell comment so isBridgeHook() works
+ * regardless of install path or directory name.
+ *
+ *   "/usr/local/bin/brv-claude-plugin ingest #brv-claude-plugin"
+ *   "node /tmp/bridge/dist/cli.js sync #brv-claude-plugin"
+ */
+export function buildHookCommand(subcommand) {
+    const exe = resolveBridgeExecutable();
+    return `${exe} ${subcommand} ${BRIDGE_HOOK_MARKER}`;
+}
+/**
+ * Check if a hook object was installed by this bridge.
+ * Matches on BRIDGE_HOOK_MARKER, not path text.
+ */
+export function isBridgeHook(hook) {
+    return (typeof hook.command === "string" &&
+        hook.command.includes(BRIDGE_HOOK_MARKER));
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function findPackageRoot() {
+    // Walk up from this file to find package.json
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 10; i++) {
+        if (existsSync(join(dir, "package.json"))) {
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error("Cannot find package.json for brv-claude-plugin");
+}
+function isExecutable(filePath) {
+    try {
+        accessSync(filePath, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function assertNoSpaces(resolvedPath) {
+    if (/\s/.test(resolvedPath)) {
+        throw new Error(`Bridge install path contains spaces: "${resolvedPath}"\n` +
+            `Install brv-claude-plugin to a path without spaces, or use a symlink.`);
+    }
+}
+//# sourceMappingURL=bridge-command.js.map

package/dist/cc-frontmatter.d.ts

@@ -0,0 +1,21 @@
+declare const VALID_TYPES: readonly ["user", "feedback", "project", "reference"];
+export type CcMemoryType = (typeof VALID_TYPES)[number];
+export interface CcMemoryFrontmatter {
+    name: string;
+    description: string;
+    type: CcMemoryType;
+}
+export interface CcMemoryFile {
+    frontmatter: CcMemoryFrontmatter;
+    body: string;
+}
+/**
+ * Parse a Claude Code memory file into frontmatter + body.
+ * Returns null if the file is not a valid cc-ts memory file.
+ */
+export declare function parseCcMemoryFile(content: string): CcMemoryFile | null;
+/**
+ * Map cc-ts memory type to ByteRover context tree domain path.
+ */
+export declare function ccTypeToDomain(type: CcMemoryType): string;
+export {};

package/dist/cc-frontmatter.js

@@ -0,0 +1,51 @@
+import yaml from "js-yaml";
+// Match cc-ts/utils/frontmatterParser.ts line 123
+const FRONTMATTER_REGEX = /^---\s*\n([\s\S]*?)---\s*\n?/;
+const VALID_TYPES = ["user", "feedback", "project", "reference"];
+/**
+ * Parse a Claude Code memory file into frontmatter + body.
+ * Returns null if the file is not a valid cc-ts memory file.
+ */
+export function parseCcMemoryFile(content) {
+    const match = content.match(FRONTMATTER_REGEX);
+    if (!match)
+        return null;
+    const raw = match[1] || "";
+    const body = content.slice(match[0].length);
+    try {
+        const fm = yaml.load(raw);
+        if (!fm || typeof fm !== "object")
+            return null;
+        if (typeof fm.name !== "string")
+            return null;
+        if (typeof fm.type !== "string")
+            return null;
+        const type = fm.type;
+        if (!VALID_TYPES.includes(type))
+            return null;
+        return {
+            frontmatter: {
+                name: fm.name,
+                description: typeof fm.description === "string" ? fm.description : "",
+                type: type,
+            },
+            body,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Map cc-ts memory type to ByteRover context tree domain path.
+ */
+export function ccTypeToDomain(type) {
+    const map = {
+        user: "_cc/user",
+        feedback: "_cc/feedback",
+        project: "_cc/project",
+        reference: "_cc/reference",
+    };
+    return map[type];
+}
+//# sourceMappingURL=cc-frontmatter.js.map

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { program } from "commander";
+import { registerInstallCommand } from "./commands/install.js";
+import { registerUninstallCommand } from "./commands/uninstall.js";
+import { registerIngestCommand } from "./commands/ingest.js";
+import { registerSyncCommand } from "./commands/sync.js";
+import { registerRecallCommand } from "./commands/recall.js";
+import { registerDoctorCommand } from "./commands/doctor.js";
+program
+    .name("brv-claude-plugin")
+    .description("Native bridge between ByteRover context engine and Claude Code auto-memory")
+    .version("0.1.0");
+registerInstallCommand(program);
+registerUninstallCommand(program);
+registerIngestCommand(program);
+registerSyncCommand(program);
+registerRecallCommand(program);
+registerDoctorCommand(program);
+program.parse();
+//# sourceMappingURL=cli.js.map

package/dist/commands/doctor.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerDoctorCommand(program: Command): void;