Skip to content

cianfhoghlaim/cianchosaint / .agents/skills/ccc

<!--
CIANCHOSAINT wholesale-copy of cianfhoghlaim/cianfhoghlaim @ main branch.

Original: cianfhoghlaim/cianfhoghlaim (per the openspec/changes/cianchosaint-repo-bootstrap-v2/specs/cianchosaint-bootstrap-v2/spec.md).
Migrated to cianchosaint: 2026-08-23
Licence: BUSL-1.1 (per LICENSE.md)

Wholesale-copied from cianfhoghlaim/cianfhoghlaim@ccc/SKILL.md.
-->
---
name: ccc
description: "Semantic code search via CocoIndex Code (ccc CLI). Use when code search, file/directory summary lookup, or concept-guide lookup is needed, when indexing the codebase after changes, or when the user asks about ccc, cocoindex-code, or the codebase index. RETAINED by user direction past the 2026-07-15 retirement; canonical replacement is the v1 App `codebase_indexing` at cocoindex/codebase_indexing.py."
---

> **DEPRECATION NOTICE (2026-07-06):** This skill was scheduled to retire
> 2026-07-15 but is retained by user direction. The replacement (CocoIndex
> v1 App `codebase_indexing`) lives at
> `cocoindex/codebase_indexing.py`. Use the v1 App for new
> work; this skill is retained for the `bun run ccc:init`,
> `bun run ccc:index`, and `bun run ccc:search` developer shortcuts.

# ccc - Semantic Code Search & Indexing

> **Deprecation banner (2026-06-16, retires 2026-07-15):** The v1-native
> replacement is `cocoindex/codebase_indexing.py` (a
> CocoIndex v1 App + Dagster asset group). It uses the same embedding
> model (`BAAI/bge-m3`) and the same LanceDB HNSW index that the rest of
> the data lakehouse uses, and it is registered in the Dagster UI under
> the `codebase` asset group. The `bun run ccc:index` alias now delegates
> to the v1 App, and `bun run ccc:v1:search "<query>"` replaces
> `ccc search "<query>"`. The original `ccc` CLI is kept on disk for the
> 30-day deprecation window only. Reference:
> `openspec/changes/docs-skills-consolidation-pipeline/`.
>
> **Round 8 phase 1 (2026-06-23):** The v1 App gained a **code-graph
> companion** (`codebase_graph` v1 App + `codebase_code_graph` Dagster
> asset). 7 node types (`File`, `Function`, `Class`, `Method`,
> `Module`, `Interface`, `Variable`) + 7 edge types (`CONTAINS`,
> `IMPORTS`, `CALLS`, `EXTENDS`, `IMPLEMENTS`, `USES`, `DEFINES`).
> 29+ language detection via
> `cocoindex/chunking/languages.py` (ported from
> `libraries/codeolas/chunking/languages.py`). Use the v1 Python API
> `search_code_graph(file_path=..., node_type=...)` to query the
> graph table.
>
> **Round 7 phase 2 (2026-06-24):** Four v1 companions for the
> *infrastructure* surface, all in
> `orchestration/defs/infrastructure_assets.py`:
>
> - `api_endpoints` — FastAPI / Hono / TanStack Start / Convex HTTP
>   routes → `api_endpoints` LanceDB. Query helper:
>   `search_api_endpoints(query, framework=None, method=None, limit=20)`.
> - `filesystem_layout` — every directory up to depth 4 with per-dir
>   file-type histogram → `filesystem_layout` LanceDB. Query helper:
>   `search_filesystem(query, min_depth=None, limit=10)`.
> - `storage_backends` — 9 backend kinds (lancedb / duckdb / ducklake /
>   postgres / garage / r2 / d1 / kv / iceberg) → `storage_backends`
>   LanceDB. Query helper:
>   `search_storage(query, kind=None, limit=20)`.
> - `config_files` — 12 config kinds (compose / mise / package /
>   pyproject / turbo / wrangler / env / k8s / pulumi / dg / github /
>   justfile) → `config_files` LanceDB. Query helper:
>   `search_config(query, kind=None, limit=15)`.
>
> **Round 7 phase 3 (2026-06-24):** Two v1 embedding Apps in
> `orchestration/defs/unified_embedding_assets.py`
> (group `embedding`):
>
> - `unified_embeddings` — v1 port of
>   `agents/tuatha/crypteolas/cocoindex_flows/unified_embedding.py:unified_embedding_flow`.
>   Reads any DuckDB connection (default:
>   `crypteolas_catalog.docs.scraped_documents`), chunks with
>   RecursiveSplitter (markdown) or paragraph+char fallback, embeds
>   with BGE-M3, writes to the `unified_embeddings` LanceDB table.
>   Query helper: `unified_search(query, source_types=None, protocol=None)`.
> - `code_embeddings` — v1 port of the v0 `code_embedding_flow`.
>   Walks `UNIFIED_CODE_ROOT` (default:
>   `agents/tuatha/crypteolas/storage/data/code/`) for `*.py`/`*.ts`/`*.tsx`/
>   `*.js`/`*.jsx`/`*.rs`/`*.go`/`*.sol`, chunks with
>   `RecursiveSplitter(detect_code_language)`, embeds with BGE-M3,
>   writes to the `code_embeddings` LanceDB table. Query helper:
>   `code_search(query, language=None, chunk_type=None)`.

