Skip to content

USAGE.md

Latest commit

 

History

History
302 lines (216 loc) · 9.69 KB

USAGE.md

File metadata and controls

302 lines (216 loc) · 9.69 KB
Raw

cbm Usage Guide

中文使用指南

Unofficial community tool. cbm-tool is an independent community wrapper for codebase-memory-mcp. It is not maintained, endorsed, or supported by DeusData / the upstream project.

cbm is a convenience CLI wrapper around codebase-memory-mcp. It works on Linux, macOS, and Windows (PowerShell).

Quick Start

# Linux / macOS
cbm .

# Windows PowerShell
.\bin\cbm.ps1 .

Before you run cbm setup

cbm setup modifies editor configuration and rules files. To avoid surprises:

  1. Preview first. Run cbm setup --dry-run to see exactly which files would change and what would be written. --dry-run does not modify any files.
  2. Back up the listed files. The files that will be touched depend on which editors are detected (or selected with --editor). Make a manual copy of each file shown in the preview before running without --dry-run.
  3. Use --yes only after previewing. The confirmation prompt is skipped with --yes, so verify the dry-run output first.

Command Reference

Usage: cbm [OPTIONS] <repo_path>
       cbm setup [OPTIONS]
       cbm ui <status|start|stop>
       cbm update <self|cbm-tool|codebase-memory-mcp> [OPTIONS]
       cbm uninstall [OPTIONS]

Index a local repository using codebase-memory-mcp, configure local AI
editors, manage the local graph UI, or update / uninstall cbm-tool.

Index options:
  -m, --mode MODE        Index mode: full | moderate | fast | cross-repo-intelligence
                         (default: full)
  -p, --persistence      Save compressed artifact to .codebase-memory/graph.db.zst
  -t, --targets PROJECTS Comma-separated target projects for cross-repo-intelligence mode
  -l, --list             List indexed projects
  -o, --open             Ensure local MCP UI is up, open it in browser, and print URL
  -h, --help             Show this help
  -v, --version          Show version

UI commands:
  status                 Show UI health, port, and managed pid
  start                  Start a dedicated UI singleton if needed
  stop                   Stop the cbm-managed UI process only

Setup options:
  -e, --editor EDITOR    Configure only this editor (claude cursor codex cline windsurf)
  -u, --uninstall        Remove codebase-memory-mcp configuration and rules
  -y, --yes              Skip confirmation prompts
  -n, --dry-run          Show what would be done without making changes
      --rules-file PATH  Use a custom rules markdown file
  -h, --help             Show setup help

Uninstall options:
  -y, --yes              Skip confirmation prompts
  -n, --dry-run          Show what would be done without making changes
      --skip-setup       Do not run setup --uninstall
      --skip-mcp         Do not uninstall codebase-memory-mcp
      --purge-indexes    Pass -y to MCP uninstall (delete graph indexes)
  -h, --help             Show uninstall help

Index examples

# Index current directory with default settings
cbm .

# Fast index a project
cbm -m fast /path/to/repo

# Index with persistence
cbm -m moderate -p /path/to/repo

# Cross-repo intelligence
cbm -m cross-repo-intelligence -t project1,project2 /path/to/repo

# List indexed projects
cbm -l

# Ensure UI is up and open it in the browser
cbm -o

UI examples

# Check whether the graph UI is reachable
cbm ui status

# Start a dedicated UI singleton (independent of editor MCP reconnects)
cbm ui start

# Stop only the cbm-managed UI process (does not kill editor MCP)
cbm ui stop

The graph UI listens on http://127.0.0.1:9749/ by default (or ui_port from ~/.cache/codebase-memory-mcp/config.json). Editor-spawned MCP processes often restart and race for that port (ui.unavailable reason=in_use), which makes the UI disappear until you restart the editor.

cbm setup writes "args": ["--ui=false"] into editor MCP configs so those instances do not bind the UI port. Use cbm -o / cbm ui start for a stable UI singleton instead. After changing setup, reload the editor MCP connection.

Setup examples

# Configure all detected editors
cbm setup

# Configure only Cursor
cbm setup --editor cursor

# Preview changes without applying them
cbm setup --dry-run

# Skip confirmation
cbm setup --yes

# Use custom rules
cbm setup --rules-file ./my-rules.md

# Remove configuration from all detected editors
cbm setup --uninstall

# Preview uninstall
cbm setup --uninstall --dry-run

Windows PowerShell examples

# Index current directory with default settings
.\bin\cbm.ps1 .

# Fast index a project
.\bin\cbm.ps1 -Mode fast C:\path\to\repo

# Index with persistence
.\bin\cbm.ps1 -Mode moderate -Persistence C:\path\to\repo

# Cross-repo intelligence
.\bin\cbm.ps1 -Mode cross-repo-intelligence -Targets project1,project2 C:\path\to\repo

# List indexed projects
.\bin\cbm.ps1 -List

