vera-ccc-tools

Purpose

Expose CocoIndex Code (ccc) as native Pi/Vera tools so semantic code search and index management are available without going through raw bash.

Registered tools

• ccc_search — semantic code search via ccc search
• ccc_index — build or refresh the project index via ccc index
• ccc_init — initialize the current project for CocoIndex Code via ccc init
• ccc_doctor — run CocoIndex diagnostics via ccc doctor

Project index status (ccc status) is not a tool. It is surfaced as an always-on ccc-status segment at the end of the system prompt, refreshed once per user turn.

Design notes

• Uses the installed ccc executable from PATH
• Executes commands in the current project cwd
• Returns truncated text output suitable for the model context
• Keeps semantic search as a first-class tool while leaving exact file lookup to fd / rg / read
• Forces UTF-8 on spawned ccc processes (PYTHONIOENCODING/PYTHONUTF8) so non-ASCII index content is not mangled when captured on Windows

Gitignore sync

Index exclusion is kept aligned with the project's effective .gitignore, because ccc's own gitignore matcher is unreliable on Windows. git is the source of truth: git ls-files -o -i --exclude-standard --directory -z yields the ignored set (platform-uniform forward-slash paths), which is converted to **/<path>/** globs and merged into .cocoindex_code/settings.yml exclude_patterns.

• Sync runs before ccc_search (when refresh_index is on — the default), at the start of ccc_index, and after a foreground ccc_init. ccc_search is the hot path, so newly-ignored files drop out of results on the next search rather than waiting for an explicit re-index.
• Idempotent: a sidecar (.cocoindex_code/.vera-gitignore-sync.json) tracks the patterns this tool injected. Each sync reconciles only that set, preserving ccc defaults and any user-added patterns. No disk write when the ignored set is unchanged.
• Fallback: a non-git directory, missing git, or an empty ignored set leaves exclude_patterns at ccc's defaults.
• Cost: one git ls-files call (~tens of ms) per refreshing search.

Implemented in src/gitignore-sync.ts.

Non-goals

• replacing rg / fd for exact text or path lookup
• destructive reset / daemon stop controls
• direct MCP transport management

External dependencies

• ccc installed and available on PATH
• CocoIndex daemon health for index/search operations
• initialized project for ccc_search unless ccc_index or ccc_init has been run
• git (optional) — enables gitignore sync; when absent, exclusion falls back to ccc defaults

Smoke

• npm run smoke
• from project root: node packages/vera-ccc-tools/scripts/smoke.mjs

Loaded through agent/settings.json as ./packages/vera-ccc-tools.