`ccc` is the CLI for CocoIndex Code, providing semantic search over the current codebase and index management.

## Ownership

The agent owns the `ccc` lifecycle for the current project — initialization, indexing, and searching. Do not ask the user to perform these steps; handle them automatically.

- **Initialization**: If `ccc search` or `ccc index` fails with an initialization error (e.g., "Not in an initialized project directory"), run `ccc init` from the project root directory, then `ccc index` to build the index, then retry the original command.
- **Index freshness**: Keep the index up to date by running `ccc index` (or `ccc search --refresh`) when the index may be stale — e.g., at the start of a session, or after making significant code changes (new files, refactors, renamed modules). There is no need to re-index between consecutive searches if no code was changed in between.
- **Installation**: If `ccc` itself is not found (command not found), refer to [management.md](references/management.md) for installation instructions and inform the user.

## Searching the Codebase

To perform a semantic search:

```bash
ccc search <query terms>
```

The query should describe the concept, functionality, or behavior to find, not exact code syntax. For example:

```bash
ccc search database connection pooling
ccc search user authentication flow
ccc search error handling retry logic
```

### Filtering Results

- **By language** (`--lang`, repeatable): restrict results to specific languages.

  ```bash
  ccc search --lang python --lang markdown database schema
  ```

- **By path** (`--path`): restrict results to a glob pattern relative to project root. If omitted, defaults to the current working directory (only results under that subdirectory are returned).

  ```bash
  ccc search --path 'src/api/*' request validation
  ```

### Pagination

Results default to the first page. To retrieve additional results:

```bash
ccc search --offset 5 --limit 5 database schema
```

If all returned results look relevant, use `--offset` to fetch the next page — there are likely more useful matches beyond the first page.

### Working with Search Results

Search results include file paths and line ranges. To explore a result in more detail:

- Use the editor's built-in file reading capabilities (e.g., the `Read` tool) to load the matched file and read lines around the returned range for full context.
- When working in a terminal without a file-reading tool, use `sed -n '<start>,<end>p' <file>` to extract a specific line range.

### Following Hints in Search Output

Search results are a mixed ranking of code chunks, per-file/dir summaries, and (when configured) curated concept guides — all scored against the same query. Two kinds of hit come with a follow-up command embedded in the output:

- `[summary]` — a file or directory summary. Read with `ccc describe <path>`.
- `[guide]` — a curated concept guide. Read with `ccc guide <slug>`.

When a hit carries one of these tags, follow the hint: the synthesised text is usually a faster read than chasing through individual files. Conversely, do **not** run `ccc describe .` or `ccc guide` proactively as a triage step — let search rank what's relevant and act on what it returns.

## Describing Files and Directories

Per-file and per-directory summaries (when configured for the project) condense each file's public API, contracts, and role into a short markdown block. They are typically faster to consult than reading the source.

```bash
ccc describe src/auth/session.py        # one file
ccc describe src/auth/                  # directory: summary + children tree
ccc describe .                          # project root overview
```

Use `describe` when you already know the path you want; let `ccc search` find paths for you when you don't.

## Concept Guides

