@mayurdluffy/cbm-cli 1.0.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mayurdluffy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,377 @@
+<h1 align="center">Codebase Memory Manager</h1>
+
+[![GitHub release](https://img.shields.io/github/v/release/mayurdluffy/cbm-cli?logo=github)](https://github.com/mayurdluffy/cbm-cli/releases)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://img.shields.io/github/actions/workflow/status/mayurdluffy/cbm-cli/publish.yml?branch=main&label=Publish%20to%20npm&logo=github)](https://github.com/mayurdluffy/cbm-cli/actions/workflows/publish.yml)
+
+---
+
+## Why CBM?
+
+[`codebase-memory-mcp`](https://github.com/DeusData/codebase-memory-mcp) is a beast. It indexes your entire codebase into a queryable knowledge graph — functions, call chains, HTTP routes, cross-service links — and answers structural queries in under a millisecond after initial indexing. It cuts agent token usage by **10–100x** depending on query type and supports **158 languages** via tree-sitter, with deep semantic analysis for 12 major languages.
+
+But getting it installed, keeping the binary updated, configuring a dozen different agents, and sharing the indexed graph with your team involves a lot of moving parts.
+
+**CBM handles all of that for you.**
+
+Think of CBM as the project-level manager that wraps the engine. One command to install the binary. One command to index your repo. One command for your teammates to jump in. No manual config file editing. No "works on my machine."
+
+---
+
+## What CBM Does
+
+1. **Installs & manages** the `codebase-memory-mcp` binary for you.
+2. **Indexes your project** into a shareable `graph.db.zst` artifact.
+3. **Auto-configures 11 coding agents** with an interactive menu — no copy-pasting JSON.
+
+---
+
+## Limitations
+
+- **Best for structural queries** — call chains, symbol discovery, blast radius analysis
+- **Not for semantic questions** — "is this algorithm correct?" still requires reading code
+- **Tiny projects** (<20 files) — grep may be faster than indexing
+- **Stale graphs** — re-index after large refactors with `cbm re-index`
+- **Config/non-code files** — `.env`, Dockerfiles not indexed
+- **Answer quality** — 83% vs 92% for raw file exploration ([arxiv paper](https://arxiv.org/abs/2603.27277))
+
+---
+
+## Installation
+
+### Via npm (Recommended)
+
+```bash
+npm install -g @mayurdluffy/cbm-cli
+```
+
+### Via npx (No install)
+
+```bash
+npx @mayurdluffy/cbm-cli install
+```
+
+### Via curl (macOS / Linux)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/mayurdluffy/cbm-cli/main/install.sh | bash
+```
+
+### Windows
+
+```bash
+npm install -g @mayurdluffy/cbm-cli
+# or
+npx @mayurdluffy/cbm-cli install
+```
+
+### Security
+
+The `codebase-memory-mcp` binary is closed-source but each release is signed, checksummed, and scanned. All processing is local — your code never leaves your machine. See [upstream SECURITY.md](https://github.com/DeusData/codebase-memory-mcp/blob/main/SECURITY.md).
+
+---
+
+## Uninstalling
+
+### Remove the `codebase-memory-mcp` binary only
+
+```bash
+cbm uninstall
+```
+
+This removes the binary, cache, and config — but keeps `cbm` installed.
+
+### Remove `cbm` entirely
+
+**npm:**
+```bash
+npm uninstall -g @mayurdluffy/cbm-cli
+```
+
+**curl (macOS / Linux):**
+```bash
+npm uninstall -g @mayurdluffy/cbm-cli
+```
+The curl installer uses npm under the hood, so the uninstall command is the same.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install the engine + select your agents
+cbm install
+
+# 2. Index your project and create a shareable graph
+cd ~/projects/my-awesome-api
+cbm build
+
+# 3. Commit the graph so your team skips re-indexing
+git add .codebase-memory/graph.db.zst
+git commit -m "Add shareable codebase graph"
+git push
+
+# 4. Teammates clone and go
+cbm use
+```
+
+---
+
+## CLI at a Glance
+
+```text
+@lucifer:~$ cbm
+
+   ██████╗ ██████╗ ███╗   ███╗
+  ██╔════╝ ██╔══██╗████╗ ████║
+  ██║      ██████╔╝██╔████╔██║
+  ██║      ██╔══██╗██║╚██╔╝██║
+  ╚██████╗ ██████╔╝██║ ╚═╝ ██║
+   ╚═════╝ ╚═════╝ ╚═╝     ╚═╝
+
+  Codebase Memory Manager
+  - Supercharge your agentic coding — without the token bleed
+
+  Usage: cbm [command]
+
+  Setup:
+    install (i)      Install codebase-memory-mcp + select agents
+    update (up)      Update to latest version
+    uninstall        Remove from system
+    version (-V, -v)  Show version info
+    kill (k)         Stop running server
+    help (-h, --help)  Show help
+
+  Project:
+    build (b)        Index + create shareable graph + select agents
+    use (u)          Use shared graph (no indexing needed)
+    re-index (ri)    Force re-index + fresh artifact
+    status (s)       Show project graph status
+
+  Options:
+    --version, -V, -v  Show version
+    --help, -h         Show help
+    --yes, -y          Skip prompts
+    --agents, -a       Specify agents (comma-separated)
+
+  Raw CLI:
+    cbm <cmd>    Any codebase-memory-mcp CLI command
+    Example: cbm cli search_graph '{"name_pattern": ".*"}'
+
+  Supported Agents:
+    Claude Code, Codex CLI, Gemini CLI, Zed, OpenCode,
+    Antigravity, Aider, KiloCode, VS Code, OpenClaw, Kiro
+
+  Notes:
+    • Aider: No native MCP config — use ./cbm-aider wrapper
+    • Antigravity: Shares Gemini CLI config file
+
+  Workflow:
+    cbm install → select agents → cbm build → select agents → git push
+```
+
+---
+
+## Commands
+
+### Setup
+
+| Command | Alias | Description |
+|---|---|---|
+| `cbm install` | `i` | Install `codebase-memory-mcp` + select agents |
+| `cbm update` | `up` | Update to latest version |
+| `cbm uninstall` | | Remove from system |
+| `cbm version` | `-V`, `-v` | Show version info |
+| `cbm kill` | `k` | Stop running server |
+| `cbm help` | `-h`, `--help` | Show help |
+
+### Project
+
+| Command | Alias | Description |
+|---|---|---|
+| `cbm build` | `b` | Index + create shareable `graph.db.zst` + select agents |
+| `cbm use` | `u` | Use shared graph (no indexing needed) |
+| `cbm re-index` | `ri` | Force re-index + fresh artifact |
+| `cbm status` | `s` | Show project graph status |
+
+### Raw CLI
+
+Any command not recognized by `cbm` is passed to `codebase-memory-mcp`:
+
+```bash
+cbm cli search_graph '{"name_pattern": ".*Handler"}'
+cbm cli get_architecture '{}'
+cbm config get auto_index
+cbm --version
+```
+
+---
+
+## Non-Interactive / CI Mode
+
+Use `--yes` to skip prompts and select all agents, or `--agents` to specify a comma-separated list:
+
+```bash
+# Install and configure all agents without prompting
+cbm install --yes
+
+# Build and configure only Claude Code (1) and OpenCode (5)
+cbm build --agents 1,5
+
+# Use shared graph and configure only VS Code (9)
+cbm use --agents 9
+```
+
+**Agent numbers:**
+1. Claude Code
+2. Codex CLI
+3. Gemini CLI
+4. Zed
+5. OpenCode
+6. Antigravity
+7. Aider
+8. KiloCode
+9. VS Code
+10. OpenClaw
+11. Kiro
+
+---
+
+## Interactive Agent Selection
+
+CBM features an **interactive arrow-key menu** for selecting coding agents:
+
+```
+Configure which agents for this project?
+
+↑↓ navigate · space toggle · a all · n none · enter confirm
+
+❯ ○ Claude Code
+  ○ Codex CLI
+  ● Zed          ← toggled
+  ○ OpenCode
+  ● VS Code      ← toggled
+  ...
+```
+
+---
+
+## Workflows
+
+### Owner Workflow
+
+```bash
+cd ~/projects/my-api
+cbm build        # Index + create artifact
+git add .codebase-memory/graph.db.zst
+git commit -m "Add codebase graph"
+git push
+```
+
+### Teammate Workflow
+
+```bash
+git clone <repo>
+cd <repo>
+cbm use          # No indexing needed!
+# Restart agent and code
+```
+
+### Refactor Workflow
+
+```bash
+cd ~/projects/my-api
+cbm re-index     # Fresh graph after big changes
+git add .codebase-memory/graph.db.zst
+git commit -m "Update graph after refactor"
+git push
+```
+
+---
+
+## What Gets Created
+
+```
+my-awesome-api/
+├── .codebase-memory/
+│   ├── cbm-server.sh      ← MCP wrapper (committed)
+│   └── graph.db.zst       ← Shareable graph (committed)
+├── .opencode/              ← if OpenCode selected
+│   └── opencode.json      ← OpenCode config (committed)
+├── .claude/                ← if Claude Code selected
+│   └── .mcp.json          ← Claude Code config (committed)
+├── .vscode/                ← if VS Code selected
+│   └── mcp.json           ← VS Code config (committed)
+├── CONVENTIONS.md         ← Aider conventions (if Aider selected)
+├── cbm-aider              ← Aider wrapper (if Aider selected)
+├── .gitignore             ← Ignores live DB
+└── .gitattributes         ← Prevents merge conflicts
+```
+
+---
+
+## Cross-Platform
+
+| OS | Status |
+|---|---|
+| macOS | ✅ Fully supported |
+| Linux | ✅ Fully supported |
+| Windows | ✅ Supported (npm, PowerShell, Git Bash, WSL) |
+| CI/CD | ✅ Non-interactive fallback with `--yes` / `--agents` |
+
+---
+
+## Pro Tips
+
+### 1. The Graph Travels With the Code
+
+Commit `graph.db.zst` and CI can use it:
+
+```yaml
+# .github/workflows/ci.yml
+- name: Use codebase graph
+  run: |
+    npm install -g @mayurdluffy/cbm-cli
+    cbm use --yes
+    # run structural tests
+```
+
+### 2. Keep It Updated
+
+After large refactors, run `cbm re-index` and commit the new `graph.db.zst` so teammates stay in sync.
+
+### 3. Aider Users
+
+Aider has no native MCP config file. Use the generated `./cbm-aider` wrapper to launch Aider with `codebase-memory-mcp` attached.
+
+---
+
+## Troubleshooting
+
+| Issue | Fix |
+|---|---|
+| `command not found: cbm` | `npm install -g @mayurdluffy/cbm-cli` or use `npx @mayurdluffy/cbm-cli` |
+| `codebase-memory-mcp not found` | `cbm install` |
+| Agent doesn't see tools | Restart agent; check `cbm status` |
+| `graph.db.zst` missing | Run `cbm build` |
+| Server won't start | `cbm kill` then restart agent |
+| Stale graph | `cbm re-index` and commit |
+| Interactive menu hangs in CI | Use `cbm <cmd> --yes` or `--agents N,M` |
+
+---
+
+## Contributing
+
+This is a community project. Contributions, issues, and feedback are welcome!
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+<p align="center">
+  <strong>Built with ❤️ for teams that move fast.</strong><br>
+  <a href="https://github.com/mayurdluffy/cbm-cli">GitHub</a> •
+  <a href="https://www.npmjs.com/package/@mayurdluffy/cbm-cli">npm</a>
+</p>

package/bin/cbm.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// =============================================================================
+// cbm — The Ultimate codebase-memory-mcp Manager (Node.js)
+// =============================================================================
+// Cross-platform: macOS · Linux · Windows
+// Interactive arrow-key agent selection
+// Supports all 11 coding agents that codebase-memory-mcp supports
+// Project-level scope only
+// =============================================================================
+
+const { main } = require("../lib/index");
+
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});

package/lib/agents.js

@@ -0,0 +1,290 @@
+const fs = require("fs");
+const path = require("path");
+const { C, log } = require("./logger");
+const { AGENTS } = require("./constants");
+const { getHomeDir } = require("./system");
+
+const SERVER_WRAPPER = `#!/usr/bin/env bash
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+export CBM_CACHE_DIR="$SCRIPT_DIR"
+exec codebase-memory-mcp serve
+`;
+
+const AIDER_CONVENTIONS = `# Codebase Memory MCP — Project Conventions
+
+This project uses \`codebase-memory-mcp\` for code intelligence.
+
+## Available MCP Tools
+
+- \`index_repository\` — Index or re-index the project
+- \`search_graph\` — Structural search (regex name patterns, label filters)
+- \`trace_path\` — BFS call graph traversal (who calls what)
+- \`get_architecture\` — Overview: languages, packages, routes, hotspots
+- \`detect_changes\` — Map git diff to affected symbols + blast radius
+- \`query_graph\` — Cypher-like graph queries (read-only)
+- \`search_code\` — Graph-augmented grep over indexed files
+- \`get_code_snippet\` — Read source by qualified name
+- \`manage_adr\` — Architecture Decision Records
+- \`semantic_query\` — Vector search across the graph
+- \`dead_code\` — Find functions with zero callers
+- \`list_projects\` — List indexed projects
+
+## Workflow
+
+1. Say "Index this project" to build the knowledge graph (or run \`cbm build\`)
+2. Ask structural questions: "What calls ProcessOrder?", "Find all HTTP routes"
+3. Use \`trace_path\` for call chains, \`search_graph\` for symbol discovery
+
+## Tips
+
+- Use \`search_graph(name_pattern=".*PartialName.*")\` to find exact qualified names
+- Add \`project="PROJECT_NAME"\` parameter when querying
+- Run \`get_graph_schema\` first to understand the graph structure
+`;
+
+const AIDER_WRAPPER = `#!/usr/bin/env bash
+# CBM Aider wrapper — launches Aider with codebase-memory-mcp
+# Usage: ./cbm-aider [other-aider-args...]
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+export CBM_CACHE_DIR="$SCRIPT_DIR/.codebase-memory"
+exec aider --mcp-server "codebase-memory-mcp serve" "$@"
+`;
+
+function createWrapper(dir) {
+  const isWin = process.platform === "win32";
+  const wrapperPath = path.join(dir, "cbm-server.sh");
+
+  fs.writeFileSync(wrapperPath, SERVER_WRAPPER, { mode: 0o755 });
+
+  if (isWin) {
+    const cmdPath = path.join(dir, "cbm-server.cmd");
+    fs.writeFileSync(
+      cmdPath,
+      '@echo off\nset "CBM_CACHE_DIR=%~dp0"\ncodebase-memory-mcp serve\n',
+    );
+  }
+
+  return wrapperPath;
+}
+
+function createAiderConventions(projectDir) {
+  const conventionsPath = path.join(projectDir, "CONVENTIONS.md");
+  fs.writeFileSync(conventionsPath, AIDER_CONVENTIONS);
+  log.ok(`Created ${C.dim}CONVENTIONS.md${C.reset} for Aider`);
+}
+
+function createAiderWrapper(projectDir) {
+  const isWin = process.platform === "win32";
+  const aiderWrapperPath = path.join(projectDir, "cbm-aider");
+
+  fs.writeFileSync(aiderWrapperPath, AIDER_WRAPPER, { mode: 0o755 });
+  log.ok(`Created ${C.dim}cbm-aider${C.reset} wrapper script`);
+
+  if (isWin) {
+    const cmdPath = path.join(projectDir, "cbm-aider.cmd");
+    fs.writeFileSync(
+      cmdPath,
+      '@echo off\nset "CBM_CACHE_DIR=%~dp0.codebase-memory"\naider --mcp-server "codebase-memory-mcp serve" %*\n',
+    );
+  }
+}
+
+function generateConfig(agent, cmd) {
+  const configs = {
+    toml: () => `[mcp_servers.codebase-memory]\ncommand = "${cmd}"\nargs = []\n`,
+
+    jsonc: () =>
+      `{\n  // codebase-memory-mcp\n  "context_servers": {\n    "codebase-memory": {\n      "command": "${cmd}",\n      "args": []\n    }\n  }\n}\n`,
+
+    "opencode-json": () =>
+      JSON.stringify(
+        {
+          mcp: {
+            "codebase-memory": {
+              type: "local",
+              command: [cmd],
+              enabled: true,
+            },
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+
+    "vscode-json": () =>
+      JSON.stringify(
+        {
+          servers: {
+            "codebase-memory": {
+              command: cmd,
+              args: [],
+            },
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+
+    "openclaw-json": () =>
+      JSON.stringify(
+        {
+          mcp: {
+            servers: {
+              "codebase-memory": {
+                command: cmd,
+                args: [],
+                transport: "stdio",
+              },
+            },
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+
+    "kilo-jsonc": () =>
+      JSON.stringify(
+        {
+          mcp: {
+            "codebase-memory": {
+              type: "local",
+              command: [cmd],
+              enabled: true,
+            },
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+
+    yml: () =>
+      `# Aider Configuration\nmcp_servers:\n  codebase-memory:\n    command: "${cmd}"\n    args: []\n`,
+
+    json: () =>
+      JSON.stringify(
+        {
+          mcpServers: {
+            "codebase-memory": {
+              command: cmd,
+              args: [],
+            },
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+  };
+
+  return (configs[agent.format] || configs.json)();
+}
+
+function createAgentConfig(agentIdx, projectDir) {
+  const agent = AGENTS[agentIdx];
+
+  if (agent.name === "Aider") {
+    createAiderConventions(projectDir);
+    createAiderWrapper(projectDir);
+    log.warn(
+      `${agent.name}: ${C.yellow}No native MCP config — use ${C.cyan}./cbm-aider${C.yellow} to launch${C.reset}`,
+    );
+    return;
+  }
+
+  const configPath = path.join(projectDir, agent.config);
+  const configDir = path.dirname(configPath);
+  const wrapperPath = path.join(
+    projectDir,
+    ".codebase-memory",
+    "cbm-server.sh",
+  );
+  const cmd = wrapperPath.replace(/\\/g, "/");
+
+  if (configDir !== projectDir) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+
+  if (agent.sharesConfigWith) {
+    return handleSharedConfig(agent, configPath, cmd);
+  }
+
+  const content = generateConfig(agent, cmd);
+  fs.writeFileSync(configPath, content);
+  log.ok(`${agent.name}: ${C.dim}${agent.config}${C.reset}`);
+}
+
+function handleSharedConfig(agent, configPath, cmd) {
+  if (!fs.existsSync(configPath)) {
+    const content = generateConfig(agent, cmd);
+    fs.writeFileSync(configPath, content);
+    log.ok(`${agent.name}: ${C.dim}${agent.config}${C.reset}`);
+    return;
+  }
+
+  try {
+    const existing = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    if (!existing.mcpServers) existing.mcpServers = {};
+    if (!existing.mcpServers["codebase-memory"]) {
+      existing.mcpServers["codebase-memory"] = { command: cmd, args: [] };
+      fs.writeFileSync(
+        configPath,
+        JSON.stringify(existing, null, 2) + "\n",
+      );
+      log.ok(
+        `${agent.name}: ${C.dim}merged into ${agent.config}${C.reset} (shared with ${agent.sharesConfigWith})`,
+      );
+    } else {
+      log.ok(
+        `${agent.name}: ${C.dim}already configured in ${agent.config}${C.reset}`,
+      );
+    }
+  } catch {
+    const content = generateConfig(agent, cmd);
+    fs.writeFileSync(configPath, content);
+    log.ok(`${agent.name}: ${C.dim}${agent.config}${C.reset}`);
+  }
+}
+
+function createGlobalConfig(agent) {
+  const globalDir = agent.globalDir();
+  fs.mkdirSync(globalDir, { recursive: true });
+
+  if (agent.name === "Aider") {
+    const conventionsPath = path.join(getHomeDir(), "CONVENTIONS.md");
+    if (!fs.existsSync(conventionsPath)) {
+      createAiderConventions(getHomeDir());
+      log.ok(`Global: ${agent.name} (CONVENTIONS.md)`);
+    }
+    return;
+  }
+
+  const cmd = "codebase-memory-mcp";
+  let configFile;
+
+  const globalPaths = {
+    toml: () => path.join(globalDir, "config.toml"),
+    jsonc: () => path.join(globalDir, "settings.json"),
+    "opencode-json": () => path.join(globalDir, "opencode.json"),
+    "vscode-json": () => path.join(globalDir, "mcp.json"),
+    "openclaw-json": () => path.join(globalDir, "openclaw.json"),
+    "kilo-jsonc": () => path.join(globalDir, "kilo.jsonc"),
+    json: () => path.join(globalDir, "mcp.json"),
+    yml: () => path.join(globalDir, "mcp.json"),
+  };
+
+  configFile = (globalPaths[agent.format] || globalPaths.json)();
+
+  if (fs.existsSync(configFile)) return;
+
+  const content = generateConfig({ ...agent, format: agent.format }, cmd);
+  fs.writeFileSync(configFile, content);
+  log.ok(`Global: ${agent.name}`);
+}
+
+module.exports = {
+  createWrapper,
+  createAgentConfig,
+  createGlobalConfig,
+  createAiderConventions,
+  createAiderWrapper,
+  generateConfig,
+};