cbm-projects

Documentation site · 简体中文

About

cbm-projects is a cross-platform, bilingual plugin host and project manager for codebase-memory-mcp. It gives developers one stable command for registering repositories, maintaining code indexes, configuring supported coding agents, and diagnosing local MCP installations.

The Go core stays small and agent-independent. Index operations and agent integration are provided by executable plugins through the versioned cbm-projects.plugin/v1 JSON protocol, so future workflows can be added in Go, Python, Node.js, PowerShell, or any language that can read stdin and write stdout. Codex is the recommended experience, while Claude Code, Cursor, Gemini CLI, OpenCode, and other clients remain supported through the upstream official installer.

The project favors explicit, auditable behavior: existing MCP installations are never silently replaced, remote plugins require SHA-256 verification, newly installed plugins start disabled, and destructive index rebuilds happen only when requested.

This is an independent community project. It is not affiliated with or endorsed by DeusData.

Install

macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/pikachuprogrammer01/cbm-projects/main/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/pikachuprogrammer01/cbm-projects/main/install.ps1 | iex

The installer verifies the release archive against checksums.txt. It detects codebase-memory-mcp before installing anything. If MCP is missing, the interactive setup offers to run the upstream official installer; if MCP already exists, it is never downloaded or upgraded implicitly.

For an auditable install, download and review install.sh or install.ps1, then run it locally. Release assets and checksums are published at GitHub Releases.

Quick start

cbm-projects setup
cbm-projects set my-project /absolute/path/to/repository
cbm-projects ensure my-project
cbm-projects status all
cbm-projects doctor

Use either language explicitly:

cbm-projects help --lang en
cbm-projects help --lang zh-CN
cbm-projects help rebuild --lang en

Language precedence is --lang, CBM_PROJECTS_LANG, saved configuration, system locale, then English.

Commands

Command	Purpose
setup	Detect/install MCP, preview agent configuration, import projects, and offer the Codex plugin
list, path, set, remove	Manage the portable project registry
status, ensure, refresh, rebuild	Route index operations through the MCP provider plugin
open / app	Open a registered project in Codex when available
agents check|install|manual	Preview, apply, or print official agent configuration
plugin ...	Manage process plugins
sources	Show source, license, version, path, and checksum provenance
doctor	Validate configuration, projects, plugins, MCP, and agent setup

auto_index is offered during setup and defaults to off. Registered repositories are indexed with ensure; the upstream auto_watch=true setting maintains ready indexes without destructive rebuilds.

Agent support

The agents-official plugin calls the upstream codebase-memory-mcp install command. That installer remains the source of truth for supported clients and their MCP entries, instructions, skills, and lifecycle hooks. Codex is recommended, but it is not required.

The optional Codex plugin adds a management skill only. It intentionally does not declare another MCP server.

codex plugin marketplace add pikachuprogrammer01/cbm-projects --ref v0.1.0
codex plugin add cbm-projects@cbm-projects

Start a new Codex task after installing or updating the plugin.

Plugin model

Plugins are independent processes, not Go shared objects. Each plugin contains plugin.json and an executable that receives one cbm-projects.plugin/v1 JSON request on stdin and returns one JSON response on stdout. stderr is reserved for diagnostics.

{
  "apiVersion": "cbm-projects.plugin/v1",
  "name": "example",
  "version": "1.0.0",
  "description": "Example extension",
  "entrypoint": "cbm-plugin-example",
  "platforms": ["*"],
  "commands": ["hello"],
  "hooks": ["doctor.check"],
  "permissions": ["process:execute"],
  "source": "https://github.com/example/plugin",
  "license": "MIT"
}

Lifecycle events are setup.detect, setup.configure, project.added, project.removed, index.before, index.after, and doctor.check. Normal hook failures are fail-open; provider command failures are fail-closed.

cbm-projects plugin install ./my-plugin
cbm-projects plugin install https://example.test/plugin.zip --sha256 <hex>
cbm-projects plugin enable my-plugin
cbm-projects plugin list
cbm-projects plugin run example hello

Newly installed third-party plugins start disabled. Review the permissions printed by plugin install, then enable the plugin explicitly. Plugins are discovered from the configured plugin directory, next to the host executable, PATH-related plugin directories, and system plugin directories documented in docs/PLUGIN_API.md.

Plugins run with the user's operating-system permissions. Manifest permissions are an explicit disclosure and approval surface, not an OS sandbox. Install only code you trust.

Development

Requires Go 1.24 or newer.

make test
make build
./scripts/build-release.sh v0.1.0 dist

The release builder produces macOS, Linux, and Windows archives for AMD64 and ARM64 plus SHA-256 checksums.

License and provenance

cbm-projects is licensed under MIT. codebase-memory-mcp is a separate MIT-licensed upstream project. See THIRD_PARTY_NOTICES.md and run cbm-projects sources for exact links.