Some projects configure cross-cutting concept guides in `.cocoindex_code/guides.yml` — synthesised markdown documents for architectural topics that span many files (e.g. memoization, plugin-SDK boundary, channel routing). Each guide names canonical files, end-to-end flow, and contracts/invariants.

```bash
ccc guide                               # list available guides + descriptions
ccc guide <slug>                        # print one guide
```

Discovery is search-driven: a relevant guide will surface in `ccc search` results tagged `[guide]` with a `ccc guide <slug>` hint. Run `ccc guide` (no args) only when first orienting in an unfamiliar codebase or when the user explicitly asks for the guide list — not as a routine first step.

### Authoring `guides.yml` Interactively

When the user wants to add or improve concept guides, collaborate on the slug list rather than dumping a finished YAML. Good guide candidates are **named subsystems the codebase obviously has** — cross-cutting lifecycles, registration/dispatch protocols, end-to-end data paths. Single-file or symbol-specific topics do not warrant a guide; per-file summaries already cover those.

Recommended flow:

1. **Survey the codebase.** Use `ccc describe .` and a few likely subdirectory summaries to enumerate the project's subsystems and inter-edge boundaries.
2. **Propose candidates.** Suggest 5–10 slugs with one-line descriptions, framed to name the canonical starting file or directory for each topic. Show them to the user as a list.
3. **Iterate.** Ask which to keep, drop, rename, or merge. Surface non-obvious dependencies (`deps:`) so a higher-level guide can cite a lower-level one rather than restate it. Cycles are rejected at load time.
4. **Write the YAML.** Add the agreed entries to `.cocoindex_code/guides.yml` (creating the file if absent). Confirm `defaults.enabled: true` and that the project's summary feature is enabled — guides require summaries.
5. **Generate.** Run `ccc index` to drive the per-guide agent loop and produce `<slug>.md` files under `.cocoindex_code/guides/`. Re-run after editing descriptions to refresh.

Schema:

```yaml
defaults:
  enabled: true                     # disables all guides when false
  model: openai/gpt-5.4-nano        # falls back to summary.model when omitted
  session_budget: 200
  max_logical_depth: 3
  max_turns_per_session: 18

guides:
  - slug: memoization                          # [a-z0-9][a-z0-9-]*
    description: |
      What this guide covers, framed for the reader.
      Name the canonical starting files (e.g. "start with src/cache.py").
    deps: [other-slug]                         # optional; must not cycle
    max_turns_per_session: 28                  # optional per-entry overrides
```

A multi-line description is fine and often clearer than one terse sentence — the description seeds the guide-generation agent's question, so concrete file/directory anchors pay off.

## Settings

To view or edit embedding model configuration, include/exclude patterns, or language overrides, see [settings.md](references/settings.md).

## Management & Troubleshooting

For installation, initialization, daemon management, troubleshooting, and cleanup commands, see [management.md](references/management.md).

## Cianfhoghlaim integration

CCC is the **primary code discovery tool** for every Cianfhoghlaim
agent — per the root `AGENTS.md` instruction, "always use
ccc before grep/find". The polyglot monorepo is indexed
continuously into `.cocoindex_code/target_sqlite.db`
(~35 MB) via `bun run ccc:index` (incremental refresh,
<10s on changed files; full rebuild ~2-5 min via
`bun run ccc:init && bun run ccc:index`).

The CCC MCP server is wired in `opencode.json` as
`cocoindex-code` (`ccc mcp`), exposing
`cocoindex-code_search(query, limit, languages, paths)` to
every agent. The tool returns ranked
`[file_path, line_range, score]` tuples — semantic,
embedding-based, not keyword.

**4 canonical CocoIndex flow examples** for the Cianfhoghlaim
workloads:

