ccc-tools

ccc-plugin

Claude Code plugin for cocoindex-code integration: semantic retrieval via MCP, automatic index freshness via git hooks, and one-command project onboarding.

What this plugin does

• /ccc-onboard <path> — initialize ccc on a project, apply standard excludes, build the index, register the MCP server with Claude Code, install git hooks for automatic refresh, and write a local .claude/CLAUDE.md hint file. Single command, six idempotent steps.
• /ccc-reset <path> — drop and rebuild a project's ccc index. Use after settings changes, device switches (CPU ↔ CUDA), or index corruption. Destructive, requires confirmation.
• /ccc-reindex <path> — force an incremental re-index. Use when you want an immediate refresh without waiting for a git hook.
• bin/ccc-install-hook <repo> <ccc-root> — standalone installer for post-commit, post-merge, post-checkout hooks that fire a non-blocking ccc index in the background. Called automatically by ccc-onboard.

Why these commands exist

cocoindex-code is a capable semantic retrieval engine but ships as a standalone CLI. Integrating it into a Claude Code workflow on a real codebase requires five separate steps (init, exclude tuning, initial index, MCP registration with a sh -c "cd PATH && exec ccc mcp" wrapper because ccc mcp refuses to start outside an initialized project, git hooks for freshness). This plugin wraps all five into one command and adds freshness automation.

Background and benchmark methodology: ~/ai/wiki/tools/semantic-retrieval-test-noise.md.

Standard exclude preset

The ccc-onboard script applies these exclusions out of the box (on top of cocoindex-code's defaults):

• Tests — **/tests/**, **/test/**, **/*Test.php, **/*.test.ts, **/*.spec.ts, **/test_*.py, **/*_test.py
• Plans and docs — **/docs/plans/**, **/plans/**, **/docs/**
• Lockfiles — **/package-lock.json, **/composer.lock, **/Cargo.lock, **/yarn.lock
• Terraform state — **/.terraform
• Python envs — **/.venv, **/venv, **/env, **/__pycache__, **/.pytest_cache, **/coverage
• Minified assets — **/*.min.js, **/*.min.css
• Laravel compiled views — **/storage/framework/views/**
• ML embedding data — **/*embeddings*.json, **/similarity_matrix*.json, **/test_outputs/**

The test exclusion is the important one. Measured on a 14-case php-src benchmark: including tests in the index drops recall@10 from 1.00 to 0.79. Tests are written in symptom language ("crash when X happens") which semantically matches bug-report queries better than the actual source file's mechanism-language. If you include tests, they crowd out the implementation in top-N results. See the wiki entry for the full write-up.

Installation

# Clone this repo
git clone https://github.com/<you>/ccc-plugin.git ~/ai/ccc-plugin

# Register the marketplace with Claude Code
claude plugin marketplace add ~/ai/ccc-plugin

# Install the plugin
claude plugin install ccc-tools@ccc-plugin

Prerequisites:

• cocoindex-code installed (uv tool install --upgrade cocoindex-code --prerelease explicit --with "cocoindex>=1.0.0a24")
• ccc doctor reports green
• Claude Code v2.x or later (for plugin marketplace support)

Usage

Inside a Claude Code session:

/ccc-onboard ~/my-project

The agent runs the shell script, reports the six-step result, verifies MCP connectivity, runs a sanity query, and summarizes the state. After that, ~/my-project is queryable via the ccc-my-project MCP tool, the index auto-refreshes on commits, and there's a local hint file at ~/my-project/.claude/CLAUDE.md teaching future Claude Code sessions when to prefer semantic search over grep.

Environment variables

• CCC_BENCH_CORPUS_DIR — directory where /ccc-bench looks for *-eval.yaml corpora and writes timestamped scorecards to history/. Defaults to $HOME/ai/retrieval-bench. Set this if you keep your benchmark corpora somewhere else. The --corpus-dir CLI flag overrides both the env var and the default.

Repo layout

.
├── .claude-plugin/marketplace.json       # marketplace manifest
└── plugins/ccc-tools/
    ├── .claude-plugin/plugin.json        # plugin manifest
    ├── commands/
    │   ├── ccc-onboard.md
    │   ├── ccc-reset.md
    │   └── ccc-reindex.md
    └── bin/
        ├── ccc-onboard                   # bash, ~130 lines
        └── ccc-install-hook              # bash, ~45 lines

Commands reference their bash counterparts via ${CLAUDE_PLUGIN_ROOT}/bin/..., so the plugin is self-contained and relocatable.

License

MIT. See LICENSE.