# Open local MCP UI (ensures the dedicated UI singleton is up)
.\bin\cbm.ps1 -Open

# UI status / start / stop
.\bin\cbm.ps1 ui status
.\bin\cbm.ps1 ui start
.\bin\cbm.ps1 ui stop

# Configure all detected editors
.\bin\cbm.ps1 setup

# Configure only Cursor
.\bin\cbm.ps1 setup -Editor cursor

# Preview changes
.\bin\cbm.ps1 setup -DryRun

# Remove configuration
.\bin\cbm.ps1 setup -Uninstall

# Preview / run full uninstall
.\bin\cbm.ps1 uninstall -DryRun
.\bin\cbm.ps1 uninstall -Yes

Version

cbm --version
cbm -v

cbm setup — Configure Local AI Editors

cbm setup connects supported editors to codebase-memory-mcp and installs a rule set that reminds the AI to prefer the knowledge graph when exploring code.

Editor MCP entries are written with "args": ["--ui=false"] so they do not bind the graph UI port. Use cbm -o / cbm ui start for a stable UI singleton.

cbm setup --uninstall removes the MCP server entry and the rule block that cbm setup previously added. Other editor settings and rules are left untouched.

Back up the listed files before running. cbm setup will touch the files shown in the table below for each detected or selected editor. Run cbm setup --dry-run first to see which files apply to your system.

Supported editors and the files they use:

Editor MCP config Rules file
Claude Code ~/.claude/.mcp.json ~/.claude/skills/codebase-memory.md
Cursor ~/.cursor/mcp.json ~/.cursorrules
Codex CLI ~/.codex/config.toml ~/.codex/AGENTS.md
Cline — ~/.clinerules
Windsurf — ~/.windsurfrules

Run cbm setup --dry-run to preview the changes before applying them.

cbm update — Update cbm-tool or codebase-memory-mcp

# Update cbm-tool itself from the latest GitHub release (SHA-256 checksum verified)
cbm update self

# Preview the self-update
cbm update self --dry-run

# Install the latest codebase-memory-mcp GitHub release
cbm update codebase-memory-mcp

# Install a specific codebase-memory-mcp release tag
cbm update codebase-memory-mcp v0.9.0
cbm update codebase-memory-mcp 0.9.0 --no-ui --dry-run

cbm update self downloads the latest cbm-tool release asset from GitHub, verifies its SHA-256 checksum, runs a syntax check, and then replaces the installed script. It only updates user-writable installs (the default one-liner path is ~/.local/bin). If cbm was installed by a package manager (for example Arch AUR), self-update is refused — use an AUR helper instead (yay -Syu cbm-tool, paru -Syu cbm-tool, etc.).

cbm update codebase-memory-mcp [VERSION] installs from the upstream GitHub release (not the floating main branch). Omit VERSION for latest; pass v0.9.0 or 0.9.0 to pin a tag. Use --ui (default) or --no-ui to select the variant.

cbm uninstall — Fully uninstall cbm-tool

# Preview full uninstall
cbm uninstall --dry-run

# Uninstall cbm, editor setup, and codebase-memory-mcp (keep graph indexes)
cbm uninstall --yes

# Keep MCP installed
cbm uninstall --yes --skip-mcp

# Also delete graph indexes via upstream MCP uninstall -y
cbm uninstall --yes --purge-indexes

Order of operations:

  1. cbm setup --uninstall (unless --skip-setup)
  2. codebase-memory-mcp uninstall -n by default, or -y with --purge-indexes
  3. Remove ~/.local/bin/cbm (Windows: cbm.ps1 + cbm.cmd)
  4. On Unix, remove # >>> cbm-tool PATH >>> markers from shell rc files

One-liners are documented in INSTALL.md.

Index Modes

Mode Description
full Full index with similarity/semantic edges (default)
moderate Filtered files + similarity/semantic edges
fast Filtered files, no similarity/semantic edges
cross-repo-intelligence Match routes/channels across indexed projects

Requirements

All platforms

  • codebase-memory-mcp CLI in your PATH

Linux / macOS only

  • Bash (macOS ships with 3.2; newer versions via Homebrew also work)
  • column (used by --list; usually preinstalled)
  • Browser opener: xdg-open (Linux) or open (macOS) for --open

Windows only

  • PowerShell 5.1 or PowerShell 7+
  • No extra tools required; JSON handling uses built-in ConvertTo-Json / ConvertFrom-Json

Notes

  • On all platforms, cbm resolves <repo_path> to an absolute path before sending it to codebase-memory-mcp.
  • A warning is printed if the target directory does not contain a .git folder.
  • On Windows, if the execution policy blocks .ps1 scripts, run with powershell -ExecutionPolicy Bypass .\bin\cbm.ps1 ... or adjust your policy.
  • cbm setup appends its rules inside <!-- CBM_CODEBASE_MEMORY_RULES_START --> / <!-- CBM_CODEBASE_MEMORY_RULES_END --> markers so repeated runs update the same block instead of duplicating it.