```python
# 1. Text embedding with LanceDB (curriculum corpus)
flow = Flow("text_embedding")
    .source(TextEmbedding.from_markdown("./docs/**/*.md"))
    .transform(LanceDB("curriculum_embeddings"))

# 2. Document knowledge graph (LLM-extracted → Neo4j)
flow = Flow("docs_kg")
    .source(DocumentSource("./docs/**/*.md"))
    .transform(LLMExtraction(model="deepseek-v4-pro",
                             schema=KnowledgeGraphSchema))
    .sink(Neo4jSink("bolt://localhost:7687"))

# 3. Code embedding (tree-sitter chunker → LanceDB)
flow = Flow("code_index")
    .source(CodeSource("./**/*.py", chunker="tree-sitter"))
    .transform(TextEmbedding("code-embeddings"))
    .sink(LanceDBSink("./.cocoindex_code"))

# 4. Multi-format indexing with ColPali (PDF/PNG/JPG → Qdrant)
flow = Flow("visual_docs")
    .source(MultiFormatSource("./docs/**/*.{pdf,png,jpg}"))
    .transform(ColPaliEmbedding())
    .sink(QdrantSink("http://localhost:6333"))
```

**CCC + Cognee complementarity** is the key architectural
insight: CCC searches code (returns implementation files);
Cognee searches docs (returns architecture + patterns). An
agent asking "find how BAML extraction is implemented" gets
code from CCC and architecture from Cognee, then merges.

**Performance**:

| Operation | Scope | Time |
|:--|:--|:--|
| `ccc:index` (incremental) | Changed files only | <10s |
| `ccc:index` (full rebuild) | Entire monorepo | ~2-5 min |
| `ccc:search` | Semantic query | <1s |
| `ccc mcp` server | Continuous | Background |

See `references/cianfhoghlaim-integration/CCC_INTEGRATION.md` for
the full 187-line reference: the current setup, the MCP
config, the index update policy (incremental + full rebuild
+ scheduled via `bun run turbo ccc:index`), the search
API, the per-agent indexing workflow, the 4 flow examples
(text embedding, docs KG, code embedding, ColPali), the
CCC + Cognee dual-search diagram, the index file structure
(`.cocoindex_code/{cocoindex.db, settings.yml, target_sqlite.db}`),
the performance table, and the cross-references.

## Cianfhoghlaim ccc-ready index health

The round-1 `cocoindex_readiness_audit` (327 lines, dated
2026-06-06) confirmed the CCC index is **already
ccc-ready for the docs corpus** and the gap is frontmatter,
not indexing. The index is **1.4 GB**, indexes **1,743
`.md` files** (because `**/*.md` is in `include_patterns`),
and was rebuilt on the audit day — no refresh needed.

**7 sample queries** all returned `docs/` files with strong
relevance (0.66-0.79 score range, frequently in the top
position):

| Query | Top hit | Score |
|:--|:--|--:|
| "BAML extraction patterns for Irish education" | `docs/meaisínfhoghlaim/model-ecosystem.md` | 0.774 |
| "Dagster asset partition definition" | `docs/data_engineering/dagster-comprehensive.md` | 0.701 |
| "Convex schema design" | `openspec/.../convex/schema/spec.md` (spec beats docs) | 0.721 |
| "Firecrawl pipeline configuration" | `docs/old/...firecrawl-openapi-research.md` (dup w/ bonneagar, tuatha) | 0.688 |
| "ADK agent routing" | `docs/context/.../google-adk.md` (docs outrank code) | 0.721 |
| "Celtic educational MMO x402 micropayments" | `docs/legacy/tuatha/celtic_mmo.md` (4 dups across dirs) | 0.787 |
| "Gaeltacht language planning areas geoJSON" | `docs/data_engineering/data-sources.md` (4 dups) | 0.741 |

**3 pass / 2 gap findings**: pass on indexing, search
returns docs/, docs outrank code for concepts,
docs-exclusive content is searchable, index freshness;
gap on YAML frontmatter (0 of 7 sampled files) and
duplicate content (4+ copies of same content across
`docs/`, `docs/old/`, `docs/bonneagar/`, `docs/legacy/tuatha/`,
`docs/legacy/tuatha/agents/tuatha/`).

**The "ccc-clean" frontmatter convention** (the round-1
recommendation that became the `agent-docs-patterns`
skill's 12-field schema): `title` (anchor at position 0),
`description` (dense one-sentence summary), `domain`
(controlled vocabulary), `entities` (class/function
names that match code identifiers), `ccc_query_hints` (the
exact natural-language queries users would type — the
highest-ROI field), `status` (active/draft/archived),
`related_skills`, `related_code` (file paths create
embedding adjacency with actual code chunks), `related_docs`.

**The 9-point summary table** scored: docs/ indexed (Pass),
semantic search returns docs/ (Pass), docs outrank code
for concepts (Pass), docs-only content searchable (Pass),
index freshness (Pass), YAML frontmatter (Gap — 0/7),
duplicate content (Gap — 4+ copies), index size
(Healthy — 1.4 GB), docs/ isolation filterable (Pass).

**5 audit recommendations**: (1) no index refresh needed,
(2) add frontmatter starting with `ccc_query_hints` for
highest ROI, (3) deduplicate before consolidating (remove
`docs/old/` + nested `docs/legacy/tuatha/agents/tuatha/` first), (4) create
a `guides.yml` for cross-cutting concept guides
("BAML extraction end-to-end", "Tuath MMO x402 payment
flow"), (5) standardize on `--path docs/` for agent
queries that need documentation context, (6) run
`ccc index` after each major consolidation batch.

See `references/health/cocoindex_readiness_audit.md` for
the full 327-line audit: the executive summary, the
indexing + search internals, the 7-query test results
(each with top-5 hits + scores + assessment), the index
health check, the frontmatter audit (0/7 sampled files),
the 6-point "ccc-clean" convention, the 9-point summary
table, the 6 recommendations, and the appendix of test
commands.

---

## Appendix A: Alternative engines

The Cianfhoghlaim-canonical code search is `ccc` (this skill). Two
alternative engines are tracked:

### ChunkHound (now removed from `.agents/skills/`)

ChunkHound (2024-2025) is an open-source local-first code
search engine. It used to ship as a separate skill
(`.agents/skills/chunkhound/SKILL.md`) but was consolidated
into this skill. Key ChunkHound capabilities the Cianfhoghlaim team
liked (and which `ccc` v1 does NOT replicate):

- **Two-layer architecture**: base RAG layer (cAST chunking +
  semantic + regex search) + orchestration layer (multi-hop
  exploration).
- **Multi-hop exploration**: BFS traversal discovering
  architectural relationships across the codebase, with a
  5-second convergence detection to prevent infinite loops.
- **Adaptive token budgets**: 30k-150k token budgets based on
  repository size, so small projects don't get buried in noise
  and large monorepos still get sufficient context.
- **29+ language support** (incl. PDF via PyMuPDF).
- **Dual-store**: DuckDB primary + LanceDB experimental.
- **Performance**: 4.3 point gain in Recall@5 on RepoEval,
  2.67 point gain in Pass@1 on SWE-bench, ~5ms query latency
  with HNSW, 10-100x faster indexing via native git bindings.

**When to consider ChunkHound over ccc**:

- The codebase is a fresh project (no Dagster + CocoIndex v1
  pipeline yet) and you need a code search engine *now*.
- You need the multi-hop exploration pattern (ccc v1 has
  flat semantic search; ChunkHound has iterative BFS).
- You need a self-contained, no-cloud-dependencies
  installation. ChunkHound runs locally; ccc needs the
  Dagster + CocoIndex v1 + LanceDB + (optionally) Lance
  Cloud infrastructure.

**How to install ChunkHound if needed** (Cianfhoghlaim teams don't
ship it as a skill anymore):

```bash
uv tool install chunkhound
cd /path/to/project
chunkhound index
chunkhound search "def.*authenticate"
```

The ChunkHound `.chunkhound.json` configuration pattern
(local-first, no cloud) is the right default for any
air-gapped or compliance-constrained project.

### Other engines (not in Cianfhoghlaim)

- **Sourcegraph** — enterprise code intelligence, paid.
- **livegrep** — regex-only, no embeddings.
- **Zoekt** — gitlab's regex engine.
- **Code Search (Google internal)** — not available externally.

The Cianfhoghlaim stack uses `ccc` (canonical) or `ChunkHound`
(per-project self-hosted) for all production code search.

## See also

- **[`../INDEXING_AND_COGNITION.md`](../INDEXING_AND_COGNITION.md)** — Consolidated setup + MCP reference for both `ccc` and `cognee`. Includes current state (index size, chunk count, container status), first-time setup, daily-use commands, MCP tool inventory for both, dual-search workflow, and troubleshooting matrix. Read this when an agent or team member asks "how do I set up ccc?", "how do I start cognee?", or "what MCP tools are available?".
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall